Welcome to the RescueGroups.org HTTP API!

The RescueGroups.org HTTP API is the only one of its kind – a powerful platform for data management and public data searches.

For additional information about the API, or to request your own public API key, please visit our API service page: http://www.rescuegroups.org/services/adoptable-pet-data-api/

Overview

The HTTP API receives and responds with data in JSON format via an HTTP POST.  Most programming languages have built-in JSON encoding and decoding functions.

Please see below for additional information and examples on how to query for public and private data using the API.

Here are the major components of the RescueGroups.org HTTP API:

• HTTP API "login" action - the process of providing an account number, user name and password to access private methods of the API
• Token and token hash - authentication information passed with each private API call (provided from the login method)
• API key - provided by RescueGroups.org, used to access public API methods
• HTTP API object information and code examples - a distinct record type in the RescueGroups.org database (e.g., animals, contacts, adoptions)
• Definitions - specifies the actions, modules/permissions and fields that are available in the specified object using the provided authentication or API key
• Overview of common HTTP API object actions - methods/functions you can call to complete a task (e.g., search, add, edit)
• Modules - a component of a RescueGroups.org service that is required in order to access an object or action (e.g., animals, contacts, etc)
• Permissions - a component of a RescueGroups.org security role that is required in order to access an object or action (e.g., volunteer, animal add, etc)
• HTTP API field properties and data types - the individual properties of an object that can be searched and modified (e.g., animalName, contactEmail)
• Using search filters with the HTTP API - passed by the client application to the API, restricts the results to only those that meet the specified criteria
• Controlling results - set the result limit, start record, sort/order for the results

API requests for public information

Public access is granted to some data in the RescueGroups.org system.  This includes public animal information and public organization information.

To use the HTTP API for animal and organization queries you need only an API Key.  You do not need to login to the HTTP API or create a token to access public data if you have an API Key.  You can request an API Key from the API Services page.

A lot of public information is available from the RescueGroups.org API including:

• Extensive LIVE adoptable pet data queries including:
  • Radius searches
  • Animal specific location results
  • Animal specific contact information
• Rescue and shelter searches including radius searches
• Events searches including radius searches ** COMING SOON
• Species, breeds, colors, patterns and qualities lists

API requests for private information (and data updates)

Access to non-public information requires a valid RescueGroups.org account, as well as a valid user name and password and permission to the object/information you are requesting.

Before you can request non-public information you will need to authenticate.  Authentication is done with the login action, and then the token and token hash values you receive must be sent with each request that requires authentication.

See the login page for more information on the login request and response.

Using your RescueGroups.org account number, user name and password, you can gain access to the RescueGroups.org platform, including:

• Add and edit objects
• List and search objects

Sending an HTTP API request

Sending a response to the HTTP API is very simple.  In your favorite programming language, create an array of the data you want to send.  Encode that data in JSON format, and POST the data via HTTPS.

See the appropriate User Guide pages for the format of the data to submit for the object or action you are trying to perform.  The required data is different between most actions and objects.

With PHP you could create an array and encode the array into JSON format using the json_encode() function. 

To perform the HTTP POST with PHP you can use the curl libraries.

Handling an HTTP API response

Responses from the HTTP API will be in JSON format.  Decode the response and handle the data as appropriate with your favorite programming language.

See the appropriate User Guide pages for the format of the response data action you are trying to perform.  The response is different between most actions.

With PHP you could decode the JSON response using the json_decode() function.