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
Copyright
Copyright (c) 2010-2020 Eric Hutzelman. See LICENSE for details.