Pagination with the SimplyRETS API

Cody Reichert rets, webapi, idx, api, tutorial

When building real estate websites and applications with the SimplyRETS API, there are several built-in features that make it easy to paginate through listings and search results. This post will outline those features and provide examples for creating and navigating “pages” of listings.

There are two primary ways of paginating in the SimplyRETS API:

The examples below will use cURL and can be run on Windows, Mac, and Linux. Depending on what language you’re using for your application, the examples should translate pretty nicely to any built in HTTP library.

lastId pagination

lastId pagination is a key-based pagination method, and the recommended approach for navigating the listing data. It is particularly useful if you are replicating the dataset. There are two main steps:

  1. Initialize pagination with the lastId=0 query parameter.
  2. To query the next page, make another query by using the .mlsId from the last listing in the response: lastId={lastMlsId}.

For a complete example, check out the Paginating API responses with lastId help topic.

limit/offset pagination

The second method for pagination API responses is by using the limit and offset parameters. With this method, subsequent “pages” can be accessed by incrementing the offset parameter with each request (or using the Link response header).

To understand this type of pagination, let’s go through a basic example:

A limit/offset example

The first step is to make a query to the API with a limit of 20:

$ curl -u simplyrets:simplyrets 'https://api.simplyrets.com/properties?limit=20'

Note that limit can be any value up to 500.

This query will return the first 20 listings in the dataset. The offset in this query essentially defaults to 0. To access the next “page” of 20 listings, increment the offset parameter by the limit:

$ curl -u simplyrets:simplyrets 'https://api.simplyrets.com/properties?limit=20&offset=20'

For each subsequent request, the offset parameter can be incremented by the limit until the end of the dataset is reached:

Page 3: ?limit=20&offset=40
Page 4: ?limit=20&offset=60
Page 5: ?limit=20&offset=80
Page 6: ?limit=20&offset=100

Although calculating the next and previous page is pretty straightforward, the SimplyRETS API makes it even easier by doing this math for you. Pre-built URLs to access the next and previous pages are provided in the Link response header.

We can see the headers returned by the API with curl by using the -I flag:

$ curl -I -u simplyrets:simplyrets 'https://api.simplyrets.com/properties?limit=50'
HTTP/1.1 200 OK
Content-Length: 266191
Content-Type: application/json; charset=utf-8
Server: nginx/1.18.0
Vary: Accept, Accept-Language
X-SimplyRETS-Media-Type: vnd.simplyrets-v0.1
...
Link: <https://api.simplyrets.com/properties?offset=50&limit=50>; rel="next",

The last header in the code above contains our pagination URL(s). In the case above, we get one link to access the next page. Since our first offset was 0 there is no previous page.

The next query, however, will contain both a next and a prev link:

$ curl -I -u simplyrets:simplyrets 'https://api.simplyrets.com/properties?limit=50&offset=50'
HTTP/1.1 200 OK
...
Link: <https://api.simplyrets.com/properties?offset=50&limit=50>; rel="next",
<https://api.simplyrets.com/properties?offset=0&limit=50>; rel="prev"

The format of the Link header follows the syntax outlined here. The Link header is provided as a convenience, so there is no difference between using it or doing the math yourself.

You can full the API documenation and all of our supported parameters on our interactive API docs page, as well as try out some queries yourself!


— Cody @ SimplyRETS

Don’t forget to sign up to our atom feed

Comments

SimplyRETS logoSimplyRETS

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

Learn more at simplyrets.com, get started with the API docs.