Skip to content
Ruby gem wrapper around the Petfinder API
Find file
Latest commit 9aee0b8 @ehutzelman Bump gem versions
Failed to load latest commit information.
lib Bump version to 1.0.3
spec Inspect methods added to Pet and Shelter.
.gitignore Converting over to excon and nokogiri, use custom xml mapper
.rspec use bundler, update to rspec 2
.travis.yml Bump version to 1.0.3
Gemfile Update gem dependencies and versions
LICENSE.txt Update license and readme Update readme for paging results example
Rakefile Adds a console rake task
petfinder.gemspec Update gem dependencies and 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.