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:

• Using lastId pagination
• Using limit/offset pagination

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.

Using 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.

Using 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 limit parameter can be any value up to 500

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'

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

The Link response header

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 rss feed

Comments