SimplyRETS 1.0.0
Added: 11/11/2015
Updated at: 13/02/2019
The SimplyRETS API is an exciting step towards making it easier for developers and real estate agents to build something awesome with real estate data! The documentation below makes live requests to our API using the trial data. To get set up with the API using live MLS data, you must have RETS credentials from your MLS, which you can then use to create an app with SimplyRETS. For more information on that process, please see our [FAQ](https://simplyrets.com/faq), [Getting Started](https://simplyrets.com/blog/getting-set-up.html) page, or [contact us](https://simplyrets.com/\#home-contact). Below you'll find the API endpoints, query parameters, response bodies, and other information about using the SimplyRETS API. You can run queries by clicking the 'Try it Out' button at the bottom of each section. ### Authentication The SimplyRETS API uses Basic Authentication. When you create an app, you'll get a set of API credentials to access your listings. If you're trying out the test data, you can use `simplyrets:simplyrets` for connecting to the API. ### Media Types The SimplyRETS API uses the `Accept` header to allow clients to control media types (content versions). We maintain backwards compatibility with API clients by allowing them to specify a content version. We highly recommend setting and explicity media type when your application reaches production. Both the structure and content of our API response bodies is subject to change so we can add new features while respecting the stability of applications which have already been developed. To always use the latest SimplyRETS content version, simply use `application/json` in your application `Accept` header. If you want to pin your clients media type to a specific version, you can use the vendor-specific SimplyRETS media type, e.g. `application/vnd.simplyrets-v0.1+json"` To view all valid content-types for making an `OPTIONS`, make a request to the SimplyRETS api root `curl -XOPTIONS -u simplyrets:simplyrets https://api.simplyrets.com/` The default media types used in our API responses may change in the future. If you're building an application and care about the stability of the API, be sure to request a specific media type in the Accept header as shown in the examples below. The wordpress plugin automatically sets the `Accept` header for the compatible SimplyRETS media types. ### Pagination To paginate through listings, start your query with these parameters: 'limit=500&lastId=0'. The 'lastId' is the important part, you can use any limit up to 500. When you receive the response from the API with the results, check the 'Link' header for the 'next' link. That link is pre-built to access the next 'page' of listings. Alternatively, you can use the last listing's 'mlsId' from the previous request and use that in the next query. For example: First query: curl -u username:password 'https://api.simplyrets.com/properties?limit=500&lastId=0' If the 'mlsId' in the last listing of the results is '1234567', then the next query will be: curl -u username:password 'https://api.simplyrets.com/properties?limit=500&lastId=1234567' ...and so one until you have reached the final page of listings. There a few pieces of useful information about each request stored in the HTTP Headers: - `X-Total-Count` shows you the total amount of listings that match your current query. - `Link` contains pre-built pagination links for accessing the next 'page' of listings that match your query. ### RETS Vendor Compliance Many RETS vendors have strict requirements for showing disclaimers with specific information embedded. For example, in many areas it's required to show the timestamp of the time the listings were refreshed inside a disclaimer or on a listing page. The timestamp of the last listing refresh timestamp can be found in one of two spots: - The `X-SimplyRETS-LastUpdate` header from `GET /properties` or `GET /properties/{mlsId}` - Calling the API root `/` or properties api endpoint `/properties` with an OPTIONS request - `OPTIONS /` This request will show the last update timestamp for all RETS vendors associated with your application. Look for the `updates` list in the JSON response. - `OPTIONS /properties` Using this request, look for the `lastUpdate` field in the JSON response.