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: - 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). Ifraw_results
isFalse
, the method will return a cleaner JSON object result set with the extraneous data removed. This parameter can be set toTrue
for those interested in retrieving the entire result set. If the parameterreturn_df
is set toTrue
, a pandasDataFrame
will be returned regardless of the value specified for theraw_result
parameter.
Return type: dict or pandas DataFrame. If the parameter
return_df
isFalse
, a dictionary object representing the JSON data returned from the Petfinder API is returned. Ifreturn_df=True
, the resulting dictionary is coerced into a pandas DataFrame. Note ifreturn_df=True
, the parameterraw_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: - 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. Ifanimal_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 defaultcount
parameter (25), 100 results would be returned. The paged results are returned as a list. - good_with_cats – Filters returned animal results to animals that are designated as good with cats. Must be a boolean value (True, False) or a value that can be coerced to a boolean (1, 0).
- good_with_children – Filters returned animal results to animals that are designated as good with children. Must be a boolean value (True, False) or a value that can be coerced to a boolean (1, 0).
- good_with_dogs – Filters returned animal results to animals that are designated as good with dogs. Must be a boolean value (True, False) or a value that can be coerced to a boolean (1, 0).
- before_date – Returns results with a published_at datetime before the specified time. Must be a string in the form of ‘YYYY-MM-DD’ or ‘YYYY-MM-DD H:M:S’ or a datetime object.
- after_date – Returns results with a published_at datetime after the specified time. Must be a string in the form of ‘YYYY-MM-DD’ or ‘YYYY-MM-DD H:M:S’ or a datetime object.
- 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)
- animal_id – Integer or list or tuple of integers representing animal IDs obtained from Petfinder. When
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: - 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 defaultcount
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')
- organization_id – Returns results for specified