Start Here

Things you should know

Terms of Service (TOS)

Your use of the RescueGroups.org API means you agree to the API Terms of Service.

The API is RESTful

The RescueGroups.org API follows the Representational State Transfer (REST) and JSON API specifications closely. All request bodies and responses use the JSON data format.

Although a REST API can be implemented in different ways, following REST principals is important so that you (the developer) can understand the basics of how to communicate with the API. This documentation provides additional descriptions of that communication.

We recommend that you do some background reading before continuing if you're not familiar with REST APIs.

Methods and response codes are purposeful

The HTTP methods you use are important; please be sure to follow the allowed methods for the endpoint. Use GET to retrieve data. Remember there is a difference between POST, PUT, and PATCH. Be extra careful with DELETE because we may not be able to restore your data if you accidentally delete it.

Test first!

Please do your developement in a test environment. Some API calls can change data, and well... accidents happen! The RescueGroups.org staff may not be able to recover your data.

RescueGroups.org provides a Test API you may be able to use for your development efforts.

We also recommend that you use a REST client like Postman to mock-up your requests before developing your application.

How to get started

To communicate with the API you need to have an API key or an account (and user credentials). The example Quick Start uses an API Key to access public data.

Request a public API key

If you'd like to access public data from our API you will need an API key. You can request one from our website: https://rescuegroups.org/services/adoptable-pet-data-api/.

API URL

The base of the API on this server is:

https://dev1-api.rescuegroups.org/v5

All requests to this server should begin with this base path.

You may have access to multiple API environments including Production, and Test, each with their own API URL. Be sure to use the correct environment to prevent data loss!

Use a REST client on your desktop first

There are many freely available REST clients you can use to create and validate your API requests. One that we can recommend is Postman. Here's a quick overview of how you can get started (your mileage may vary):

• Download and install Postman
• Add a request and set the method (try using a GET request first)
• Enter the URL which includes the API URL and endpoint path
• Add the Authorization header with your API key
• Click Send!

For most REST clients, including Postman, you can make life easier by using Environments. An Environment in Postman can store the API base URL and API key/token as variables, making it easier to manage each individual request. In this documentation you may see environment variables shown with curly brases, like {{url}}.

Frequently asked questions

Do I need an account with RescueGroups.org to use the public API?

No, you only need a public API key.

How do I get a public API key?

Request an API key from RescueGroups.org here: https://rescuegroups.org/services/adoptable-pet-data-api/

I am allowed to have more than one API key?

Generally, you should have only one API key. However, We ask that you use a different API key for each website or service you create. This is because we show the list of API keys to our users, and we want to link to each website, service, and application individually.

Why does the API return a different entity type in the response than the type I provided in my request?

In the cases where your request has changed related data, the API will return what we believe is the highest data that changed.

For example, if you PUT a new picture for an animal, we return the animal (instead of the new picture) because the animal's attributes have changed. We don't want the app to know when to retrieve the animal again.

The response will contain any include so that the related data that was created is always returned with the parent entity.

The endpoint reference will state what entity type will be returned for each endpoint.

Rate limits

Rate limits are important to protect the RescueGroups.org system from misuse.

Please develop your code in such a way that avoid flooding our system, or unecessary requests to the API. For example, cache frequently used data like breeds, species, colors, etc. Although we do not advertise specific rate limits, the API will return 429 Too Many Requests if we see an abnormal number of requests from your key.

Please see the Terms of Service for more information about rate limits.

Getting help

Please join us on our Google Groups created specifically for discussion of the RescueGroups.org API. Your questions and improvement ideas are welcome: https://groups.google.com/a/rescuegroups.org/forum/#!forum/apidev

Requests

Headers

You must provide a Content-Type header with every request. The only content type supported is application/vnd.api+json.

You must provide an Authorization header with every request (except /tokens). Depending on the endpoint you must use either an API key or Bearer token Authorization (but never both).

See the Authorization Use Cases below for more information

Authorization

API key (access public data)

The most common authorization is to use a public API key. If you are building a public website you most likely will be using the API key authorization. This should be used to search public adoptable pet data and organizations.

Token-based authorization (access private data)

If you are making a request on behalf of a user with a RescueGroups.org login you should use the token authorization mechanism. You would use the user-provided credentials to generate a token.

When you make a valid request using a token, the response will include an updated Authorization header. You must update your local cache with the new token. See the tokens endpoint for more information.

Use cases

Here are some examples of when you would use API key or token-based authorization:

Methods

Below are the HTTP Methods that are supported by the API. Each endpoint will show which methods are supported.

Query parameters

Query parameters are provided after the question mark in your request like this:

/public/animals/search/available/dogs/?limit=10&page=2&sort=+distance&fields[animals]=name&include=fosters

Here is the list of valid query parameters:

Paging

If you don't provide page or limit in the request URL, the response will be the first page of 25 results. The meta provided in the response will include valuable data that can be used to build paging into your app. See Responses below.

Views

A view is a predefined search that can be specified on the URL. A view is basically a shortcut for using advanced searching with filters. All views can be replicated as filters.

The available views for each endpoint are included in the documentation for that endpoint. Both views and filters control what data objects are included in the response, but cannot be used together.

Views can be used by adding one or more view names to the search endpoint URL.

Advanced searches

Filters

Filters are used in a POST body payload, to the a search endpoint. Both filters and views control what data objects are included in the response, and can be used together.

A filter is made up of three parts:

• Field name
• Operation
• Criteria

Field name

The fieldName is the name of any attribute for the endpoint.

Operation

The operation is the manner in which you want the filter evaluated.

Criteria

The criteria is the value to use for the evaluation.

There are also these special criteria that will be replaced by the API during processing:

Filter processing

Filter processing is an advanced feature, and is not required. If you do not include the filterProcessing property in your searches, all filters will be evaluated with "and" (i.e, "1 AND 2 AND 3"). The first filter is 1, the second is 2, and so on.

Below is an example of a search for adoptable cats and dogs. The filter processing specifies that the results should be both Status of Available, and Species either Cat or Dog.

Radius searches

Distance radius searches are available on specific endpoints. They can accomplished by providing a filterRadius object in the POST data. The distance can be miles or kilometers. The results meta will automatically include distance attribute which is the distance from the provided postal code in the same units as your request (miles or kilometers).

In order to make a valid geodistance search you must provide both a location, and distance. Location can be provided as lat and lon, coordinates (lat,lon), or postalcode. Distance can be provided as either miles or kilometers.

and ONE of:

Including related data

You may request related entities to be included in the response. For example, with a request for animals, you might want to retrieve breed information at the same time.

To do so, simply add an include paramter with a comma separated list of the includes. The documentation for each endpoint lists the available includes.

If you request an invalid include you will receive a 400 error.

Responses

Response codes

The API will return meaningful response codes that should be used to understand how the API handled (or couldn't handle) your request.

In the case of client errors (4XX), the response code along with the response body may provide useful information in resolving the issue with the request.

All unhandled errors on the API side (5XX) are recorded in our system and investigated. However, if you need to contact us regarding the error, please refer to the transactionId from the API response meta so we can identify your request and the resulting error.

Here's a list of the server response codes and when the API returns them. Also see errors below.

Headers

Body

The response body will have one or more of three objects: meta, data, and included.

{
    "meta": {},
    "data": {},
    "included": {}
}

Data

The resulting data is contained in the data object. The data will include type and id as well as a link to self.

Fields are included in the attributes object. The relationships object will contain any related keys.

{
  "data": [{
    "type": "animals",
    "id": "8013243",
    "attributes": {
      "name": "Curly",
      "ageGroup": "Young",
      "birthDate": "2016-03-30T00:00:00Z"
    },
    "relationships": {
      "breeds": {
        "data": [{
            "type": "breeds",
            "id": "35"
          },
          {
            "type": "breeds",
            "id": "62"
          }
        ]
      }
    }
  }]
}

Relationships

Any relationships with other objects (ie., fields with a type of "key") will be included in a relationships object. Each object will include the data type and id.

You can use the type and id to find the object if you requested the object as an include. You can also use the related link to request the full object from the API.

"relationships": {
  "breeds": {
     "data": {
       "type": "breeds",
       "id": 78
     }
  },
  "statuses": {
    "data": [
      {
        "type": "statuses",
        "id": "3"
      }
    ]
  }
}

Includes

Any requested includes are provided in the included object. The object also includes a link to self.

"included": [
    {
        "type": "breeds",
        "id": "78",
        "attributes": {
            "name": "Akita"
        }
    }
}

Metadata

Some responses may include a meta object, including a count of the total number of data objects that matched your search (regardless of the limit that was used).

Additionally, each individual data object may include a meta object.

For example, a request to the animals endpoint will return the total number of animals that matched the search (not the number that is included in the results) and an array of the species that are included in the results.

{
  "meta": {
    "count": 34,
    "countReturned": 25,
    "pageReturned": 1,
    "limit": 25,
    "pages": 2,
    "transactionId": "OxXNFbigaFHi"
  }
}

Error messages

Client errors 4XX

The server may return an error object in the response body. We try to return an error that will be helpful in troubleshooting the issue. For example, we might provide a pointer to the POST data, or a parameter value for a query parameter that was not valid.

The error detail is generally formatted for end-user consumtion.

Example: Error for bad filter field name on POST search

{
  "errors": [
    {
      "status": 400,
      "source": {
        "pointer": "/data/filters/2/fieldName/species.name"
      },
      "title": "Invalid field",
      "detail": "species.name is not a valid filter field"
    }
  ]
}

API system errors 5XX

A 500 error is an error on the RescueGroups.org API side. The error response will include a transactionId which you can provide to RescueGroups.org support to assist us in investigating the system issue.

Interaction Patterns

Although we try to follow best practices and established norms for REST APIs, we thought it would be helpful to describe how to interact with API under certain circumstances, including how to know what data to send to the API, and how the API will respond.

Authorization

The only endpoint that does not require an Authorization header is tokens.

Methods

Be careful to use the correct method when sending requests. For example, there's a big difference between POST and PUT. See the accepted methods and descriptions below.

Views

We've created views to make it easier to complete common searches and avoid having to use advanced filters. The API will combine the filters if you specify multiple views.

You can use views on a POST request and provide additional filters in the POST body. For example, when requesting available animals within a radius, you can use the available view and include the distance criteria in the POST body.

Fields and Includes

You can specify the fields and includes that you want returned with the results. However, if you don't provide that information with your request, the API will return a default set of fields and includes, as described with the endpoints and schemas.

Distance/radius searches

Some endpoints (like animals and organizations) support filtering results by the radius of a postal code. The center of the postal code is used for the distance calculation. You must provide the postal code and either miles or kilometers.

Response Data

When adding or updating data, the API will return the highest level object that has changed. For example, if you add a picture to an animal, the animal object (with all pictures) will be returned. You can use the fields and include parameters on the URL to specify what data you want returned.

Updating relationships

Some relationships are 1-to-1 and should be updated using a single object (not an array). Some relationships are 1-to-many and support an array of objects. Be sure to review the schema to determine if the API is expecting an object or an array of objects.

Endpoint reference

All of the RescueGroups.org API endpoints are listed below for your reference.

Petlists

Petlists

Endpoints

Schema

Includes

Views

Animal breeds

Animal breeds

Endpoints

Schema

Includes

Views

Animal patterns

Animal patterns

Endpoints

Schema

Includes

Views

Animal species

Animal species

Endpoints

Schema

Includes

Views

Animal species

Animal species

Endpoints

Schema

Includes

Views

Animal statuses

Animal statuses

Endpoints

Schema

Includes

Views

Animal colors

Animal colors

Endpoints

Schema

Includes

Views

Animals

Public animal data posted by rescues and shelters.

Endpoints

Schema

Includes

Views

Organizations

Rescues and shelters that have accounts with RescueGroups.org.

Endpoints

Schema

Includes

Views

Schema reference

Animals

Show schema

Animal Pictures

Show schema

Breeds

Show schema

Colors

Show schema

Contacts

Show schema

Locations

Show schema

Organizations

Show schema

Patterns

Show schema

Species

Show schema

Statuses

Show schema

Change Log

January 25, 2020

Minor but significant updates to the beta. The improvements include:

• Geolocation now accepts postalcode, coordinates, or lat and lon in order to calculate distance for animals and organizations. Refer to the Endpoint reference for more information about how to perform a distance query for animals or organizations.

October 3, 2019

We're releasing a major update to the beta of our v5 API. The major changes include:

• All attributes will be returned if no fields are specified.
• If an attribute or relationship doesn't exist (ie., is null), that element will no longer be returned in the result. This will result in smaller results transfer sizes and easier to read and understand result data.
• Compression (gzip) has been enabled on the API server.
• All entity meta properties are now returned as entity attributes. Meta is only provided at the top-level of the response data.
• The top-level meta data now includes more information about the request and results, including a transactionId that can be used when requesting assistance from RescueGroups.org.
• We're simplifying the API by removing endpoints that weren't being used.
• Documentation: Endpoints are now grouped so that all endpoints of the same type (eg., animals) are together.