Introduction

Version 5 of the RescueGroups.org API is currently under development. On 2/15/18, we released an alpha developer preview of RescueGroups.org API v5. This is a very early release involving only the Animals endpoint.

This API will change in the coming months. We would greatly appreciate your feedback and ideas for improvement. However, perform development at your own risk. We would expect changes to be relatively minor, but there's no guarantee.

Changes and improvements of note

Closely follows the JSON API specification. v2 was a completely custom and non-standard request and response structure.
Uses industry standard HTTP verbs/methods (GET, PUT, etc) and endpoint URLs. v2 used one URL and everything was a POST.
API Key is accepted only on Authorization header. In v2 the API Key was taken from the URL.
Multiple sort values using +/- are supported. In v2 only one sort field was supported with asc/desc.
Random sort now available. In v2 random was not available.
Distance filter is it's own properties in POST body and supports either miles or kilometers. In v2 the radius filter was included with any other filters.
Related objects can be included in the response body but separate (eg., Organization along with Animals). In v2 related object fields were either mixed with the requested object or an additional request to the API was necessary.
Some fields are considered meta and returned separately from the other properties (see the meta Option). In v2 all fields were the same, even if they were meta.

Swagger definition available

You can download an early draft of our Swagger definition for the public API animals endpoint: http://test-api.rescuegroups.org/v5/public/swagger.php

To open the definition go to the Swagger Editor and click File > Import URL and paste the URL above.

Common questions

Question: When will this version of the API be available in production?

We don't have any ETA for production release yet. We are hoping that it will be in production by the middle of 2018.

Question: Will the current APIs (v2 and the REST API) be deprecated?

Yes, we expect to discontinue use of the current APIs as some time after v5 goes live. We will provide plenty of notice beforehand. We expect to have multiple APIs running in production for at least a year.

Examples

We will be adding examples and improving the Swagger definition as time allows.

Search with advanced filters

Return one random available cat within 100 miles of 20697. This request includes all related objects and all available fields, so it's a bit overwhelming.

Method: POST

Header: Authorization: (your API Key)

URL:

https://test-api.rescuegroups.org/v5/public/animals/search/?include=breeds,colors,fosters,locations,orgs,patterns,pictures,species,statuses,videos,videourls&fields[animals]=activityLevel,adoptedDate,adoptionFeeString,isAdoptionPending,adultSexesOk,ageGroup,isAltered,availableDate,birthDate,isBirthDateExact,breedId,breedString,breedPrimary,breedPrimaryId,breedSecondary,breedSecondaryId,isBreedMixed,isCatsOk,coatLength,color,colorId,isCourtesyListing,
createdDate,isCurrentVaccinations,isDeclawed,descriptionHtml,descriptionText,distinguishingMarks,isDogsOk,earType,exerciseNeeds,eyeColor,fenceNeeds,isNeedingFoster,isFound,foundDate,foundPostalcode,groomingNeeds,isHousetrained,housetrainedReasonNot,indoorOutdoor,
isKidsOk,killDate,killReason,isMicrochipped,name,newPeopleReaction,obedienceTraining,ownerExperience,pattern,patternId,priority,rescueId,searchString,sex,sheddingLevel,sizeGroup,sizePotential,sizeCurrent,sizeUOM,isSpecialNeeds,specialNeedsDetails,species,speciesId,isSponsorable,sponsors,sponsorshipDetails,sponsorshipMinimum,summary,tailType,updatedDate,vocalLevel,isYardRequired,qualities&fields[orgs]=name,street,city,state,citystate,postalcode,postalcodePlus4,country,phone,fax,email,url,facebookUrl,adoptionUrl,donationUrl,sponsorshipUrl,serveAreas,adoptionProcess,about,services,meetPets,type,isCommonapplicationAccepted&fields[breeds]=name&fields[colors]=name&fields[fosters]=salutation,email,firstname,lastname,phoneHome,phoneCell&fields[locations]=name,street,city,state,postalcode,country,url,phone,phoneExt&fields[patterns]=name&fields[pictures]=created,updated,original,large,small&fields[species]=singular,plural,youngSingular,youngPlural&fields[statuses]=name&fields[videos]=fileSize,url&fields[videourls]=url,videoId,urlThumbnail&options=meta&sort=random&limit=1

POST Body:

{
    "data": {
        "filters": [
            {
                "fieldName": "statuses.name",
                "operation": "equals",
                "criteria": "Available"
            },
            {
                "fieldName": "species.singular",
                "operation": "equals",
                "criteria": "Cat"
            }            
        ],
        "filterRadius":
        	{
        		"miles": 100,
        		"postalcode": 20697
        	}
    }
}

Get one animal

Return one specific animal by ID.

Method: GET