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 https://api.simplyrets.com/
{
"vendors": [],
"expires": "2020-12-12T19:24:40.995Z",
"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, 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:
https://api.simplyrets.com/properties?minbeds=4However, 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:
https://api.simplyrets.com/properties? \
minbeds=4& \
maxbeds=4& \
status=active& \
type=residentialIt 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.
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:
- Your query string, even if the query seems obvious
- Steps to reproduce
- The output you are receiving
- 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:
https://api.simplyrets.com/properties/1238453Doing 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:
https://api.simplyrets.com/properties?q=N3487923Note! 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