Petfinder API Frequently Asked Questions

These are the most frequently asked questions from API users during our beta program. We will be expanding it as we hear more from our users, so check back often. If you have a question that is not answered here, e-mail api-help@petfinder.com and we will respond as soon as possible.

General

What data does the API provide?

The API provides access to public shelter information and adoptable pet data for shelters who have allowed third parties access to their data. You can also query our most current list of breeds that can be used for pet searches.

Can I use the API to update my pet records?

Not yet, but that functionality is planned for a future release.

Is the API stable?

Yes. During this late stage of the beta period, we are not changing the behavior of any of the existing methods or updating the schema unless it is required to fix a bug or add missing functionality. Code written to use the API before October 7, 2009 should be reviewed to verify it still works with the latest schema.

Are there limits on API usage?

Each key is limited to 10,000 API requests per day (this number will likely be increased after the beta period). Each request can return at most 1,000 records, though you can iterate though longer result sets. NOTE: a request is a single call to a Petfinder API method.

Can you increase my usage limits?

We consider API limit increases on a case-by-case basis. Please submit a request to api-help@petfinder.com that contains a description of your application and your daily API usage estimates, and someone will contact you to discuss the matter further.

What do I need my API secret for?

The secret is used to authenticate the caller to the Petfinder API. It is not currently used for anything, but we will eventually offer access to non-adoptable pet data and other private shelter information, and this will require the secret for stronger authentication.

If you are only querying adoptable pet data, you don't need the secret at all.

Usage

What do responses look like?

Each method has a response type with a corresponding definition in the XML schema. These responses are prefixed with a standard header and wrapped in a petfinder container tag. There is a comprehensive XML schema that defines the various reponse formats. The response from pet.get, which returns a single pet record, looks 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>

Why don't I see any pet data for a shelter that has adoptable pets?

The most likely reason for this is that the shelter has opted out of sharing their pet data with third parties. Shelter administrators can opt-in on the Edit Shelter Info section of their Petfinder admin page.

Why do I see the same results from pet.find even after I increment the offset?

This was a bug that manifested itself for searches in sparsely populated areas. To fix this, pet.find (and other methods returning large variable result sets) now return a value in the lastOffset tag that you must use as the offset to the next request. This also saves you the hassle of calculating the next offset yourself.

How do I iterate through large result sets?

API methods will return 25 records by default, or the number of records you specify in the count argument, up to 1,000 records per request. The response to your first request will contain a lastOffset tag. To retrieve the next set of results, pass the value of this tag in the offset argument to the next call. Do not change any of the other arguments from the first request.

Why is lastUpdate set to midnight on January 1, 1970 for some pet.find results?

This is a bug that occurs when searching by breed, but does not affect generic animal searches. We hope to have it fixed soon.

Can I link directly to the photo URLs returned in a pet record?

Absolutely. However, if your activity is excessive and is affecting photo service for other users, we may cut off access temporarily.

What are the photo sizes?

Pet photos come in 5 sizes, which are used on various parts of the Petfinder.com site:

Photos are never scaled "up", so these sizes represent the upper limits of the image dimensions.

What do the status codes mean?

In the current version of the API you can only query adoptable pets, but a future release will allow you to query adopted pets as well. We also hope to give individual shelters the ability to query all of their pets regardless of status.