Paginating search results

Learn how to manage large result sets using pagination. Pagination helps you organise search results into smaller, more manageable pages, improving performance and user experience.

How pagination works

The Demand API uses pagination to break large result sets into separate pages. You can:

• Specify how many results to return per page using maximum_results (cars) or rows (accommodation).
• Retrieve additional pages using the next_page token provided in the response.

Requesting additional pages with next_page

When your search response contains more results than can fit on a single page, the API includes a next_page token.

• This token contains encoded information from your original request.

To request the next page:

1. Copy the value from the next_page field in the response.
2. Include it as the page parameter in your next request.

Example - Search response with next_page token:

Example of search response with pagination token (next_page):

{
  "data": [ ... ],
  "metadata": {
    "next_page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7Im...fQ.y7NmH48mm7lImd2WxsHdotj6n-dVQAzJCGCnIJCKy3A",
    "total_results": 122
  }
}

Example - Requesting the next page

{ "page":"eyJhbGciOiJIUzI1NiJ9.eyJwIjp7Im1heGltdW1fcmVzdWx0cyI6MTAsIm9mZnNldCI6MTB9LCJhdWQiOiJDQVJTX1NVUFBMSUVSUyIsImV4cCI6MTY4MzY0NzMwNX0.y7NmH48mm7lImd2WxsHdotj6n-dVQAzJCGCnIJCKy3A"
}

If the next_page field is missing from the response, there are no additional results.

Limiting results per page

You can control how many results are returned per page:

Accommodation example: Using rows

Return up to 30 properties per page:

{
  "booker": {
    "country": "gb",
    "platform": "desktop"
  },
  "checkin": "2025-09-12",
  "checkout": "2025-09-14",
  "city": -2612321,
  "extras": [
    "products"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "rows": 30
}

Cars example: Using maximum_results

Return up to 50 car rental results per page:

{
    "booker": {
      "country": "nl"
    },
    "currency": "EUR",
    "driver": {
      "age": 36
    },
    "route": {
      "dropoff": {
        "datetime": "2025-05-08T11:05:00",
        "location": {
          "coordinates": {
            "latitude": 52.309456,
            "longitude": 4.762266
          }
        }
      },
      "pickup": {
        "datetime": "2025-05-20T11:05:00",
        "location": {
          "coordinates": {
            "latitude": 52.309456,
            "longitude": 4.762266
          }
        }
      },
      "maximum_results": 50
    }
  }'

Full pagination example: Accommodation search

Let’s say you want to display 50 accommodations per page in your application. Here’s how pagination would work:

Step 1 - Initial request (50 results per page)

{
  "booker": {
    "country": "gb",
    "platform": "desktop"
  },
  "checkin": "2025-09-12",
  "checkout": "2025-09-14",
  "city": -2612321,
  "extras": [
    "products"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "rows": 50
}

Step 2 - Response includes a next_page token:

{
  "products": [ ... ],
  "next_page": "eyJhbGciOi..."
}

Step 3 - Request next page

• Copy the "next_page" token and include it as page in the next request to retrieve the next pages:

{
  "page": "eyJhbGciOi..."
}

Repeat step 3 until the next_page token is no longer included in the response.

Best practices

✔ Always check for a next_page token in the response to determine if more results are available. ✔ Use maximum_results or rows to control page size and optimise performance. ✔ Combine pagination with filters and sorting to build efficient, user-friendly search experiences. ✔ Be mindful of the 3-hour token expiry window.