API Reference¶

`Petfinder` – Petfinder API Wrapper¶

class petpy.api.Petfinder([key][, secret=None][, host='http://api.petfinder.com/'])¶: The Petfinder class provides the wrapper for the Petfinder API. The API methods are listed below

Pet Methods¶

Petfinder.breed_list([animal][, outputformat='json'][, return_df=False])¶

Method for calling the ‘breed.list’ method of the Petfinder API. Returns the available breeds for the selected animal.

Parameters:

Parameters:	animal – Return breeds of animal. Must be one of ‘barnyard’, ‘bird’, ‘cat’, ‘dog’, ‘horse’, ‘reptile’, or ‘smallfurry’. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	json, str. or pandas DataFrame If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

animal – Return breeds of animal. Must be one of ‘barnyard’, ‘bird’, ‘cat’, ‘dog’, ‘horse’, ‘reptile’, or ‘smallfurry’.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

json, str. or pandas DataFrame If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

Petfinder.pet_find([location], [animal=None], [breed=None], [size=None], [sex=None], [age=None], [offset=None], [count=None], [pages=None], [output=None], [outputformat='json'], [return_df=False)¶

Returns a collection of pet records matching input parameters. Wrapper for ‘pet.find’ method in the Petfinder API.

Parameters:

Parameters:	location – ZIP/postal code, state, or city and state to perform the search. animal – Return breeds of animal. Must be one of ‘barnyard’, ‘bird’, ‘cat’, ‘dog’, ‘horse’, ‘reptile’, or ‘smallfurry’. breed – Specifies the breed of the animal to search. size – Specifies the size of the animal/breed to search. Must be one of ‘S’ (small), ‘M’ (medium), ‘L’ (large), ‘XL’ (extra-large). sex – Filters the search to the desired gender of the animal. Must be one of ‘M’ (male) or ‘F’ (female). age – Returns animals with specified age. Must be one of ‘Baby’, ‘Young’, ‘Adult’, ‘Senior’. offset – Can be set to the value of `lastOffset` returned from the previous call to retrieve the next set of results. The `pages` parameter can also be used to pull a desired number of paged results. count – The number of records to return. Default is 25. 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. output – Sets the amount of information returned in each record. ‘basic’ returns a simple record while ‘full’ returns a complete record with description. Defaults to ‘basic’. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	json, list of json, str, list of str or pandas DataFrame. Pet records matching the desired search parameters. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If the `pages` parameter is set, the paged results are returned as a list. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

location – ZIP/postal code, state, or city and state to perform the search.
animal – Return breeds of animal. Must be one of ‘barnyard’, ‘bird’, ‘cat’, ‘dog’, ‘horse’, ‘reptile’, or ‘smallfurry’.
breed – Specifies the breed of the animal to search.
size – Specifies the size of the animal/breed to search. Must be one of ‘S’ (small), ‘M’ (medium), ‘L’ (large), ‘XL’ (extra-large).
sex – Filters the search to the desired gender of the animal. Must be one of ‘M’ (male) or ‘F’ (female).
age – Returns animals with specified age. Must be one of ‘Baby’, ‘Young’, ‘Adult’, ‘Senior’.
offset – Can be set to the value of lastOffset returned from the previous call to retrieve the next set of results. The pages parameter can also be used to pull a desired number of paged results.
count – The number of records to return. Default is 25.
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.
output – Sets the amount of information returned in each record. ‘basic’ returns a simple record while ‘full’ returns a complete record with description. Defaults to ‘basic’.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

json, list of json, str, list of str or pandas DataFrame. Pet records matching the desired search parameters. If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If the pages parameter is set, the paged results are returned as a list. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

Petfinder.pet_get([petId][, outputformat='json'][, return_df=False])¶

Returns a single record for a pet. Wrapper for ‘pet.get’ method in the Petfinder API.

Parameters:

Parameters:	petId – ID of the pet record to return. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	json, str or pandas DataFrame. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

petId – ID of the pet record to return.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

json, str or pandas DataFrame. If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

Petfinder.pets_get([petId][, outputformat='json'][, return_df=False])¶

Convenience wrapper of pet_get for returning multiple pet records given a list or tuple of pet IDs.

Parameters:

Parameters:	petId – list or tuple containing pet IDs to search. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	list or pandas DataFrame. Matching record corresponding to input pet ID. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

petId – list or tuple containing pet IDs to search.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

list or pandas DataFrame. Matching record corresponding to input pet ID. If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

Petfinder.pet_getRandom([animal=None][, breed=None][, size=None][, sex=None][, location=None][, shelterId=None][, records=None][, output=None][, outputformat='json'][, return_df=False])¶

Returns a randomly selected pet record. The possible result can be filtered with input parameters. Wrapper for ‘pet.getRandom’ method in the Petfinder API.

Parameters:

Parameters:	animal – Return breeds of animal. Must be one of ‘barnyard’, ‘bird’, ‘cat’, ‘dog’, ‘horse’, ‘reptile’, or ‘smallfurry’. breed – Specifies the breed of the animal to search. size – Specifies the size of the animal/breed to search. Must be one of ‘S’ (small), ‘M’ (medium), ‘L’ (large), ‘XL’ (extra-large). sex – Filters the search to the desired gender of the animal. Must be one of ‘M’ (male) or ‘F’ (female). location – ZIP/postal code, state, or city and state to perform the search. shelterId – Filter results to a specific shelter. output – Sets the amount of information returned in each record. ‘basic’ returns a simple record while ‘full’ returns a complete record with description. Defaults to ‘basic’. records – Returns `records` random results. Each returned record is counted as one call to the Petfinder API. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	json, str or pandas DataFrame. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If `records` is specified, a list of the results is returned. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

animal – Return breeds of animal. Must be one of ‘barnyard’, ‘bird’, ‘cat’, ‘dog’, ‘horse’, ‘reptile’, or ‘smallfurry’.
breed – Specifies the breed of the animal to search.
size – Specifies the size of the animal/breed to search. Must be one of ‘S’ (small), ‘M’ (medium), ‘L’ (large), ‘XL’ (extra-large).
sex – Filters the search to the desired gender of the animal. Must be one of ‘M’ (male) or ‘F’ (female).
location – ZIP/postal code, state, or city and state to perform the search.
shelterId – Filter results to a specific shelter.
output – Sets the amount of information returned in each record. ‘basic’ returns a simple record while ‘full’ returns a complete record with description. Defaults to ‘basic’.
records – Returns records random results. Each returned record is counted as one call to the Petfinder API.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

json, str or pandas DataFrame. If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If records is specified, a list of the results is returned. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

Shelter Methods¶

Petfinder.shelter_find([location][, name=None][, offset=None][, count=None][, pages=None][, outputformat='json'][, return_df=False])¶

Returns a collection of shelter records matching input parameters. Wrapper for the ‘shelter.find’ method in the Petfinder API.

Parameters:

Parameters:	location – ZIP/postal code, state, or city and state to perform the search. name – Full or partial shelter name offset – Can be set to the value of `lastOffset` returned from the previous call to retrieve the next set of results. The `pages` parameter can also be used to pull a desired number of paged results. count – The number of records to return. Default is 25. 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. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	json, list of json, str, list of str or pandas DataFrame. Shelters matching specified input parameters. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If the `pages` parameter is set, the paged results are returned as a list. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

location – ZIP/postal code, state, or city and state to perform the search.
name – Full or partial shelter name
offset – Can be set to the value of lastOffset returned from the previous call to retrieve the next set of results. The pages parameter can also be used to pull a desired number of paged results.
count – The number of records to return. Default is 25.
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.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

json, list of json, str, list of str or pandas DataFrame. Shelters matching specified input parameters. If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If the pages parameter is set, the paged results are returned as a list. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

Petfinder.shelter_get([shelterId][, outputformat='json'][, return_df=False])¶

Returns a single shelter record. Wrapper for the ‘shelter.get’ method in the Petfinder API.

Parameters:

Parameters:	shelterId – Filter results to a specific shelter. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	json, str or pandas DataFrame. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

shelterId – Filter results to a specific shelter.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

Petfinder.shelters_get([shelterId][, outputformat='json'][, return_df=False])¶

Returns multiple shelter records given a list or tuple of shelter IDs. Convenience wrapper function of shelter_get().

Parameters:

Parameters:	shelterId – list or tuple containing shelter IDs to search. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	list or pandas DataFrame. Shelter record of input shelter ID. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

shelterId – list or tuple containing shelter IDs to search.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

list or pandas DataFrame. Shelter record of input shelter ID. If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

Petfinder.shelter_getPets([shelterId][, status=None][, offset=None][, count=None][, output=None][, pages=None][, outputformat='json'][, return_df=False])¶

Returns a collection of pet records for an individual shelter. Wrapper for the ‘shelter_getPets’ method in the Petfinder API.

Parameters:

Parameters:	shelterId – Filter results to a specific shelter. status – Filters search by pet’s status. Must be one of ‘A’ (adoptable, default), ‘H’ (hold), ‘P’ (pending), ‘X’ (adopted/removed). offset – Can be set to the value of `lastOffset` returned from the previous call to retrieve the next set of results. The `pages` parameter can also be used to pull a desired number of paged results. count – The number of records to return. Default is 25. 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. output – Sets the amount of information returned in each record. ‘basic’ returns a simple record while ‘full’ returns a complete record with description. Defaults to ‘basic’. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	json, list of json, str, list of str or pandas DataFrame. Pet records of given shelter matching optional input parameters. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If the `pages` parameter is set, the paged results are returned as a list. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

shelterId – Filter results to a specific shelter.
status – Filters search by pet’s status. Must be one of ‘A’ (adoptable, default), ‘H’ (hold), ‘P’ (pending), ‘X’ (adopted/removed).
offset – Can be set to the value of lastOffset returned from the previous call to retrieve the next set of results. The pages parameter can also be used to pull a desired number of paged results.
count – The number of records to return. Default is 25.
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.
output – Sets the amount of information returned in each record. ‘basic’ returns a simple record while ‘full’ returns a complete record with description. Defaults to ‘basic’.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

json, list of json, str, list of str or pandas DataFrame. Pet records of given shelter matching optional input parameters. If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If the pages parameter is set, the paged results are returned as a list. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

Petfinder.shelter_listByBreed([animal][, breed][, offset=None][, count=None][, pages=None][, outputformat='json'][, return_df=False])¶

Returns a list of shelter IDs listing animals matching the input animal breed. Wrapper for the ‘shelter.listByBreed’ method in the Petfinder API.

Parameters:

Parameters:	animal – Return breeds of animal. Must be one of ‘barnyard’, ‘bird’, ‘cat’, ‘dog’, ‘horse’, ‘reptile’, or ‘smallfurry’. breed – Specifies the breed of the animal to search. offset – Can be set to the value of `lastOffset` returned from the previous call to retrieve the next set of results. The `pages` parameter can also be used to pull a desired number of paged results. count – The number of records to return. Default is 25. 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. outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’. return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.
Return type:	json, list of json, str or list of str. Shelter IDs listing animals matching the input animal breed. If the parameter `outputformat` is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If the `pages` parameter is set, the paged results are returned as a list. If `return_df` is `True`, `outputformat` is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

animal – Return breeds of animal. Must be one of ‘barnyard’, ‘bird’, ‘cat’, ‘dog’, ‘horse’, ‘reptile’, or ‘smallfurry’.
breed – Specifies the breed of the animal to search.
offset – Can be set to the value of lastOffset returned from the previous call to retrieve the next set of results. The pages parameter can also be used to pull a desired number of paged results.
count – The number of records to return. Default is 25.
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.
outputformat – Output type of results. Must be one of ‘json’ (default) or ‘xml’.
return_df – If True, coerces results returned from the Petfinder API into a pandas DataFrame.

Return type:

json, list of json, str or list of str. Shelter IDs listing animals matching the input animal breed. If the parameter outputformat is ‘json’, the result is formatted as a JSON object. Otherwise, the return object is a text representation of an XML object. If the pages parameter is set, the paged results are returned as a list. If return_df is True, outputformat is overridden and the results are converted to a pandas DataFrame. Please note there may be some loss of data when the conversion is made; however, this loss is primarily confined to the call encoding and timestamp information and metadata of the associated media (photos) with a record.

API Reference¶

Petfinder – Petfinder API Wrapper¶

Pet Methods¶

Shelter Methods¶

`Petfinder` – Petfinder API Wrapper¶