petpy - Python Wrapper of the Petfinder API¶
Petpy is an unofficial Pythonwrapper of the Petfinder API for interacting with Petfinder’s database of animals and animal welfare organizations.
Getting a Petfinder API and Secret Key¶
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.
petpy is best installed through
pip install petpy
For those of you who prefer it, the library can also be cloned or downloaded into a location of your choosing and then
installed using the
setup.py script per the following:
git clone email@example.com:aschleg/petpy.git cd petpy python setup.py install
Connecting and using the Petfinder API is as straightforward as initializing the
Petfinder() class. The
following are several examples for extracting data from the Petfinder database and interacting with the Petfinder API.
Authenticating with the Petfinder API¶
Authentication to the Petfinder API occurs when the
Petfinder() class is initialized.
import petpy pf = Petfinder(key=API_key, secret=API_secret)
Calls to the API to extract data can now be made!
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'])
Get Breeds of 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)
Getting animals on Petfinder¶
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_ids.append(i['id']) 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')
Tutorials and Examples¶
- Introduction to petpy
- Download 45,000 Cat Images in 6.5 Minutes with petpy and multiprocessing
- Please note the following notebook is still based on the legacy version of the Petfinder API and thus are not fully
representative of the functionality and methods of the most recent version of
petpyand the Petfinder API. These are currently being updated to reflect the new version of
- Please note the following notebook is still based on the legacy version of the Petfinder API and thus are not fully representative of the functionality and methods of the most recent version of
- Download Pure Breeds Cat Images with petpy for Deep Neural Network training
- Provided by contributor ma755
The following are longer usage examples and tutorials that have been posted to external media websites such as Medium.com: