We have updated our API Terms of Service. Please review the entire terms before continuing to use the API. Your use of the API means you accept and agree to the updated API Terms of Service found here: https://rescuegroups.org/api-terms-of-service/
Included with your API key is the ability to download the complete animal and organization database via FTP. This is the easiest way to do a bulk download of the adoptable pets and rescue/shelter (org) information.
- Request an API key from RescueGroups.org.
- Enable your FTP data export.
- Download your data files.
- Perform the initial import of the data.
- Perform daily updates of the data.
- Perform regular scrubs of the data.
Request an API key from RescueGroups.org
You can request an API Key here:
Enable your FTP data export
Soon after your API Key is created you will receive an email with a link to update your API key information. The API key edit page will also include the option to enable the FTP-based download of the pet data.
- Click the link you received in the email.
- Next to Enable daily JSON data file download via FTP select Yes.
- Click Save.
Your FTP credentials will be emailed to you. You can use that FTP account to download the full adoptable pet data.
Your API key's data files will be available by 6 AM Eastern the day after you enable the FTP-based export.
Download your data files
Login to the FTP account you created above and download the following files:
- orgs_n.json - all organization data
- pets_n.json - all animal data
- updatedpets_n.json - updated pets from the past 24 hours
- newpets_n.json - new pets from the past 24 hours
- petlist.csv - a list of all available animalIDs
Multiple files may be generated for the organization, animal, new pets, and updated pets files. The file names will be numbered (e.g., orgs_1.json, orgs_2.json).
Perform the initial import of the data
Import the data from orgs_n.json and pets_n.json into your database.
Please see the section Image/picture related topics below for important information on how to handle pictures and picture changes.
Perform daily updates of the data
On a daily basis, download the adoptable pet data from your API key's FTP account. Process the updated data.
- Process the data for each pet in the updatedpets_n.json files.
- Add the pets that are in the newpets_n.json files.
- Delete any pets (by animalID) that are not listed in the petlist.csv file.
Perform regular scrubs of the data
On a regular basis (e.g., weekly or monthly), perform a full refresh of data from the orgs_n.json and pets_n.json data files.
Additional information about the data files
Each data file contains a maximum of 10,000 rows.
The orgs_1.json file (the first file in the orgs data set) contains a time stamp as the first row. The time stamp is the date/time that the export was started.
Data file format
The data files are formatted in JSON format, with the exception of the file petlist.csv (which is in CSV format). Currently the data files can either be compressed or not (zip format), and you can make that selection on your API Key setup page.
Each of the JSON files have a maximum of 1,000 records. There is one record per row in the data files.
The petlist.csv file has 100 comma separated animalIDs per row.
Please refer to the sample data files that are attached to this article for specific examples.
The data files are generated and placed in your dedicated FTP account by 3 AM eastern. As our data set grows, however, the time that the data files will be available is expected to move later, so you may want to schedule your download and processing at a later time (like 4 or 5 AM eastern).
The data files provide two formats for the animal descriptions: animalDescription and animalDescriptionPlain.
animalDescription is the description just the way the user (rescue/shelter) saved it. It will include HTML (ex., <a>, <div>, <embed>, etc).
The animalDescriptionPlain field contains the animal description with all HTML removed. It does, however, include line breaks (\n) to preserve paragraph formatting.
When using the animalDescriptionPlain value, be sure to replace the line breaks (\n) with HTML break tags (<br>) to preserve the paragraph formatting the user intended.
RescueGroups.org provides a feature to our partner rescues and shelters that helps them see and track where their adoptable pets are being viewed. It's important that if you are using the animalDescriptionPlain value for your animal descriptions that you append the trackerImageUrl value to the pet's description.
Image/picture related topics
You should store the lastUpdated time stamp from the pictures data when you add a pet to your own database. Then, when processing pets, when you come across a pet that already exists in your database, check the mediaLastUpdated time stamp on the animal to determine if any of the pictures have changed. If the mediaLastUpdated time stamp is newer than the time stamp that you stored in your local database you should reprocess the pet's pictures.
You are welcome to use the image URLs from the data on your own website. Otherwise, feel free to download the "fullsize" image and process/resize and store it however you'd like.
RescueGroups.org does not re-use picture file names. So if a picture file name has changed, it is a new picture. It's possible that the image URL could change but the actual image has not, so you should try to use the time stamp from the pet data to determine if the image has changed.