Skip to main content

Wrapper for the Petfinder API

Project description

Petpy - Python Wrapper for the Petfinder API

Documentation Status Build Status Coverage Status codecov Codacy Badge Dependencies

:cat2: :dog2: :rooster: :rabbit2: :racehorse:


petpy is easily installed through pip.

pip install petpy

The library can also be cloned or downloaded into a location of your choosing and then installed using the file per the following:

git clone
cd petpy
python install

Examples and usage

An account must first be created with Petfinder to receive an API and secret key. The API and secret key will be used to grant access to the Petfinder API, which lasts for 3600 seconds, or one hour. After the authentication period ends, you must re-authenticate with the Petfinder API. The following are some quick examples for using petpy to get started. More in-depth tutorials for petpy and some examples of what can be done with the library, please see the More Examples and Tutorials section below.

Authenticating with the Petfinder API

Authenticating the connection with the Petfinder API is done at the same time the Petfinder class is initialized.

pf = Petfinder(key=key, secret=secret)

The following are some quick examples for getting started with petpy and the Petfinder API.

Finding animal types

# All animal types and their relevant data.
all_types = pf.animal_types()

# Returning data for a single animal type
dogs = pf.animal_types('dog')

# Getting multiple animal types at once
cat_dog_rabbit_types = pf.animal_types(['cat', 'dog', 'rabbit'])

Getting animal breeds for available animal types

cat_breeds = pf.breeds('cat')
dog_breeds = pf.breeds('dog')

# All available breeds or multiple breeds can also be returned.

all_breeds = pf.breeds()
cat_dog_rabbit = pf.breeds(types=['cat', 'dog', 'rabbit'])

The breeds method can also be set to coerce the returned JSON results into a pandas DataFrame by setting the parameter return_df = True.

cat_breeds_df = pf.breeds('cat', return_df = True)
all_breeds_df = pf.breeds(return_df = True)

Finding available animals on Petfinder

The animals() method returns animals based on specified criteria that are listed in the Petfinder database. Specific animals can be searched using the animal_id parameter, or a search of the database can be performed by entering the desired search criteria.

# Getting first 20 results without any search criteria
animals = pf.animals()

# Extracting data on specific animals with animal_ids

animal_ids = []
for i in animals['animals'][0:3]:

animal_data = pf.animals(animal_id=animal_ids)

# Returning a pandas DataFrame of the first 150 animal results
animals = pf.animals(results_per_page=50, pages=3, return_df=True)

Getting animal welfare organizations in the Petfinder database

Similar to the animals() method described above, the organizations() method returns data on animal welfare organizations listed in the Petfinder database based on specific criteria, if any. In addition to a general search of animal welfare organizations, specific organizational data can be extracted by supplying the organizations() method with organization IDs.

# Return the first 1,000 animal welfare organizations as a pandas DataFrame

organizations = pf.organizations(results_per_page=100, pages=10, return_df=True)

# Get organizations in the state of Washington

wa_organizations = pf.organizations(state='WA')

More Examples and Tutorials


A series of IPython notebooks that introduce and explore some of the functionality and possible uses of the petpy library. The notebooks can also be launched interactively with binder by clicking the "launch binder" badge.


The following are longer usage examples and tutorials that have been posted to external media websites such as



  • Python >= 3.6
  • requests >= 2.18.4
  • Although not strictly required to use petpy, the pandas library is needed for returning the results as a DataFrame.

About is one of the largest online, searchable databases for finding a new pet online. The database contains information on over 14,000 animal shelters and adoption organizations across North America with nearly 300,000 animals available for adoption. Not only does this make it a great resource for those looking to adopt their new best friend, but the data and information provided in Petfinder's database makes it ideal for analysis.


  • ma755 - Fixed several functions that use an animal parameter and implementing checks for exceeding the Petfinder API limit.
  • ljlevins - Found and fixed an error with the distance parameter used in the organizations API endpoint.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

petpy-2.3.1.tar.gz (14.0 kB view hashes)

Uploaded Source

Built Distributions

petpy-2.3.1-py3.8.egg (30.7 kB view hashes)

Uploaded Source

petpy-2.3.1-py2.py3-none-any.whl (16.6 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page