Pagination with the SimplyRETS API

Cody Reichert rets, webapi, idx, api, tutorial

When building real estate websites and applications with the SimplyRETS API, our built in pagination will allow you to easily create “pages” of listings. There are a couple different methods for creating pagination links - below is a short tutorial on how that can be accomplished.

I’ll use the command line application cURL for the following examples, which you can run from 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.

The limit parameter

By default, our API payload will return 20 listings and at a maximum 50. You can set how many listings to return with the limit parameter. For example, the following query will return 40 unfiltered listings:

_Note that unfiltered simply means no additional parameters like maxprice_

$ curl -u simplyrets:simplyrets ''

Our pagination is built using this parameter in addition to the offset parameter to traverse listings without showing duplicates on the client side.

In the HTTP response header, we store a pre-created link to the next page of listings. The link includes any additional parameters from your original query, so you don’t have to worry about adding them back in.

Here’s an example of retrieving this link from the command line:

$ curl -u simplyrets:simplyrets -I ''

The simplyrets:simplyrets part will be your API keys, and the -I flag tells cURL to display the headers. So the above command would return:

HTTP/1.1 200 OK
Date: Fri, 17 Apr 2015 04:00:24 GMT
Server: Warp/
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
X-Powered-By: Yesod
X-SimplyRETS-Media-Type: vnd.simplyrets-v0.1
Content-Type: application/json; charset=utf-8
Vary: Accept, Accept-Language
Link: ; rel="next",

The last line “Link” is what we’re looking for. The link returned is the API request you can make to get the next set of listings. If you’re already on the second or third page, it will also return a “previous” link to get back to the previous set of listings:

Link: ; rel="next",
; rel="prev"

Naturally, the rel="next" link will get the next set of listings, and the rel="prev" link will get the previous set.

Building your own pagination

It’s also possible to build the pagination links yourself, and sometimes that might be easier. Using the offset and limit parameter, it’s pretty easy to calculate those on the client side.

For a basic example, if your first query is all listings above $500,000 with a limit of 25 per page:

$ curl -u simplyrets:simplyrets

Then you get the next page by adding the offset of 25 to the next API request:

$ curl -u simplyrets:simplyrets

Thus returing the second set of 25 listings.

And then the third page by increasing the offset by 25 again:

$ curl -u simplyrets:simplyrets

And there you have it! Three pages without showing duplicate listings to the client!

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


SimplyRETS logoSimplyRETS

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

Learn more at, get started with the API docs.