RESO Web API Replication
If you'd like to replicate data and are not sure if you've been provided a key for replication, or find a problem with this outline, please contact firstname.lastname@example.org.
The RESO API endpoint for replicating data is: https://replication.sparkapi.com/Reso/OData. Developers replicating data must use this endpoint.
Developers who wish to replicate data are granted Personal Access Tokens with special replication access. These keys are granted a few additional privileges to make replicating data easier. For example:
- The maximum $top value is raised to 1000 records.
- The Members and Offices resources do not apply company or office restrictions when searching user records for IDX roles.
These keys are otherwise identical to regular API keys, with access to the same resources and governed by one of our data roles.
The following guidelines outline the process for replicating using our implementation of the RESO Web API. While the Properties resource is used in these examples, the same general guidelines also apply to replicating other resources like Member and Office.
1. Initial Download
To kick off the initial download you'll need to make a request to the all properties endpoint. Optionally, you may include the $count or $select parameters, but no other parameters should be specified.
Paginating through the full result set can be accomplished by executing the request returned by the @odata.nextLink value in your last request. This attribute shows how to access the next page of results using the $skiptoken parameter when you've finished processing the current page.
Important: a ListingKey orderby is applied by default, ensuring that the order of the results is consistent while paginating with _skiptoken.
2. Update Data
Keeping your result set updated involves making requests against the ModificationTimestamp field using the timestamp of your last successful update minus 20 minutes to account for server side caching. Here is a pseudocode example to demonstrate:
query_timestamp = last_successful_retrieval_timestamp - 20 #minutes ?$filter=ModificationTimestamp gt query_timestamp
Paginating through the update result set is once again accomplished by following the @odata.nextLink attribute.
During this step it is recommended that you also update the Media, Room, Unit and Open House relations. For an optimization, when updating media for a listing, you can reference the PhotosChangeTimestamp, VideosChangeTimestamp and DocumentsChangeTimestamp attributes to see if any media needs to be updated prior to polling for that data.
3. Purging Stale Data
Repeat step 1 with the $select=ListingKey parameter applied, paginate through the result set identically to step 1, and compare all ListingKey values returned with the values in your database. Purge any records that do not match.