API Reference¶

This page serves as a complete reference to all public classes and exceptions. This is probably only useful after you have read Quickstart.

petfinder.PetfinderClient¶

class petfinder.PetFinderClient(api_key, api_secret, endpoint='http://api.petfinder.com/')¶

Simple client for the Petfinder API. You’ll want to pull your API details from http://www.petfinder.com/developers/api-key and instantiate this class with said credentials.

Refer to http://www.petfinder.com/developers/api-docs for the required kwargs for each method. It is safe to ignore the key argument, as this client handles setting that for you.

breed_list¶

PetFinderClient.breed_list(**kwargs)¶

breed.list wrapper. Returns a list of breed name strings.

Return type:	list
Returns:	A list of breed names.

pet_get¶

PetFinderClient.pet_get(**kwargs)¶

pet.get wrapper. Returns a record dict for the requested pet.

Return type:	dict
Returns:	The pet’s record dict.

pet_getrandom¶

PetFinderClient.pet_getrandom(**kwargs)¶

pet.getRandom wrapper. Returns a record dict or Petfinder ID for a random pet.

Return type:	dict or str
Returns:	A dict of pet data if `output` is `'basic'` or `'full'`, and a string if `output` is `'id'`.

pet_find¶

PetFinderClient.pet_find(**kwargs)¶

pet.find wrapper. Returns a generator of pet record dicts matching your search criteria.

Return type:	generator
Returns:	A generator of pet record dicts.
Raises:	`petfinder.exceptions.LimitExceeded` once you have reached the maximum number of records your credentials allow you to receive.

shelter_find¶

PetFinderClient.shelter_find(**kwargs)¶

shelter.find wrapper. Returns a generator of shelter record dicts matching your search criteria.

Return type:	generator
Returns:	A generator of shelter record dicts.
Raises:	`petfinder.exceptions.LimitExceeded` once you have reached the maximum number of records your credentials allow you to receive.

shelter_get¶

PetFinderClient.shelter_get(**kwargs)¶

shelter.get wrapper. Given a shelter ID, retrieve its details in dict form.

Return type:	dict
Returns:	The shelter’s details.

shelter_getpets¶

PetFinderClient.shelter_getpets(**kwargs)¶

shelter.getPets wrapper. Given a shelter ID, retrieve either a list of pet IDs (if output is 'id'), or a generator of pet record dicts (if output is 'full' or 'basic').

Return type:	generator
Returns:	Either a generator of pet ID strings or pet record dicts, depending on the value of the `output` keyword.
Raises:	`petfinder.exceptions.LimitExceeded` once you have reached the maximum number of records your credentials allow you to receive.

shelter_listbybreed¶

PetFinderClient.shelter_listbybreed(**kwargs)¶

shelter.listByBreed wrapper. Given a breed and an animal type, list the shelter IDs with pets of said breed.

Return type:	generator
Returns:	A generator of shelter IDs that have breed matches.

petfinder.exceptions¶

Petfinder API exceptions.

exception petfinder.exceptions.AuthenticationFailure¶: Raised when an authentication failure occurs.

exception petfinder.exceptions.GenericInternalError¶: Your guess is as good as mine.

exception petfinder.exceptions.InvalidGeographicalLocationError¶: Raised when an invalid geographical location is specified.

exception petfinder.exceptions.InvalidRequestError¶: Raised when an invalid or mal-formed request is sent.

exception petfinder.exceptions.LimitExceeded¶: Raised when usage limits are exceeded.

exception petfinder.exceptions.PetfinderAPIError¶: Base class for all Petfinder API exceptions. Mostly here to allow end users to catch all Petfinder exceptions.

exception petfinder.exceptions.RecordDoesNotExistError¶: Raised when querying for a record that does not exist.

exception petfinder.exceptions.RequestIsUnauthorizedError¶: Raised when attempting to call a method that the user is unauthorized for.

exception petfinder.exceptions.UnrecognizedError¶: This is raised if the API returns a status code that we don’t have a matching exception for. This is more for future-proofing, in case they add extra status codes.