pet.find

The Basics


This method searches for pets based on the parameters provided and returns a collection of records. We can also determine the level of detail we want to get back (Basic, Full or just pet IDs)

Parameters


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
(Above table taken from official API docs and placed here for ease of reference.)

Additional Information


As you can see above, there are a number of parameters we can include in our calls to this method allowing us to narrow our search. In fact, without using several of them at the same time, we are not likely to get very useful information.

Even with a narrowed search we are still likely to get several results. The count parameter is of particular note here since this specifies the number of results returned per call. This is used in conjunction with the offset parameter and the lastOffset tag to 'page' through results.

Let's take a look at how this works...

offset / lastOffset Example


First, let's take a look at a quick call to search for two dogs in Milwaukee, WI and it's result.

Note: The result is truncated to show only the information most pertinent to this example
var baseURL = "https://api.petfinder.com/"; var reqType = "pet.find?"; var params = "animal=dog&location=Milwaukee, WI&count=2&output=basic&"; var yourKey = "key=123456789&"; var format = "format=json"; var callback = "&callback=?";
var fullURL = baseURL+reqType+params+yourKey+format+callback; $(document).ready(function(){ $("#request").text(fullURL); $.ajax({ dataType: "jsonp", url: fullURL, success:(function(data){ var prettyData = JSON.stringify(data, null,'\t'); $("#results").text(prettyData); }) }); });
{ "@encoding": "iso-8859-1", "@version": "1.0", "petfinder": { "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance", "lastOffset": { "$t": "2" }, "pets": { "pet": {
"options": { "option": [ { "$t": "hasShots" }, { "$t": "housetrained" } ] }, "status": { "$t": "A" }, "contact": { "phone": {}, "state": { "$t": "WI" }, "address2": {}, "email": { "$t": "tirrenia@execpc.com" }, "city": { "$t": "Milwaukee" }, "zip": { "$t": "53201" }, "fax": {}, "address1": { "$t": "P.O. Box 128" } }, "age": { "$t": "Senior" }, "size": { "$t": "M" }, "media": { "photos": { "photo": [ { "@size": "pnt", "$t": "http://photos.petfinder.com/photos/pets/35209788/1/?bust=1464210736&width=60&-pnt.jpg", "@id": "1" } ] } }, "id": { "$t": "35209788" }, "shelterPetId": {}, "breeds": { "breed": { "$t": "Samoyed" } }, "name": { "$t": "Krystal & Lily - ADOPTED!" }, "sex": { "$t": "F" }, "description": { "$t": "These beautiful and well cared for seniors are mother and daughter whose owner can no longer keep them because of medical issues. The mother is 13 and her daughter is 10 and both are healthy. This is an initial posting and we are waiting for more photos and a description. For obvious reasons we do not want to separate them as each might die of a broken heart after all this time. The girls are in the Des Plaines, IL area and rather than putting them in foster care and disrupting their lives further, we are hoping to move them from their current home directly to a new home. We do have all their vet records and as mentioned, they have been very well cared for. Krystal, the daughter (DOB: 6-23-06) is 64 lbs so she could stand to lose some weight. Lily (DOB:6-18-03) is 33 lbs. The mother is not spayed and we will not spay her because of her advanced age, but we were told that she no longer cycles. Lily is spayed. More info will be posted as we received it. Posted: May 25, 2016." }, "mix": { "$t": "no" }, "shelterId": { "$t": "WI55" }, "lastUpdate": { "$t": "2016-06-23T01:53:43Z" }, "animal": { "$t": "Dog" } }, { "options": { "option": [ { "$t": "hasShots" }, { "$t": "altered" }, { "$t": "housetrained" } ] }, "status": { "$t": "A" }, "contact": { "phone": {}, "state": { "$t": "WI" }, "address2": {}, "email": { "$t": "tirrenia@execpc.com" }, "city": { "$t": "Milwaukee" }, "zip": { "$t": "53201" }, "fax": {}, "address1": { "$t": "P.O. Box 128" } }, "age": { "$t": "Young" }, "size": { "$t": "M" }, "media": { "photos": { "photo": [ { "@size": "pnt", "$t": "http://photos.petfinder.com/photos/pets/37087891/1/?bust=1483148672&width=60&-pnt.jpg", "@id": "1" } ] } }, "id": { "$t": "37087891" }, "shelterPetId": {}, "breeds": { "breed": [ { "$t": "Pit Bull Terrier" }, { "$t": "Husky" } ] }, "name": { "$t": "Moose" }, "sex": { "$t": "M" }, "description": { "$t": "This is a courtesy listing and Playing Agains Sams is absolved of any liabilities.\n\nMoose is a 1.5-2 year old husky/bully blend who was almost euthanized for space at a very high kill shelter. He's neutered, microchipped and current on vaccinations. He is around 40-50 pounds. He is being fostered near Green Bay.\n\nHe would be happiest with a larger, assertive (but playful) female who will keep him in line or a female playmate who won't mind playing like a linebacker (preferably a staffy or APBT). He submits to his foster brother (a rambunctious 80lb husky blend) because he knows he's in charge. He seems to do best with large, confident males.\n\nHe cannot go to a home with any small animals (including dogs) because of his high prey drive. The foster mom has been sending him to daycare during the day because of his separation anxiety, but he does great in his crate at night if the foster mom sleeps in a different room with the door closed. He is a people pleaser when he's focused and will benefit from more obedience training and needs a confident and assertive handler. He could easily climb fences unless they are 6 ft tall or higher (typical husky). He has quite a bit of puppy energy left, so a home without small children is ideal because he likes to give hugs and can be somewhat mouthy. \n\nPlease contact Emily, the foster mom directly, if interested in knowing more about this beautiful and fun boy at: emilypearsonphoto@gmail.com or call 920-604-3230. An application, reference check, homevisit and adoption fee are all required." }, "mix": { "$t": "yes" }, "shelterId": { "$t": "WI55" }, "lastUpdate": { "$t": "2016-12-31T13:43:08Z" }, "animal": { "$t": "Dog" } } ] }, "header": { "timestamp": { "$t": "2017-02-28T20:41:54Z" }, "status": { "message": {}, "code": { "$t": "100" } }, "version": { "$t": "0.1" } }, "@xsi:noNamespaceSchemaLocation": "http://api.petfinder.com/schemas/0.9/petfinder.xsd" } }

As you can see in the URL, we have set the count parameter to 2, meaning we will only get two results back.

Likewise, the highlighted lastOffset tag in the result has the value of 2.

Obviously, these are related, but how?

If you think of all the potential results as a stack of widgets this means that:

Say we wanted to grab the next 4 dogs after the two we viewed in the previous example. To do this, we would:

Challenge


Below is a challenge for you. The sample call in the JSFiddle is pulling the first 4 dogs for the zip code 53217.

Your challenge is to complete the yourCall() function to pull only dogs 3 and 4. Compare with the sample pull to check your work.

Be sure to insert your own key and uncomment the call to yourCall() when you are ready to test.