Adopt-a-Pet.com Pet List API Documentation for Partners

Document Version 1.2.1 last updated November 7th, 2014

Table of Contents

Introduction

Overview

Audience

API Features

API Design Overview

API Functions

Global Inputs

Global Outputs

Global Data Type Notes

Pet List Functions

Error Codes

Getting Help

Glossary of Terms

Terms of Use

1. Service

2. Appropriate Conduct and Prohibited Uses

3. Adopt-a-Pet.com Rights

4. Adopt-a-Pet.com Logo and Brand License

5. Indemnity

6. DISCLAIMER

Appendix A: Limited Pet Details Output Data Structures

pet Structure

images Sub-Structure

Appendix B: Pet Details Output Data Structures

pet Structure

images Sub-Structure

Appendix C: Output Formats and Examples

XML Output

JSON Output

Introduction [top]

This documentation is for partners of Adopt-a-Pet.com. The Adopt-a-Pet.com API (Application Programming Interface) is a series of tools that allows partners to use Adopt-a-Pet.com's pet adoption features and pet data in other applications. These tools can only be used pursuant to the contractual details of the partnership, and acknowledgement of Adopt-a-Pet.com on all pages of the implementation of these tools is required as per that contract (see Terms of Use).

Overview

The Adopt-a-Pet.com API will allow partners to query the Adopt-a-Pet.com database for information that can be used to build pet listings and view pet details information including pet photos.

Audience

This document is intended for software developers who are already familiar with the concept of an API and object oriented programming concepts. Developers should also be familiar with the Adopt-a-Pet.com interface from a user's point of view.

API Features

The Adopt-a-Pet.com Pet List API provides the following features:

  1. Retrieve the list of available pets for the shelter or rescue
  2. Retrieve the details for a specific pet

API Design Overview [top]

The API is designed to receive inputs from your custom application using HTTP GET requests that are formatted with a script name and a querystring. For example:

https://api.adoptapet.com/search/pets_at_shelter?key=A34F48&v=1&output=xml&shelter_id=2342

The results of the request will be a text result formatted in one of the available output styles. From there, you can use your own output parser to break the returned data into local data structures, and then process them as you want to. See Appendix C: Output Formats and Examples below for more.

Using the API functions provided, you should be able to build a pet list interface that is customized for your website's look and feel. You can also use the pets_at_shelters function (note that "shelters" is plural, unlike the pets_at_shelter function) to create a pet list for multiple shelters. This would be especially useful for organizations that have multiple brannch locations. Here's an example API call:

https://api.adoptapet.com/search/pets_at_shelters?key=A34F48&v=1&output=xml&shelter_id=2342&shelter_id=17293&shelter_id=8323

API Functions [top]

This section describes the functions that are available in this version of the API, what inputs can be passed, and what outputs are returned.

Global Inputs

The following inputs can be submitted with every function call to the API. Globally required inputs are in bold.

API Key

key=

A string that identifies your partner account and prevents unauthorized use of the API.

API Version

v=

A string that indicates what version of the API you expect to be querying.The current version options are "beta", "1" (the default) and "2".

Output Format

output=

A string that indicates what output format you want returned from your function calls. The current output format options are "xml" (the default) and "json". See Appendix B for more information.

Global Outputs

Each API query will include a response element called "status" whose value will be "ok" or "fail". If the status is "fail", we will also return error codes and error messages – see the Error Codes section below.

Global Data Type Notes

The output data structures will generally be one of these four types:

Pet List Functions

Function Name

Inputs

Outputs

Notes

pets_at_shelter

  • shelter_id
  • start_number (default: 1)
  • end_number (default: 50, max: 25000)
  • meta_only (default: 0)
  • total_pets
  • returned_pets (this call)
  • pets
    • order
    • results_photo_url
    • results_photo_width
    • results_photo_height
    • large_results_photo_url
    • large_results_photo_width
    • large_results_photo_height
    • details_url
    • species
    • pet_id
    • pet_name
    • sex
    • age
    • size
    • primary_breed
    • addr_city
    • addr_state_code

If "meta_only" is passed as true, we'll only return result counts, not actual pet data.

You can create your own pagination scheme by passing a start and ending number for the subset of results you want back.

pets_at_shelters

  • shelter_ids
  • start_number (default: 1)
  • end_number (default: 50, max: 25000)
  • meta_only (default: 0)
  • total_pets
  • returned_pets (this call)
  • pets
    • order
    • results_photo_url
    • results_photo_width
    • results_photo_height
    • large_results_photo_url
    • large_results_photo_width
    • large_results_photo_height
    • details_url
    • species
    • pet_id
    • pet_name
    • sex
    • age
    • size
    • primary_breed
    • addr_city
    • addr_state_code
    • shelter_name
    • shelter_details_url

If "meta_only" is passed as true, we'll only return result counts, not actual pet data.

You can create your own pagination scheme by passing a start and ending number for the subset of results you want back.

limited_pet_details
Get the limited details for a single pet.

  • pet_id
  • See Appendix A below, "Limited Pet Details Output Data Structures"


pet_details
Get the full details for a single pet.

  • pet_id
  • See Appendix B below, "Pet Details Output Data Structures"


Error Codes

API function call responses will always always include a top level attribute of status and a value of fail in the event of an error. A nested error data structure will also be included in the response, and it has the following attributes:

The table below describes failure error codes that may be returned from API function calls:

Error Code

Error Message

Meaning

400

input_invalid

A field had invalid or badly formatted data

401

invalid_key

The API key submitted was invalid, or was submitted from an unauthorized domain

403

access_denied

Your partner account does not have permission to perform the request submitted

412

input_missing

A required field was not submitted in the request.

450

validation_failure

An error in the information submitted prevented the request from being completed. Check the missing, invalid, or unknown attributes for further information.

500

tech_failure

The system was not able to complete your request for some other reason

503

resource_unavailable

The system has received too many requests from you and will not complete your request

Examples of complete error outputs can be found in the Appendix C: Output Formats and Examples section below.

Getting Help [top]

If you've read the information in this document and need assistance implementing the API calls in your application, or have questions or suggestions for improving the API, please contact us by sending e-mail to helpdesk@adoptapet.com.

Glossary of Terms [top]

Term

Meaning

API

Application Programming Interface. An API allows you to create your own program-controlled modules that interface with the functionality of the system providing the API.

API Key

The API key is a unique identifier string assigned to each partner that makes use of the Adopt-a-Pet.com API. It insures that only your custom software can make use of the API features enabled for your account.

JSON

JSON is a lightweight computer data interchange format. JSON finds its main application in Ajax web application programming, as a simple alternative to using XML for asynchronously transmitting structured information between client and server.

Super Breed

A Super Breed is an internal breed name that is a combination of other actual pet breeds. For example, "Shepherds (All Types)" is a Super Breed that is made up of 10 actual dog breeds including Anatolian Shepherds, Australian Shepherds, etc.

Validation

Validation is the process of insuring that the information submitted to the site (by the user on the site, through the API, or otherwise) has the necessary and correctly-formatted information to successfully process the request.

XML

The Extensible Markup Language (XML) is a W3C-recommended general-purpose markup language that supports a wide variety of applications. Its primary purpose is to facilitate the sharing of data across different information systems, particularly systems connected via the Internet.

Terms of Use [top]

Use of the Adopt-a-Pet.com syndicated search API is strictly limited to contractually agreed upon partner organizations, and only for the contractually agreed upon time period. Any other use of the API for any other reason or by any other entity is strictly prohibited. By using the Adopt-a-Pet.com API (the "API"), Partner Organizations ("You") accept and agree to be bound by the following terms and conditions (the "Terms of Use").

1. Service

1.1 Description of API. The API consists of code that allows you to embed a homeless pet search on your site that draws its real-time data from the Adopt-a-Pet.com database of homeless pets.

1.2 Modifications. Adopt-a-Pet.com reserves the right to release subsequent versions of the API and to require You to obtain and use the most recent version. Adopt-a-Pet.com may modify the Terms of Use at any time with or without notice, and will inform you if any such change is made.

2. Appropriate Conduct and Prohibited Uses

The Service may be used only for services that are contractually agreed upon in writing with Adopt-a-Pet.com.

You agree that You are responsible for proper use of the API and the data you have access to. Such proper use is the use agreed upon in the signed contract, and is designed to display pets for adoption and promote homeless pet adoption at Adopt-a-Pet.com partner shelters.

By way of example, and not as a limitation, You agree that when using the Service, You will not:

  1. use Adopt-a-Pet.com homeless pet data to promote breeding or commercial sale of pets;
  2. display homeless pet or shelter data in any manner that causes harm to animals or to Adopt-a-Pet.com partner shelters.

Adopt-a-Pet.com reserves the right to cancel the use of the API at any time if:

  1. You violate the terms of the agreement;
  2. the data is used in any way other than the intended agreed upon and specific use to promote homeless pet adoption on the agreed upon website in a credited "powered by" Adopt-a-Pet.com pet search;
  3. Anything about the use of this data is deemed by us to create the impression that Adopt-a-Pet.com is endorsing, or is otherwise promoting a specific company or its products, as such endorsement or promotion could jeopardize Adopt-a-Pet.com's tax exempt status.

3. Adopt-a-Pet.com Rights

For purposes of the Terms of Use, "Intellectual Property Rights" shall mean any and all rights existing from time to time under patent law, copyright law, semiconductor chip protection law, moral rights law, trade secret law, trademark law, unfair competition law, publicity rights law, privacy rights law, and any and all other proprietary rights, and any and all applications, renewals, extensions and restorations thereof, now or hereafter in force and effect worldwide. As between You and Adopt-a-Pet.com, You acknowledge that Adopt-a-Pet.com owns all right, title and interest, including without limitation all Intellectual Property Rights, in and to the Service and that You shall not acquire any right, title, or interest in or to the Service, except as expressly set forth in the Terms of Use and the signed contract with Adopt-a-Pet.com.

4. Adopt-a-Pet.com Logo and Brand License

For purposes of the Terms of Use, "Adopt-a-Pet.com Logo and Brand" shall be defined as the trade names, trademarks, service marks, logos, domain names, and other distinctive brand features of Adopt-a-Pet.com. Adopt-a-Pet.com hereby grants to You a nontransferable, nonsublicenseable, nonexclusive license during the Term to display Adopt-a-Pet.com Logo and Brand for the purpose of promoting or advertising that You use the API Service in accordance with a signed agreement with Adopt-a-Pet.com.

You understand and agree that Adopt-a-Pet.com has the sole discretion to determine whether your use of Adopt-a-Pet.com brand features is in accordance with the above restrictions.

5. Indemnity

You agree to hold harmless and indemnify Adopt-a-Pet.com, and its subsidiaries, affiliates, officers, agents, and employees, advertisers or partners, from and against any third party claim arising from or in any way related to your use of the API, violation of these Terms of Use or any other actions connected with use of Adopt-a-Pet.com services, including any liability or expense arising from all claims, losses, damages (actual and consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature.

6. DISCLAIMER

YOU EXPRESSLY UNDERSTAND AND AGREE THAT ANY MATERIAL DOWNLOADED OR OTHERWISE OBTAINED THROUGH THE SERVICE IS DONE AT YOUR OWN DISCRETION AND RISK AND THAT YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM OR LOSS OF DATA THAT RESULTS FROM THE DOWNLOAD OF ANY SUCH MATERIAL.

YOU EXPRESSLY UNDERSTAND AND AGREE THAT ADOPT-A-PET.COM SHALL NOT BE LIABLE TO YOU FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES, INCLUDING BUT NOT LIMITED TO, DAMAGES FOR LOSS OF PROFITS, GOODWILL, USE, DATA OR OTHER INTANGIBLE LOSSES, RESULTING FROM: (i) THE USE OR THE INABILITY TO USE THE SERVICE; (ii) THE COST OF PROCUREMENT OF SUBSTITUTE GOODS AND SERVICES RESULTING FROM ANY GOODS, DATA, INFORMATION OR SERVICES PURCHASED OR OBTAINED OR MESSAGES RECEIVED OR TRANSACTIONS ENTERED INTO THROUGH OR FROM THE SERVICE; (iii) UNAUTHORIZED ACCESS TO OR ALTERATION OF YOUR TRANSMISSIONS OR DATA; (iv) STATEMENTS OR CONDUCT OF ANY THIRD PARTY ON THE SERVICE; OR (v) ANY OTHER MATTER RELATING TO THE SERVICE.

Appendix A: Limited Pet Details Output Data Structures [top]

When successful, the limited_pet_details method returns a structure containing information about the requested pet, as well as info about the shelter that is placing the animal for adoption. Specifically, a successful response will contain a pet structure with an extensive list of attributes and values for the pet and its shelter. Additionally, if and only if the pet has any associated photos, the pets structure will also contain an images sub-structure with its own attributes and value pair(s) related to the pet photo(s).

The tables below describe the fields that may be returned in the limited_pet_details response (note that all fields may be null, except the ones marked with an asterisk):

pet Structure

Name

Type

Description

Example

*primary_breed

String


American Bulldog

*species

String


Dog

act_quickly

Boolean

If it's important to adopt this pet soon


addr_city

String

Shelter address

Los Angeles

addr_state_code

String

Shelter address

CA

age

String


Puppy

automap

Boolean

Show a link to a map of the location


color

String


White

declawed

Boolean



hair_length

String


Long

housetrained

Boolean



pet_details_url

String

URL of official pet details page

https://www.adoptapet.com/pet/625204-richmond-indiana-beagle-mix

pet_id

Integer

Internal unique identifier

67616

pet_name

String


Fluffy

purebred

Boolean



secondary_breed

String


Shih Tzu

sex

String


Female

size

String


Med. 26-60 lbs (12-27 kg)

special_needs

Boolean



images

Structure

One photo for the pet – see below


experienced_adopter

Boolean

Whether or not this pet needs an experienced adopter (version 2).

family_label

String

This will either be 'breed' or 'species' depending on the type of pet. See below for more discussion. (version 2)

images Sub-Structure

Name

Type

Description

Example

*thumbnail_url

String


https://s3.amazonaws.com/pet-uploads.adoptapet.com/e/2/5/92794427.jpg

*thumbnail_width

Integer


125

*thumbnail_height

Integer


75

*original_url

String

URL to largest available version of the image

https://s3.amazonaws.com/pet-uploads.adoptapet.com/6/f/3/92702234.jpg

*original_width

Integer


300

*original_height

Integer


250

It is possible that pet details could be requested for a pet which has become unavailable. In this case, a successful response will still be returned, but the pet structure will simply contain one attribute/value pair: "pet_state: unavailable".

A note on the family_label field: When displaying a pet's details the primary_breed and secondary_breed might contain a species of animal instead of a breed for some types of animals (e.g. small_animal: hamster or farm_animal: sheep). For those type of animals (small_animal, reptile and farm_animal) the family_label field will be set to the string 'species' and for the rest it will be 'breed'. When displaying primary_breed and secondary_breed, you should label it with family_label to be most accurate.

Appendix B: Pet Details Output Data Structures [top]

When successful, the pet_details method returns a structure containing information about the requested pet, as well as info about the shelter that is placing the animal for adoption. Specifically, a successful response will contain a pet structure with an extensive list of attributes and values for the pet and its shelter. Additionally, if and only if the pet has any associated photos, the pets structure will also contain an images sub-structure with its own attributes and value pair(s) related to the pet photo(s).

The tables below describe the fields that may be returned in the pet_details response (note that all fields may be null, except the ones marked with an asterisk):

pet Structure

Name

Type

Description

Example

*primary_breed

String


American Bulldog

*shelter_name

String


Animal Avengers

*species

String


Dog

act_quickly

Boolean

If it's important to adopt this pet soon


adoption_process

html

Explanation of the shelter's adoption process, fees, contracts, etc.


addr_city

String

Shelter address

Los Angeles

addr_line_1

String

Shelter address

PMB-23

addr_line_2

String

Shelter address

7336 Santa Monica Blvd.

addr_postal_code

String

Shelter address

90046

addr_state_code

String

Shelter address

CA

addr_country_code

String

Shelter address

US, or CA

age

String


Puppy

areas_served

String

Description of cities, towns and/or counties served by the shelter


automap

Boolean

Show a link to a map of the location


color

String


White

contact_person

String

Person whom interested adopters should contact

Debbie Smith

declawed

Boolean



description

html



donation_url

String

Shelter's online donation page


email

String

Shelter's email address

adoption@shelter.com

fax_area_code

Integer


765

fax_number

String


233-1282

good_with_cats

Boolean



good_with_dogs

Boolean



good_with_kids

Boolean



good_with_birds

Boolean

(version 2)

good_with_small_animals

Boolean

(version 2)

hair_length

String


Long

housetrained

Boolean



pet_code

String

Shelter's reference code for the pet

A453-BG4

pet_id

Integer

Internal unique identifier

67616

pet_name

String


Fluffy

phone_area_code

Integer


325

phone_extension

String


x23

phone_number

String


655-4220

purebred

Boolean



secondary_breed

String


Shih Tzu

sex

String


Female

shelter_id

Integer

Internal unique identifier for associated shelter. Can be used to link back to shelter info or to other pets at shelter.

12345

shelter_desc

html

Description of shelter, mission statement, etc.


shelter_driving_dir

html

Directions on how to get to the shelter


shots_current

Boolean



size

String


Med. 26-60 lbs (12-27 kg)

spayed_neutered

Boolean



special_needs

Boolean



website_url

String

Shelter's website

https://www.animalavengers.com

images

Structure

One or more photos for the pet – see below


bonded_to

Integer

Internal unique identifier for pet "bonded" to this one. (version 2)

67617

experienced_adopter

Boolean

Whether or not this pet needs an experienced adopter. (version 2)

rideable

Boolean

Whether or not this pet can be ridden. Only applies to horses. (version 2)

family_label

String

This will either be 'breed' or 'species' depending on the type of pet. See below for more discussion. (version 2)

images Sub-Structure

Name

Type

Description

Example

*thumbnail_url

String


https://s3.amazonaws.com/pet-uploads.adoptapet.com/e/2/5/92794427.jpg

*thumbnail_width

Integer


125

*thumbnail_height

Integer


75

*original_url

String

URL to largest available version of the image

https://s3.amazonaws.com/pet-uploads.adoptapet.com/6/f/3/92702234.jpg

*original_width

Integer


300

*original_height

Integer


250

It is possible that pet details could be requested for a pet which has become unavailable. In this case, a successful response will still be returned, but the pet structure will simply contain one attribute/value pair: "pet_state: unavailable".

A note on the family_label field: When displaying a pet's details the primary_breed and secondary_breed might contain a species of animal instead of a breed for some types of animals (e.g. small_animal: hamster or farm_animal: sheep). For those type of animals (small_animal, reptile and farm_animal) the family_label field will be set to the string 'species' and for the rest it will be 'breed'. When displaying primary_breed and secondary_breed, you should label it with family_label to be most accurate.

Appendix C: Output Formats and Examples [top]

Currently there are two available output formats for API function calls: XML and JSON. Ideally, there will be tools available for your programming language of choice that converts data in one of these formats to a data structure you can easily manipulate.

Below are some examples showing some sample outputs using both the XML and JSON output formats.

XML Output

The returned content type for an XML request will be Content-Type: text/xml; charset=ISO-8859-1. The XML response will always include a top level tag of <result>. This tag will always have a single attribute of "status" which will be set to "ok" upon success, or "fail" if there is an error. Each entity returned will be represented by a nested tag, with key/value properties as attributes and values. For example, here is a complete error response in XML format:

 

<result status="fail">
  <error code="450" details="The method inputs didn't pass validation. Please check the missing, invalid, and unknown stuctures for more information." msg="validation_failure">
    <invalid field="shelter_id" msg="Please check your submission: it appears that we didn't recognize a field you entered."/>
  </error>
</result>

Notice that the values are properly XML-escaped. In some cases, an attribute in the response may point to a nested data structure. In those circumstances, the keys will become nested tags, which may form a list of additional tags with more attribute/value pairs. Here is an example of an abbreviated and contrived response from the limited_pet_details method:

 

<result status="ok">
  <pet pet_name="Fluffy"
       species="Dog">
    <images url="https://..." />
    <images url="https://..." />
  </pet>
</result>

JSON Output

The returned content type for a JSON request will be Content-Type: application/json; charset=ISO-8859-1. The JSON response object always has a single attribute of "status" which will be set to "ok" upon success, or "fail" if there is an error. Each entity returned will be represented by a nested pair, with key/value properties as attributes and values. For example, here is the same complete error response from above, this time rendered in JSON format:

 

{
    "status":"fail",
    "error":{
        "code":412
        "details":"Field \"foo\" was missing.",
        "msg":"input_missing",
    }
}

Notice that the values are properly escaped. Also note that the actual message may be returned on one line for efficiency, but is formatted here for readability.

In some cases, an attribute in in the response may point to a nested data structure, which JSON represents as an array of pairs. Here is an example of a contrived response from the limited_pet_details method, mimicking the XML example from above:

 

{
    "status":"ok",
    "pet":{
        "pet_name":"Fluffy",
        "species":"Dog",
        "images":[
            {"url":"https://..."},
            {"url":"https://..."}
        ]
    }
}