Pagination

Handling large volumes of data can be challenging, especially when it comes to efficient data retrieval and seamless user experience. Housemates API offers a solution to this through Pagination. This allows you to retrieve data in manageable, bite-sized chunks, making the overall process more efficient and user-friendly.

When you make a request to an endpoint that returns multiple items (such as properties, rooms, or enquiries), the Housemates API will return the results in a paginated format. This means you will receive a portion of the results at a time, rather than all at once, preventing overwhelming data loads.

By default, the API returns 10 items per page. However, you can specify the number of items you want to retrieve per page by including a 'limit' parameter in your request. You can also navigate through the pages using 'page' parameter.

Pagination example

Here is a quick example of how to paginate through the properties endpoint.

Optional parameters

Name
per_page
Type
integer
Required
Optional
Description
The number of items you want to retrieve per page. The default is 10. It should be provided as a query parameter.
Name
page
Type
integer
Required
Optional
Description
The page number to be returned. e.g. page=2. By default, the first page is returned.

Response

Lets go through the response and explore the pagination attributes.

Pagination attributes

Name
meta
Type
object
Description
An object containing pagination metadata.
Name
links
Type
object
Description
An object that contains URLs to the first, last, next, and previous pages, relative to the current page. Can usually be used to build simple pagination links.

Manual pagination using cURL

curl -i -X GET \
     "https://api.housemates.io/api/properties?per_page=15" \
  -H 'X-API-PARTNER-ID: {API_PARTNER_ID}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \

Paginated response

{
  "success":true,
  "code":0,
  "locale":"en",
  "message":"OK",
  "data":{
    "items":[
      // ... properties
    ],
    "meta":{
      "total":4,
      "count":4,
      "per_page":15,
      "current_page":1,
      "total_pages":1,
      "path":"https://api.housemates.io/properties",
      "links":[
        {
          "url":null,
          "label":"&laquo; Previous",
          "active":false
        },
        {
          "url":"https://api.housemates.io/properties?page=1",
          "label":"1",
          "active":true
        },
        {
          "url":null,
          "label":"Next &raquo;",
          "active":false
        }
      ]
    },
    "links":{
      "first":"https://api.housemates.io/properties?page=1",
      "last":"https://api.housemates.io/properties?page=1",
      "next":null,
      "prev":null
    }
  }
}