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 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:
- Initialize pagination with the
- To query the next page, make another query by using the
.mlsIdfrom the last listing in the response:
For a complete example, check out the Paginating API responses with lastId help topic.
The second method for pagination API responses is by using the
offset parameters. With this method, subsequent “pages” can be accessed by
offset parameter with each request (or using
the Link response header).
To understand this type of pagination, let’s go through a basic 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'
limit can be any value up to 500.
This query will return the first 20 listings in the dataset. The
this query essentially defaults to 0. To access the next “page” of 20
listings, increment the
offset parameter by the
$ 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
We can see the headers returned by the API with curl by using the
$ 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
$ 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