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.
You can request an API Key here:
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.
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.
Login to the FTP account you created above and download the following files:
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).
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.
On a daily basis, download the adoptable pet data from your API key's FTP account. Process the updated 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.
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.
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.
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.