Petfinder API

Overview

The Petfinder API gives developers access to access Petfinder's database of over 300,000 adoptable pets and 11,000 animal welfare organizations (AWO). In addition to searching for adoptable pets on the Petfinder.com web site, you can use the API to create your own dynamic pet web sites or applications, using the same data we use on Petfinder.com.

THIS PAGE IS INTENDED FOR DEVELOPERS

1. Getting Started

   You will need an API key and secret to access the Petfinder API, which you can obtain by registering here. You will also be asked for the domain of the web site on which your applications will run. We do not currently use this information for restricting access, but we may do so in the future to protect your security information. Developers of commercial or high-volume sites and applications should refer to the restrictions below.

2. Restrictions

   The following usage restrictions apply to users of the API:

   • Total requests per day: 10,000
   • Records per request: 1,000
   • Maximum records per search: 2,000

   If your usage may exceed these limits, please contact us at api-help@petfinder.com.

3. Request Format

   The Petfinder API is a RESTful API, which means you access it using standard HTTP request methods. GET is used for reading data, and POST, PUT and DELETE are used for updating data (not supported yet). Arguments are passed in the query string for GET and DELETE, and in the request body for POST and PUT.

   URLs are of the form: http://api.petfinder.com/subsystem.method

   For GET calls, all arguments are specified in the URL query string like this: http://api.petfinder.com/my.method?key=12345&arg1=foo&token=67890&sig=abcdef

   For POST, PUT and DELETE calls, all arguments should be specified in the request body, so the URL would be http://api.petfinder.com/my.method while the request body would contain key=12345&arg1=foo&token=67890&sig=abcdef

4. Developer Keys

   When you register to use the API you will receive a key and a secret. The key identifies you in each API request and can be safely displayed and transmitted unencrypted. The secret is used to sign requests that require authentication. The secret, as its name implies, should be kept private and never shared or displayed.

| Back to Top |

5. Security

   Most API methods simply search and return public data, and don't require any authentication other than your key for logging purposes. If all you want to do is query adoptable pet and public shelter data, you can skip this section. All you need is your key.

   Certain methods may access private data or modify data, and these require stronger authentication. The Petfinder API uses signatures and session tokens to implement this authentication.

   SESSION TOKENS

   Authenticated API requests require a session token, which can be obtained using the auth.getToken method. The token is valid for 60 minutes, after which you should call auth.getToken to request a new one.

   SIGNING THE REQUEST

   Each authenticated request must be signed so the server can verify that it's really coming from you. The signature is an MD5 hash of the concatenation of your secret and the arguments from the request, including your key and token:

   MD5 ( secret + arguments )
   

   Pass the result as the signature argment in your query string (GET) or POST body data.

   EXAMPLE API CALL

   Let's say we were assigned the key "12345" and a secret of "abcdef". We want to retrieve the record for pet ID 24601. The first thing we need to do is obtain a session token. This token must be passed as an argument to all subsequent API calls, until the token expires (after 60 minutes). To do that, we'll use the auth.getToken API method and construct our URL as follows:

   http://api.petfinder.com/auth.getToken?key=12345
   

   If we were to submit this request as is, we would receive an invalid signature error. So let's sign the request. First, we concatenate the secret and the request arguments:

   abcdefkey=12345
   

   Note how there is no space or other separator between the secret and the first character of the other arguments. Now take the MD5 hash of that string:

   MD5(abcdefkey=12345) = 333fda55007a750ef0c4cb792ee5f872
   

   We now append the signature to the query string as sig:

   auth.getToken?key=12345&sig=333fda55007a750ef0c4cb792ee5f872
   

   The request is now signed and ready to submit! The response should look like this:

   <petfinder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://api.petfinder.com/schemas/0.9/petfinder.xsd">
    <header>
     <version>0.1</version>
     <timestamp>2008-10-15T20:15:05Z</timestamp>
     <status>
      <code>100</code>
      <message></message>
     </status>
    </header>
    <auth>
     <key>12345</key>
     <token>cb444effb1b45a10d3d9d58561c86c31</token>
     <expires>1224105305</expires>
     <expiresString>2008-10-15T21:15:05Z</expiresString>
    </auth>
   </petfinder>
   

   As you can see from the response XML, our token is cb444effb1b45a10d3d9d58561c86c31. We can use this token until it expires. For convenience, the expiration is given in two formats: expires is the expiration in Unix epoch format (seconds since 00:00:00 January 1, 1970 UTC), while expiresString is the string representation of the expiration time in UTC (GMT).

   Now, back to our original goal: retrieve the pet record for pet ID 24601. We have our token, so we can construct a call to pet.getto ask for the pet's record. This is done using the same procedure above, except we add a token argument.

   1. Construct the raw request: http://api.petfinder.com/pet.get?key=12345&id=24601
   2. Add the token: http://api.petfinder.com/pet.get?key=12345&id=24601
&token=cb444effb1b45a10d3d9d58561c86c31
   3. Generate the signature:
      MD5(abcdefkey=12345&id=24601&token=cb444effb1b45a10d3d9d58561c86c31) = 091915104e404251a4b2618db7d920fa
   4. Append the signature to the request: http://api.petfinder.com/pet.get?key=12345&id=24601
&token=cb444effb1b45a10d3d9d58561c86c31
&sig=091915104e404251a4b2618db7d920fa
   5. Submit the request.

   The response, if successful, should look something like this:

   <?xml version="1.0" encoding="UTF-8"?>
   <petfinder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://api.petfinder.com/schemas/0.9/petfinder.xsd">
    <header>
     <version>0.1</version>
     <timestamp>2008-10-21T15:28:37Z</timestamp>
     <status>
      <code>100</code>
      <message></message>
     </status>
    </header>
    <pet>
     <id>24601</id>
     <animal>Dog</animal>
     <breeds>
      <breed>German Shepherd Dog</breed>
     </breeds>
     <mix>no</mix>
     <age>Adult</age>
     <name>Jean Valjean</name>
     <shelterId>NJ94</shelterId>
     <size>M</size>
     <sex>M</sex>
     <description>Steals bread, but is a good doggie.</description>
     <lastUpdate>2008-09-30 17:01:12</lastUpdate>
     <status>A</status>
     <media>
      <photos>
       <photo id="1" size="x">
        http://photocache.petfinder.com/fotos/NJ94/NJ94.26401-1-x.jpg
       </photo>
       <photo id="1" size="t">
        http://photocache.petfinder.com/fotos/NJ94/NJ94.26401-1-t.jpg
       </photo>
       <photo id="1" size="pn">
        http://photocache.petfinder.com/fotos/NJ94/NJ94.26401-1-pn.jpg
       </photo>
       <photo id="1" size="pnt">
        http://photocache.petfinder.com/fotos/NJ94/NJ94.26401-1-pnt.jpg
       </photo>
       <photo id="1" size="fpm">
        http://photocache.petfinder.com/fotos/NJ94/NJ94.26401-1-fpm.jpg
       </photo>
      </photos>
     </media>
     <contact></contact>
    </pet>
   </petfinder>
   

| Back to Top |

6. Response Formats

   The Petfinder API can respond in one of two formats: XML (the default) or JSON. The XML format is specified by the XML schema at http://api.petfinder.com/schemas/0.9/petfinder.xsd The JSON output is based on the standard used by the Google Data API. You can change the output to JSON with format=json. For now we'll focus on the XML format here, but the concepts are directly applicable to JSON.

   Every XML response is wrapped in a petfinder container tag. Within that container is a header and optional data tags.

   Response Header

   Responses always contain a header, which contains information about your request:

   • version: API version
   • timestamp: the date and time the response was issued
   • status: the status code for this request
   • message: an optional diagnostic message, usually provided on error

   Response Data

   The response data directly follows the header, and contains the results of your request. The tags returned vary depending on the method called, so refer to that method's documentation for details.

   Some methods, such as pet.find, can return thousands of records. For these methods, instead of returning and processing all the results in one call, you can iterate through the results a few at a time by providing the number of records to return, and an optional offset from the start of the list. To do this, specify the number of records to return as count (default is 25) and call the method. The response will contain a lastOffset tag that you will use as the offset to the next call, leaving all other arguments the same.

   Status Codes

   Code	Name	Notes
   100	PFAPI_OK	No error
   200	PFAPI_ERR_INVALID	Invalid request
   201	PFAPI_ERR_NOENT	Record does not exist
   202	PFAPI_ERR_LIMIT	A limit was exceeded
   203	PFAPI_ERR_LOCATION	Invalid geographical location
   300	PFAPI_ERR_UNAUTHORIZED	Request is unauthorized
   301	PFAPI_ERR_AUTHFAIL	Authentication failure
   999	PFAPI_ERR_INTERNAL	Generic internal error

| Back to Top |

7. API Methods

   auth.getToken

   Returns a token valid for a timed session (usually 60 minutes). This token must be passed to all API functions that require a token.

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderAuthData

   | Back to Top |

   breed.list

   Returns a list of breeds for a particular animal.

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   token	string	optional	session token
   animal	string	required	type of animal (barnyard, bird, cat, dog, horse, pig, reptile, smallfurry)
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderBreedList

   | Back to Top |

   pet.get

   Returns a record for a single pet.

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   token	string	optional	session token
   id	integer	required	pet ID
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderPetRecord

   | Back to Top |

   pet.getRandom

   Returns a record for a randomly selected pet. You can choose the characteristics of the pet you want returned using the various arguments to this method.

   This method can return pet records in three formats:

   • id: just the pet ID
   • basic: essential information like name, animal, breed, shelter ID, primary photo
   • full: the complete pet record

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   token	string	optional	session token
   animal	string	optional	type of animal (barnyard, bird, cat, dog, horse, pig, reptile, smallfurry)
   breed	string	optional	breed of animal (use breeds.list for a list of valid breeds)
   size	string	optional	size of animal (S=small, M=medium, L=large, XL=extra-large)
   sex	character	optional	M=male, F=female
   location	string	optional	the ZIP/postal code or city and state the animal should be located (NOTE: the closest possible animal will be selected)
   shelterid	string	optional	ID of the shelter that posted the pet
   output	string	optional (default=id)	How much of the pet record to return: id, basic, full
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderPetRecord

   | Back to Top |

   pet.find

   Searches for pets according to the criteria you provde and returns a collection of pet records matching your search. The results will contain at most count records per query, and a lastOffset tag. To retrieve the next result set, use the lastOffset value as the offset to the next pet.find call.

   NOTE: the total number of records you are allowed to request may vary depending on the type of developer key you have.

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   token	string	optional	session token
   animal	string	required	type of animal (barnyard, bird, cat, dog, horse, pig, reptile, smallfurry)
   breed	string	optional	breed of animal (use pet.listBreeds for a list of valid breeds)
   size	string	optional	size of animal (S=small, M=medium, L=large, XL=extra-large)
   sex	character	optional	M=male, F=female
   location	string	required	the ZIP/postal code or city and state where the search should begin
   age	string	optional	age of the animal (Baby, Young, Adult, Senior)
   offset	string	optional	set this to the value of lastOffset returned by a previous call to pet.find, and it will retrieve the next result set
   count	integer	optional	how many records to return for this particular API call (default is 25)
   output	string	optional (default=basic)	How much of each record to return: basic (no description) or full (includes description)
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderPetRecordList

   | Back to Top |

   shelter.find

   Returns a collection of shelter records matching your search criteria.

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   token	string	optional	session token
   location	string	required	the ZIP/postal code or city and state where the search should begin
   name	string	optional if location is specified	full or partial shelter name
   offset	integer	optional	offset into the result set (default is 0)
   count	integer	optional	how many records to return for this particular API call (default is 25)
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderShelterRecordList

   | Back to Top |

   shelter.get

   Returns a record for a single shelter.

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   token	optional	required	session token
   id	string	required	shelter ID (e.g. NJ94)
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderShelterRecord

   | Back to Top |

   shelter.getPets

   Returns a list of IDs or collection of pet records for an individual shelter

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   token	string	optional	session token
   id	string	required	shelter ID (e.g. NJ94)
   status	character	optional (default=A, public may only list adoptable pets)	A=adoptable, H=hold, P=pending, X=adopted/removed
   offset	integer	optional	offset into the result set (default is 0)
   count	integer	optional	how many records to return for this particular API call (default is 25)
   output	string	optional (default=basic)	How much of the pet record to return: id, basic (no description), full
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderPetRecordList

   | Back to Top |

   shelter.listByBreed

   Returns a list of shelter IDs listing animals of a particular breed.

   ARGUMENTS
   Name	Type	Required?	Description
   key	string	required	your developer key
   token	string	optional	session token
   animal	string	required	type of animal (barnyard, bird, cat, dog, horse, pig, reptile, smallfurry)
   breed	string	required	greed of animal(use pet.listBreeds for a list of valid breeds)
   offset	integer	optional	offset into the result set (default is 0)
   count	integer	optional	how many records to return for this particular API call (default is 25)
   format	string	optional (default=xml)	Response format: xml, json

   XML return type: petfinderShelterRecordList

| Back to Top |