Skip to content
Ruby gem wrapper around the Petfinder API
Find file
Latest commit 9aee0b8 Oct 7, 2015 @ehutzelman Bump gem versions


Gem Version Build Status Code Climate

Ruby gem wrapper for the Petfinder API.


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:


Instantiate a client

petfinder ='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'
petfinder =


Return a list of dogs in the "90210" zip code

pets = petfinder.find_pets('dog', '90210')
# => "25"
# => "Petey"

# => "CA123"

Returning paged results

petfinder.find_pets('dog', 77057, count: 25)

# page 2
petfinder.find_pets('dog', 77057, count: 25, offset: 25)

# page 3
petfinder.find_pets('dog', 77057, count: 25, offset: 50)

# page 4
petfinder.find_pets('dog', 77057, count: 25, offset: 75)

Return information about the shelter with id "CA123"

shelter = petfinder.shelter('CA123')
# => "Melrose Place SPCA"

Other available methods

# Valid animal types: barnyard, bird, cat, dog, horse, pig, reptile, smallfurry
breeds = petfinder.breeds(animal_type)

# Options available: animal, breed, size, sex, location, shelterid
pet = petfinder.random_pet(options)
pet =

# Options available: breed, size, sex, age, offset, count
pets = petfinder.find_pets(animal_type, location, options)

# Options available: status, offset, count
pets = shelter_pets(shelter_id, options)

# Options available: name, offset, count
shelters = petfinder.find_shelters(location, options)
shelters = petfinder.find_shelters_by_breed(animal_type, breed)

shelter = petfinder.shelter(shelter_id)


  • Implement use of security token when Petfinder requires it
  • Support paging for results


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


Copyright (c) 2010-2013 Eric Hutzelman. See LICENSE for details.

Something went wrong with that request. Please try again.