Listings API Tips and Tricks

Back to the Blog Posted on December 3, 2015 by Christopher Reichert

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

(e.g. Content-Type header).

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
    { "expires": "2015-12-05T19:24:40.995Z","vendors":[]
    , "endpoints": ["/listings"]
    , "accepts": ["application/json", "application/vnd.simplyrets-v0.1+json"]

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:


WARNING 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 `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.

/If you are using the WordPress Plugin, the Content-Type header is set 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,

The default property types searched in this query is Residential and Rental. Active and Pending listing statuses are queried by default. This means our query is doing a little more work than necessary.

The most efficient and performant way to specify the query is to use explicit parameters for each criteria:

It may not always possible to narrow the criteria down this far but it can have worthwhile benefits.

3. Use the support form in the SimplyRETS admin panel

We use a support email 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

using the mlsId to directly request the listing

will be significantly more performant than

WARNING: A drawback of requesting listing directly is that SimplyRETS cannot predict when the MLS will purge them from the database. Most of the time, it’s best not to hardcode mlsId queries (e.g. for featured listings). Rather, structure your code to make use of the mlsId when possible.

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 Swagger 2.0 specification.

Our JSON specification document can be retrieved at:

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 status changes chronologically on the History Page.

– Christopher @ SimplyRETS

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