Welcome to Petfinder.com! The virtual home of 374,783 adoptable pets from 13,618 adoption groups

Search for a Pet

[See All]Breed

Location*

Ex: Des Moines, IA or 50301

Find Animal
Welfare Groups

[List by State]

Check us out on:

Download our iPhone app
Petfinder at Myspace
Petfinder at Facebook
Petfinder at YouTube

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

Table of Contents

1. Getting Started

2. Restrictions

3. Request Format

4. Developer Keys

5. Security

6. Response Formats

7. API Methods

XML Schema 0.9 (XSD)

Petfinder API FAQ

  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

    Cross-Domain Support (JSONP)

    The Petfinder API supports JSONP for cross-domain JavaScript requests. When making any request that is in JSON format, the callback parameter may be added to denote that this is a JSONP request. The value for the callback parameter should be a unique string.

    Below is a basic example of a JSONP request, using jQuery. Here the callback=? query string parameter is required to specify that it is a JSONP call. jQuery will replace the '?' within the query string with a unique time-stamped value (i.e. 'jQuery110206092635430395603_1391456463806').

    $.getJSON('http://api.petfinder.com/my.method?format=json&key=12345&callback=?')
      .done(function(petApiData) { alert('Data retrieved!'; })
      .error(function(err) { alert('Error retrieving data!'); 
    });
    

  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.

  5. | Back to Top |

  6. 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>
    

  7. | Back to Top |

  8. 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
  9. | Back to Top |

  10. 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 optional type of animal (barnyard, bird, cat, dog, horse, pig, reptile, smallfurry)
    breed string optional breed of animal (use breed.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 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 breed.list 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

  11. | Back to Top |