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)
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 |
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...
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 exampleAs 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:count
is the number of widgets we are going to be looking at.lastOffset
represents the index of the last widget we are seeing in the results.offset
, if included, tells the API the index of the last widget we saw, so it will then grab the next count
widgets and return them to us.
Say we wanted to grab the next 4 dogs after the two we viewed in the previous example. To do this, we would:
count
to 4 (we want to get 4 results back)offset
to 2 (since the index of the last dog we viewed was 2). This will make the API treat the dog after this as the first dog to grab.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.