Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Ruby gem wrapper around the Petfinder API
branch: master
Failed to load latest commit information.
lib Bump version to 1.0.2
spec Add sanitized description to pet
.gitignore Converting over to excon and nokogiri, use custom xml mapper
.travis.yml Travis test on Rubies 1.9-2.0 Bump version to 1.0.2
Gemfile Update gem dependencies and versions
Gemfile.lock Bump version to 1.0.2
LICENSE.txt Update license and readme Update readme for paging results example
Rakefile Converting over to excon and nokogiri, use custom xml mapper
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.