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: - 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. Ifreturn_df
isTrue
,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: - 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. Thepages
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 defaultcount
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 thepages
parameter is set, the paged results are returned as a list. Ifreturn_df
isTrue
,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: - 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. Ifreturn_df
isTrue
,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: - 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. Ifreturn_df
isTrue
,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: - 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. Ifrecords
is specified, a list of the results is returned. Ifreturn_df
isTrue
,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: - 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. Thepages
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 defaultcount
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 thepages
parameter is set, the paged results are returned as a list. Ifreturn_df
isTrue
,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: - 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. Ifreturn_df
isTrue
,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.
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: - 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. Ifreturn_df
isTrue
,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: - 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. Thepages
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 defaultcount
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 thepages
parameter is set, the paged results are returned as a list. Ifreturn_df
isTrue
,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: - 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. Thepages
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 defaultcount
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 thepages
parameter is set, the paged results are returned as a list. Ifreturn_df
isTrue
,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.