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

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

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.

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.

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.

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.

API Exceptions¶

class petpy.api.PetfinderError(Exception)¶: Base Exception class for Petfinder API Exception definitions.

class petpy.api.PetfinderInvalidCredentials(PetfinderError)¶: Exception for handling invalid API and secret keys passed to the Petfinder class.

class petpy.api.PetfinderInsufficientAccess(PetfinderError)¶: Exception for handling insufficient access errors when working with the Petfinder API. This exception is typically raised when the credentials supplied to the Petfinder API have expired and the connection to the API needs to be re-authenticated.

class petpy.api.PetfinderResourceNotFound(PetfinderError)¶: Exception for handling unknown resource requests.

class petpy.api.PetfinderUnexpectedError(PetfinderError)¶: Exception for handling unexpected errors from the Petfinder API. This error is generally the result of an unknown and unexpected error that occurs on the server-side of the Petfinder API when sending a request.

class petpy.api.PetfinderInvalidParameters(PetfinderError)¶: Exception for handling invalid values passed to Petfinder API method parameters.

API Reference¶

Petfinder – Petfinder API Wrapper¶

Get Animal Types¶

Get Available Animal Breeds¶

Find Listed Animals on Petfinder¶

Get Animal Welfare Organization Data¶

API Exceptions¶

`Petfinder` – Petfinder API Wrapper¶