API Reference¶

`Petfinder` – Petfinder API Wrapper¶

class petpy.api.Petfinder(key, secret)¶

The Petfinder class provides the wrapper for the Petfinder API. The API methods are listed below

Parameters:	key – API key received from Petfinder after creating a developer account. secret – Secret key received from Petfinder.

import petpy
pf = Petfinder(key=API_key, secret=API_secret)

Get Animal Types¶

Petfinder.animal_types([types=None])¶

Returns data on an animal type, or types available from the Petfinder API. This data includes the available type’s coat names and colors, gender and other specific information relevant to the specified type(s). The animal type must be of ‘dog’, ‘cat’, ‘rabbit’, ‘small-furry’, ‘horse’, ‘bird’, ‘scales-fins-other’, ‘barnyard’.

Parameters:	types – String representing a single animal type or a list or tuple of a collection of animal types. If not specified, all available breeds for each animal type is returned. The animal type must be of ‘dog’, ‘cat’, ‘rabbit’, ‘small-furry’, ‘horse’, ‘bird’, ‘scales-fins-other’, ‘barnyard’.
Return type:	dict. Dictionary object representing JSON data returned from the Petfinder API.

# 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 Available Animal Breeds¶

Petfinder.breeds(types[, return_df=False][, raw_results=False])¶

Returns breed names of specified animal type, or types.

Parameters:

Parameters:	types – String representing a single animal type or a list or tuple of a collection of animal types. If not specified, all available breeds for each animal type is returned. The animal type must be of ‘dog’, ‘cat’, ‘rabbit’, ‘small-furry’, ‘horse’, ‘bird’, ‘scales-fins-other’, ‘barnyard’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame. raw_results – The PetFinder API `breeds` endpoint returns some extraneous data in its result set along with the breed names of the specified animal type(s). If `raw_results` is `False`, the method will return a cleaner JSON object result set with the extraneous data removed. This parameter can be set to `True` for those interested in retrieving the entire result set. If the parameter `return_df` is set to `True`, a pandas `DataFrame` will be returned regardless of the value specified for the `raw_result` parameter.
Return type:	dict or pandas DataFrame. If the parameter `return_df` is `False`, a dictionary object representing the JSON data returned from the Petfinder API is returned. If `return_df=True`, the resulting dictionary is coerced into a pandas DataFrame. Note if `return_df=True`, the parameter `raw_results` is overridden.

types – String representing a single animal type or a list or tuple of a collection of animal types. If not specified, all available breeds for each animal type is returned. The animal type must be of ‘dog’, ‘cat’, ‘rabbit’, ‘small-furry’, ‘horse’, ‘bird’, ‘scales-fins-other’, ‘barnyard’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
raw_results – The PetFinder API breeds endpoint returns some extraneous data in its result set along with the breed names of the specified animal type(s). If raw_results is False, the method will return a cleaner JSON object result set with the extraneous data removed. This parameter can be set to True for those interested in retrieving the entire result set. If the parameter return_df is set to True, a pandas DataFrame will be returned regardless of the value specified for the raw_result parameter.

Return type:

dict or pandas DataFrame. If the parameter return_df is False, a dictionary object representing the JSON data returned from the Petfinder API is returned. If return_df=True, the resulting dictionary is coerced into a pandas DataFrame. Note if return_df=True, the parameter raw_results is overridden.

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)

Find Listed Animals on Petfinder¶

Petfinder.animals([animal_id=None][, animal_type=None][, breed=None][, size=None][, gender=None][, age=None][, color=None][, coat=None][, status=None][, name=None][, organization_id=None][, location=None][, distance=None][, sort=None][, results_per_page=None][, pages=None][, return_df=False])¶

Returns adoptable animal data from Petfinder based on specified criteria.

Parameters:

Parameters:	animal_id – Integer or list or tuple of integers representing animal IDs obtained from Petfinder. When `animal_id` is specified, the other function parameters are overridden. If `animal_id` is not specified, a search of animals on Petfinder matching given criteria is performed. animal_type – String representing desired animal type to search. Must be one of ‘dog’, ‘cat’, ‘rabbit’, ‘small-furry’, ‘horse’, ‘bird’, ‘scales-fins-other’, or ‘barnyard’. breed – String or tuple or list of strings of desired animal type breed to search. Available animal breeds in the Petfinder database can be found using the `breeds()` method. size – String or tuple or list of strings of desired animal sizes to return. The specified size(s) must be one of ‘small’, ‘medium’, ‘large’, or ‘xlarge’. gender – String or tuple or list of strings representing animal genders to return. Must be of ‘male’, ‘female’, or ‘unknown’. age – String or tuple or list of strings specifying animal age(s) to return from search. Must be of ‘baby’,’young’, ‘adult’, ‘senior’. color – String representing specified animal ‘color’ to search. Colors for each available animal type in the Petfinder database can be found using the `animal_types()` method. coat – Desired coat(s) to return. Must be of ‘short’, ‘medium’, ‘long’, ‘wire’, ‘hairless’, or ‘curly’. status – Animal status to filter search results. Must be one of ‘adoptable’, ‘adopted’, or ‘found’. name – Searches for animal names matching or partially matching name. organization_id – Returns results for specified `organization_id`. Can be a str or a tuple or list of str representing multiple organizations. location – Returns results by specified location. Must be in the format ‘city, state’ for city-level results, ‘latitude, longitude’ for lat-long results, or ‘postal code’. distance – Returns results within the distance of the specified location. If not given, defaults to 100 miles. Maximum distance range is 500 miles. sort – Sorts by specified attribute. Leading dashes represents a reverse-order sort. Must be one of ‘recent’, ‘-recent’, ‘distance’, or ‘-distance’. pages – The number of pages of results to return. For example, if `pages=4` with the default `count` parameter (25), 100 results would be returned. The paged results are returned as a list. results_per_page – Number of results to return per page. Defaults to 20 results and cannot exceed 100 results per page. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	dict or pandas DataFrame. Dictionary object representing the returned JSON object from the Petfinder API. If `return_df=True`, the results are returned as a pandas DataFrame.

animal_id – Integer or list or tuple of integers representing animal IDs obtained from Petfinder. When animal_id is specified, the other function parameters are overridden. If animal_id is not specified, a search of animals on Petfinder matching given criteria is performed.
animal_type – String representing desired animal type to search. Must be one of ‘dog’, ‘cat’, ‘rabbit’, ‘small-furry’, ‘horse’, ‘bird’, ‘scales-fins-other’, or ‘barnyard’.
breed – String or tuple or list of strings of desired animal type breed to search. Available animal breeds in the Petfinder database can be found using the breeds() method.
size – String or tuple or list of strings of desired animal sizes to return. The specified size(s) must be one of ‘small’, ‘medium’, ‘large’, or ‘xlarge’.
gender – String or tuple or list of strings representing animal genders to return. Must be of ‘male’, ‘female’, or ‘unknown’.
age – String or tuple or list of strings specifying animal age(s) to return from search. Must be of ‘baby’,’young’, ‘adult’, ‘senior’.
color – String representing specified animal ‘color’ to search. Colors for each available animal type in the Petfinder database can be found using the animal_types() method.
coat – Desired coat(s) to return. Must be of ‘short’, ‘medium’, ‘long’, ‘wire’, ‘hairless’, or ‘curly’.
status – Animal status to filter search results. Must be one of ‘adoptable’, ‘adopted’, or ‘found’.
name – Searches for animal names matching or partially matching name.
organization_id – Returns results for specified organization_id. Can be a str or a tuple or list of str representing multiple organizations.
location – Returns results by specified location. Must be in the format ‘city, state’ for city-level results, ‘latitude, longitude’ for lat-long results, or ‘postal code’.
distance – Returns results within the distance of the specified location. If not given, defaults to 100 miles. Maximum distance range is 500 miles.
sort – Sorts by specified attribute. Leading dashes represents a reverse-order sort. Must be one of ‘recent’, ‘-recent’, ‘distance’, or ‘-distance’.
pages – The number of pages of results to return. For example, if pages=4 with the default count parameter (25), 100 results would be returned. The paged results are returned as a list.
results_per_page – Number of results to return per page. Defaults to 20 results and cannot exceed 100 results per page.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

dict or pandas DataFrame. Dictionary object representing the returned JSON object from the Petfinder API. If return_df=True, the results are returned as a pandas DataFrame.

# 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)

Get Animal Welfare Organization Data¶

Petfinder.organizations([organization_id=None][, name=None][, location=None][, distance=None][, state=None][, country=None][, query=None][, sort=True][, results_per_page=None][, pages=None][, return_df=False])¶

Returns data on an animal welfare organization, or organizations, based on specified criteria.

Parameters:

Parameters:	organization_id – Returns results for specified `organization_id`. Can be a str or a tuple or list of str representing multiple organizations. name – Returns results matching or partially matching organization name. location – Returns results by specified location. Must be in the format ‘city, state’ for city-level results, ‘latitude, longitude’ for lat-long results, or ‘postal code’. distance – Returns results within the distance of the specified location. If not given, defaults to 100 miles. Maximum distance range is 500 miles. state – Filters the results by the selected state. Must be a two-letter state code abbreviation of the state name, such as ‘WA’ for Washington or ‘NY’ for New York. country – Filters results to specified country. Must be a two-letter abbreviation of the country and is limited to the United States and Canada. query – Search matching and partially matching name, city or state. sort – Sorts by specified attribute. Leading dashes represents a reverse-order sort. Must be one of ‘recent’, ‘-recent’, ‘distance’, or ‘-distance’. count – Number of results to return per page. Defaults to 20 results and cannot exceed 100 results per page. pages – The number of pages of results to return. For example, if `pages=4` with the default `count` parameter (25), 100 results would be returned. The paged results are returned as a list. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	dict or pandas DataFrame. Dictionary object representing the returned JSON object from the Petfinder API. If `return_df=True`, the results are returned as a pandas DataFrame.

organization_id – Returns results for specified organization_id. Can be a str or a tuple or list of str representing multiple organizations.
name – Returns results matching or partially matching organization name.
location – Returns results by specified location. Must be in the format ‘city, state’ for city-level results, ‘latitude, longitude’ for lat-long results, or ‘postal code’.
distance – Returns results within the distance of the specified location. If not given, defaults to 100 miles. Maximum distance range is 500 miles.
state – Filters the results by the selected state. Must be a two-letter state code abbreviation of the state name, such as ‘WA’ for Washington or ‘NY’ for New York.
country – Filters results to specified country. Must be a two-letter abbreviation of the country and is limited to the United States and Canada.
query – Search matching and partially matching name, city or state.
sort – Sorts by specified attribute. Leading dashes represents a reverse-order sort. Must be one of ‘recent’, ‘-recent’, ‘distance’, or ‘-distance’.
count – Number of results to return per page. Defaults to 20 results and cannot exceed 100 results per page.
pages – The number of pages of results to return. For example, if pages=4 with the default count parameter (25), 100 results would be returned. The paged results are returned as a list.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

dict or pandas DataFrame. Dictionary object representing the returned JSON object from the Petfinder API. If return_df=True, the results are returned as a pandas DataFrame.

# 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')

API Reference¶

Petfinder – Petfinder API Wrapper¶

Get Animal Types¶

Get Available Animal Breeds¶

Find Listed Animals on Petfinder¶

Get Animal Welfare Organization Data¶

`Petfinder` – Petfinder API Wrapper¶