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 email@example.com and we will respond as soon as possible.
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 firstname.lastname@example.org 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.
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
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
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.
lastUpdate set to midnight on January 1, 1970 for some
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:
|x||large||original, up to 500x500|
|t||thumbnail||scaled to 50 pixels tall|
|pn||petnote||up to 320x250|
|pnt||petnote thumbnail||scaled to 60 pixels wide|
|fpm||featured pet module||scaled to 95 pixels wide|
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.
What are the pet animal values?
|smallfurry||Small & Furry|
|reptile||Scales, Fins & Other|
What are the pet sizes?
What are the pet ages?
|Baby, Young, Adult, Senior|
What are the pet options?
|altered||Spayed / Neutered|
|hasShots||Has Current Shots|
|noCats||Not Good With Cats|
|noDogs||Not Good With Dogs|
|noKids||Not Good With Kids|
|specialNeeds||Has Special Needs|