Petfinder

Ruby gem wrapper for the Petfinder API v2.0.

NOTE: The gem to support v1.0 of the API can be found on the v1 branch, but be warned that Petfinder will be deprecating this v1 API in early 2020.

Installation

Add this line to your application's Gemfile:

gem 'petfinder'

And then execute:

$ bundle

Or install it yourself as:

$ gem install petfinder

Get your API key

Get your Petfinder API key at: https://www.petfinder.com/developers

Usage

Instantiate a client

petfinder = Petfinder::Client.new('your_api_key', 'your_api_secret')

or configure once

Petfinder.configure do |config|
  config.api_key = 'your_api_key'
  config.api_secret = 'your_api_secret'
end
petfinder = Petfinder::Client.new

Examples

Return a list of dogs in the "90210" zip code (with pagination)

A hash of parameters can be passed to this method, but none are required. You can find the full set of allowable parameters here: Petfinder animals endpoint documentation.

animals, pagination = petfinder.animals(type: 'dog', location: '90210', page: 1)

animals.first.name
# => "Tyra"
animals.first.photos.first.full
# => "https://dl5zpyw5k3jeb.cloudfront.net/photos/pets/47027518/2/?bust=1578168103"
animals.first.organization_id
# => "CA2350"

pagination.count_per_page
# => "20"
pagination.total_pages
# => "8853"

Return a list of organizations (with pagination)

A hash of parameters can be passed to this method, but none are required. You can find the full set of allowable parameters here: Petfinder organizations endpoint documentation.

organizations, pagination = petfinder.organizations({ location: '90210', limit: 5 })

organizations.first.name
# => "STAR Eco Station"

pagination.count_per_page
# => "5"
pagination.total_count
# => "265"
pagination.total_pages
# => "53"

Return information about the organization (shelter) with id "CA2350"

organization = petfinder.organization('CA2350')

organization.name
# => "Promise 4 Paws"

organization.address.city
# => "San Juan Capistrano"

Return a list of animal types

types = petfinder.types

types.first.name
# => "Dog"

types.first.colors
# => ["Brown", "Black", "Yellow"]

Return a list of breeds for a given animal type

breeds = petfinder.breeds('dog')

breeds.length
# => 275

breeds.first.name
# => "Affenpinscher"

Handling errors

A Petfinder::Error exception will be raised if the response fails with a bad response. This exception contains a hash of error information returned by Petfinder.

animals, pagination = petfinder.animals(type: 'invalid_type')
# => Petfinder::Error (Invalid Request: The request contains invalid parameters.)

rescue Petfinder::Error => exception

exception.data
# => {"type"=>"https://www.petfinder.com/developers/v2/docs/errors/ERR-00002/", "status"=>400, "title"=>"Invalid Request", "detail"=>"The request contains invalid parameters.", "invalid-params"=>[{"in"=>"query", "path"=>"type", "message"=>"invalid_type is not a valid animal type."}]}

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request