Listings API Tips and Tricks

Christopher Reichert rets, webapi, api, idx, mls

Code and Coffee w/ SimplyRETS

At SimplyRETS, we try our best to make using our API and services a simple and pleasurable experience. This article describes some simple tips geared towards maximizing the stability and performance of your SimplyRETS application.

1. Always use explicit media-types

It’s very important to always explicitly specify a Content-Type header in API requests. By default, our API and services honor the Content-Type: application/json header as the default and latest version of our API resources.

The downside to always using the latest media type is that as we improve and upgrade our API, you may experience unexpected changes. For example, changes to the JSON keys or the type of a field may change when we make a change. Specifying an exact media type version can prevent this from happening.

To view accepted media types, make an OPTIONS request to the root url endpoint:

$ curl -XOPTIONS -u simplyrets:simplyrets

  "vendors": [],
  "expires": "2020-12-12T19:24:40.995Z",
  "endpoints": ["/listings"],
  "accepts": [

The accepts field in the returned JSON object is a list of supported ‘Content-Types’ (e.g. what the SimplyRETS server will accept. To always retrieve the latest formats supported by SimplyRETS, use application/json.

NOTE: If you don’t explicitly set a media type (or use application/json, your app may be at risk of breakage when fields in the API are upgraded). This is also explained in our interactive documentation

To explicitly specify a media-type, use a Content-Type with application/vnd.simplyrets-v0.1+json. The v.0.1 is the SimplyRETS API version. When new versions of the API are released, your application will be backwards compatible with v0.1.

For WordPress plugin users, the media type is handled for you automatically.

2. Use narrow API queries

SimplyRETS supports a wide range of query parameters for listing data. If your aiming for performance, it’s important to keep your queries as narrow as possible. For example, if you need to find 4 bedroom, Active, Residential homes, you could start here:

However, by default the SimplyRETS API searches Residential and Rental, and Active and Pending listings. This means our query is doing a little more work than necessary. The most efficient way to specify the query is to use explicit parameters for each criteria: \
    minbeds=4& \
    maxbeds=4& \
    status=active& \

It may not always possible to narrow the criteria down this far but it can have worthwhile benefits on the search results and performance.

3. Use the support form in the SimplyRETS admin panel

We use a support email support@simplyrets to handle general support inquiries. We are more than happy to provide top-tier support over email. There is a trick, however, to having your technical issues prioritized directly with our development team.

The quickest way to have your support request reviewed by our development team is to submit it using the Support Request form in the admin panel.

Request SimplyRETS Support

We are enhancing our support request process so we can resolve issues as fast as possible. Keep in mind, if you are having technical problems, it is a good idea to include the following details:

  1. Your query string, even if the query seems obvious
  2. Steps to reproduce
  3. The output you are receiving
  4. The output you expect to receive

In general, including more information helps us narrow down possibilities significantly quicker and will help you get the answer you need directly for our development team.

4. Request Listings Directly

Whenever possible, use the mlsId field to request listings directly. Remember, mlsId is the unique identifier specific to SimplyRETS. Think of mlsId as synonymous with ListingKey from the RESO Data Dictionary

listingId is the MLS# from your MLS. Our listingId is synonymous with ListingId from the RESO Data Dictionary

For example, when dealing with a listing which has the following attributes:

  "mlsId": 1238453,
  "listingId": "N3487923",

You can use the mlsId to query the listing directly:

Doing so yields in a much faster query. So, for example, if your application shows pages with a single listing and its details, the above query would be better than:

Note! You should not hard-code pages queries or pages to rely on the `mlsId`. Since an MLS may purge or delete a listing, structure your code to make use of the `listingId` and use the `mlsId` dynamically.

5. Understand listing status and purging

Each day, SimplyRETS deletes old listings from your feed. Old listings are those which your MLS has revoked access and requested it be removed from our servers. This could be because the listing was sold, deleted, or even withdrawn or cancelled.

For example, imagine there is a listing in your feed with an mlsId of 12345 and status Active.

  "mlsId": 12345,
  "status": "Active",

Tomorrow, when requesting the listing, the response returned for the same listing will be an HTTP 404 response status. Even if your account has access to Closed, Withdrawn, or even Terminated listings, you may still experience listings being purged at any given point.

6. The SimplyRETS API has a JSON specification documentation

If you are an advanced user of the SimplyRETS API, you might be interested in diving into our OpenAPI specification. You can find them in .yaml format here:

Using that document, you can generate client code for all sorts of different programming languages and frameworks including Android, Swift, C#, Java, PHP, and many more.

See the interactive swagger editor for more details on code generation (see Generate Client).

7. Use the SimplyRETS status dashboard

Use status dashboard to view any scheduled maintenance, problems, or downtime. You can also see all historical status changes chronologically on the GitHub repo issues page.

— Christopher @ SimplyRETS

Drop us a line if you have questions or you’re interested in learning more about SimplyRETS


SimplyRETS logoSimplyRETS

The easiest way to build real estate software with your MLS data.

Learn more at, get started with the API docs.