PLEASE NOTE: AS OF OCTOBER 1, 2020, WE WILL NO LONGER BE PROVIDING API KEYS UNTIL FURTHER NOTICE.
We expose a subset of our platform’s functionality to partners through a JSON-based Web API. Currently this functionality is limited to searching for and looking up the details of pets available for adoption on getyourpet.com.
Submitting a POST or GET request to an API endpoint requires the Content-Type http request header to be set to application/json. See the code examples under the subheading Using an API key.
To obtain an API key, provide one or more IP addresses to be whitelisted, or if you have any questions, please send an email to [email protected].
API Authentication and Authorization
Authentication to the API endpoint is accomplished in two ways. Requests will be authenticated if:
- they include a valid API key
- they originate from a whitelisted IP address
Different rate limits apply depending on which authentication method(s) are used. See Rate Limiting.
Using an API key
Obtain an API key by sending a request to [email protected]. Please include the following:
- your name
- the name and address of your organization
- your phone number
- the domain name of the web site or the name of the app that will use the API
- a brief description of how you intend to use the API
You do not need to provide IP addresses to be whitelisted when making your initial request for an API key.
Once we provide you with an API key, include it with API requests by adding an HTTP request header with the name api-key.
C# Example
using (HttpClient httpClient = new HttpClient())
{
httpClient.DefaultRequestHeaders.Accept.Clear();
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
httpClient.DefaultRequestHeaders.Add("api-key", "3A53B6621BC042669AC9129A48F727EF");
…
}Java Example
HttpPost httpPost = new HttpPost("https://getyourpet.com/api/partnerpetsearch");
httpPost.setHeader("Content-Type", "application/json");
httpPost.setHeader("api-key", "3A53B6621BC042669AC9129A48F727EF");
…Whitelisting IP Addresses
The maximum limit on the rate of requests is allowed when requests originate from an IP address that we have on file for your organization. See Rate Limiting.
To whitelist one or more IP addresses, send an email to [email protected].
Rate Limiting
Access to the API endpoint is unrestricted, but a limit on the rate of requests is imposed based on the presence of a valid API key and whether or not the requests originate from a whitelisted IP address.
| API key is provided | Originating IP address is whitelisted | Requests are Limited to |
| No | No | 1 every 15 seconds |
| Yes | No | 1 per second |
| Yes | Yes | 100 per second |
Note whitelisted IP addresses are only recognized as such in the presence of an API key (hence the No/Yes combination is not represented in the table above).
Internal Server Errors
If an internal server error is encountered, you can contact us and we can investigate. Please email the response body content showing LogCorrelationGuid and Message for each error to be investigated to [email protected].
The logs we use for investigation are only available for a limited time. If you’re interested in us doing an investigation, be sure to contact us as soon as possible after the internal server error is encountered.
Partner Pet Search API
The Partner Pet Search API consists of two methods. One performs a search, and the other provides a direct lookup by PetId.
This section describes the Search and Get by PetId endpoints, and also includes a data dictionary.
Search
The search endpoint allows you to perform a search based on, minimally, a zip code and a search radius. Additional filters can be applied, and the results are returned ordered by either adoption deadline (descending) or distance from the searched zip code (ascending). Results are provided in “pages,” 24 pets per page.
Endpoint Details
| Method | URL |
| POST |
Request Body Examples:
Additional parameters may be included. See Parameters. |
Parameters
In the list of parameters below, for those indicated as optional, pets returned in the response will only be limited by that filter when a non-null value is provided in the request.
| Parameter | Value(s) | Description |
| ZipCode | a valid 5-digit USPS zip code | Required. The center of the area to search. |
| SearchRadiusInMiles | [ 10, 500 ] | Required. The radial distance outward from the zip code to be searched. |
| PageNumber | [ 1, 50 ] | Required. The page number of search results to be returned. |
| OrderBy | “ad”, “adoptiondeadline”, “d”, “distance”, null | Optional. When provided, the response will contain pets ordered by either each pet’s adoption deadline (descending) or the distance the pet is from ZipCode (ascending). When not provided, pets are ordered by adoption deadline (descending). |
| PetType | “c”, “cat”, “cats”, “d”, “dog”, “dogs”, null | Optional. When provided, the response will contain a specific type of pet. |
| Gender | “f”, “female”, “females”, “m”, “male”, “males”, null | Optional. When provided, the response will contain pets of a specific gender. |
| AgeYearsMin | [ 0, 18 ] | Optional. When provided, the response will contain pets at least the specified number of years old. |
| AgeYearsMax | [ 1, 20 ] | Optional. When provided, the response will contain pets no more than the specified number of years old. |
| ActivityLevelMin
ActivityLevelMax |
“l”, “low”, “a”, “average”, “h”, “high”, null | Optional. When provided, the response will contain pets in the activity level range specified by ActivityLevelMin and ActivityLevelMax. Either both must be provided, each with a non-null value, or neither provided, or both provided with a value of null. |
| GoodWithChildrenUnder5
GoodWithChildren5to10 GoodWithChildrenOver10 GoodWithCats GoodWithDogs |
“t”, “true”, “f”, “false”, null | Optional. When provided, the response will contain pets that are good with children under 5 years old, children 5 to 10 years old, children over 10 years old, cats, and dogs. Logical “and” across non-null “GoodWith” parameters found in the request. |
| SizeMin
SizeMax |
“xs”, “extrasmall”, “s”, “small”, “m”, “medium”, “l”, “large”, “xl”, “extralarge” | Optional. When provided, the response will contain dogs in the size range specified by SizeMin and SizeMax. Either both must be provided, each with a non-null value, or neither provided, or both provided with a value of null. |
| CoatShort
CoatMedium CoatLong CoatHairless CoatWire CoatCurly |
“t”, “true”, “f”, “false”, null | Optional. When provided, the response will contain pets whose coat is short, medium, long, hairless, wire or curly. Logical “or” across non-null “Coat” parameters found in the request. |
| Claws | “a”, “all”, “n”, “none”, “ro”, “rearonly”, “noro”, “noneorrearonly” | Optional. When provided, the response will contain cats with claws, without claws, with only rear claws, or a combination of cats with no claws or with only rear claws. |
| Colors | An array containing one or more of the following: “BLACK”, “Black”, “black”, “BLUE”, “Blue”, “blue”, “BRINDLE”, “Brindle”, “brindle”, “BROWN”, “Brown”, “brown”, “BUFF”, “Buff”, “buff”, “CHOCOLATE”, “Chocolate”, “chocolate”, “FAWN”, “Fawn”, “fawn”, “GOLD”, “Gold”, “gold”, “GREY”, “Grey”, “grey”, “HARLEQUIN”, “Harlequin”, “harlequin”, “LIVER”, “Liver”, “liver”, “MERLE”, “Merle”, “merle”, “PARTICOLOR”, “Particolor”, “particolor”, “RED”, “Red”, “red”, “SABLE”, “Sable”, “sable”, “SILVER”, “Silver”, “silver”, “TAN”, “Tan”, “tan”, “TRICOLOR”, “Tricolor”, “tricolor”, “WHEATON”, “Wheaton”, “wheaton”, “WHITE”, “White”, “white”, “YELLOW”, “Yellow”, “yellow” | Optional. When provided, the response will contain pets whose color(s) match the color(s) provided. |
| NewlyAvailable | “t”, “true”, “f”, “false”, null | Optional. When provided, the response will contain pets whose profile has been published in the past 3 days. |
Response
| HTTP Status Code | Example Response(s) |
| 200 | dog, minimally populated: |
|
|
| dog, maximally populated: | |
|
|
| cat, minimally populated: | |
|
|
| cat, maximally populated: | |
|
|
| 400 | Invalid ZipCode and PetType example: |
|
|
| 401 | Response Header: |
|
|
| Response Body: | |
|
|
| 429 | Returned if the frequency of requests is too high. See Rate Limiting. |
|
|
| 500 | Returned if there is an unexpected error occurs while processing the request. See Internal Server Errors. |
|
Get by PetId
The get by pet id endpoint allows you to get the details of a specific pet. The same format is used for the response here as is used in searching. The difference is that these additional fields are populated:
- AdditionalPhotoUrls (populated if a pet’s profile has additional photos)
- VideoContentType (populated if a pet’s profile has a video)
- VideoUrl (populated if a pet’s profile has a video)
- Story (always populated)
Endpoint Details
| Method | URL |
| GET |
Examples: |
Parameters
| Parameter | Value | Description |
| PetId | a valid PetId found in the response of to a search request | Required. Indicates the pet whose details are to be returned. |
| ZipCode | a valid 5-digit USPS zip code | Optional. The zip code to use in computing DistanceInMiles. If omitted then DistanceInMiles will be null. |
Response
| HTTP Status Code | Example Response |
| 200 | dog, minimally populated: |
|
|
| dog, maximally populated: | |
|
|
| cat, minimally populated: | |
|
|
| cat, maximally populated: | |
|
|
| 400 | Invalid ZipCode example: |
|
|
| 401 | Response Header: |
|
|
| Request Body: | |
|
|
| 404 | Returned if the PetId value in the request is not found. |
|
|
| 429 | Returned if the frequency of requests is too high. See Rate Limiting. |
|
|
| 500 | Returned if there is an unexpected error occurs while processing the request. See Internal Server Errors. |
|
Data Dictionary
Successful responses to both the Search and Get by PetId endpoints return information about pets available for adoption. Search returns a list of pets, while Get by PetId returns the information about a single pet. The table below gives some additional information about the information returned.
For string properties, the notation string(#) indicates the maximum length in the parenthetical. For example, string(50) indicates that strings returned for that property are limited to a maximum of 50 characters.
Most properties are returned by both Search and Get by PetId, but a handful of properties are only returned by Get by PetId. This is indicated in the Returned By column in the table below.
For properties that are populated conditionally, an explanation is provided in the description.
Pet
| Property | Data Type | Returned By | Populated | Description |
| PetId | int | Both | Always | A strictly positive integer that is the unique key for identifying pets in the system. |
| AdoptionDeadline | date | Both | Always | The date by which the pet’s Guardian needs to find the pet a home. Formatted in JSON as yyyy-mm-dd. |
| NewlyAvailable | bool | Both | Always | Indicates if the pet has recently become available for adoption. |
| Name | string(50) | Both | Always | The pet’s name. |
| PetType | string(3) | Both | Always | The type of the pet. Values:
· cat |
| Gender | string(6) | Both | Always | The gender of the pet. Values:
· female |
| Breeds | array of Breed (see next table) | Both | Conditionally | An array of up to 3 Breeds indicating the breed(s) of the pet. If the pet’s breed is unknown to its Guardian then this property will be null. |
| BreedsForDisplay | string(60) for search results; string(160) for single pet lookup |
Both | Always | The breed(s) of the pet formatting using getyourpet.com display logic / rules. When Breeds is null then this will be “unknown / mixed breed”. When formatted for search results, at most one breed is included, with “mix” added if there are two or more breeds. For a single pet lookup this is a comma-delimited string of all breed names. |
| Size | string(20) | Both | Conditionally | The size of a dog (only populated for dogs; null for cats). Values:
· xs (up to 10lbs.) |
| Coat | string(8) | Both | Always | The pet’s coat length / type. Values:
· short |
| Claws | string(9) | Both | Conditionally | The status of a cat’s claws (only populated for cats; null for dogs). Values:
· all |
| Color | string(20) | Both | Always | The pet’s color. Values:
· black |
| AgeYears | int | Both | Always | The age of the pet. |
| AgeMonths | int | Both | Always | |
| SpayedNeutered | bool | Both | Always | Indicates if the pet is spayed (female pets) or neutered (male pets). |
| ActivityLevel | string(7) | Both | Always | The pet’s activity level. Values:
· low |
| GoodWith | array of string(16) | Both | Conditional | The types of children and other pets the pet is good to live with as indicated by the pet’s Guardian. If none apply, GoodWith will be null. Values:
· cats |
| PrimaryPhotoUrl | string(100) | Both | Always | The URL to the pet’s primary photo. |
| AdditionalPhotoUrls | array of string(100) | Get by PetId | Conditional | The URLs to the pet’s additional photos. If no additional photos, AdditionalPhotoUrls will be null. |
| HasVideo | bool | Both | Always | Indicates whether the pet’s Guardian has included a video in the pet’s profile. |
| VideoContentType | string(25) | Get by PetId | Conditional | The content type of the pet’s video (if the pet has a video). Values:
· video/mp4 |
| VideoUrl | string(150) | Get by PetId | Conditional | The URL to the pet’s video (if the pet has a video). |
| Story | string(400) | Get by PetId | Always | A narrative provided by the current Guardian of the pet. |
| ProfileUrl | string(100) | Both | Always | The URL of the pet on getyourpet.com. Use this URL within your implementation to send a user to getyourpet.com where they’ll get to see the pet’s full profile and the option to connect with the pet’s Guardian. Note the value of the acquisitionCode query string parameter is generated based on your API key. Please do not make any assumptions about the format of this URL. We reserve the right to change its format at any time. |
| ZipCode | string(5) | Both | Always | The zip code where the pet lives. Guaranteed to be a valid, 5-digit USPS zip code. |
| City | string(100) | Both | Always | The city where the pet lives. |
| State | string(2) | Both | Always | The state where the pet lives. |
| Latitude | double | Both | Always | The latitude of the zip code where the pet lives. |
| Longitude | double | Both | Always | The longitude of the zip code where the pet lives. |
| DistanceInMiles | double | Both* | Conditional | The distance from the zip code in the request to the zip code where the pet lives.
* ZipCode is optional for Get by PetId. When ZipCode is not provided to Get by PetId then DistanceInMiles will be null. |
| DistanceInMiles ForDisplay | string(6) for search results; string(20) for single pet lookup | Both* | Conditional | DistanceInMiles formatted as “# mi” for search results and “# miles away” or “within 1 mile of ZZZZZ” for single pet lookup (where ZZZZZ is the zip code query string parameter value of a single pet lookup request).
* ZipCode is optional for Get by PetId. When ZipCode is not provided to Get by PetId then DistanceInMilesForDisplay will be null. |
Breed
When returned, each breed is always fully populated with a BreedId and a BreedName.
| Property | Data Type | Description |
| BreedId | int | A strictly positive integer that is the unique key for identifying breeds in the system. |
| BreedName | string(50) | The name of the breed. |