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 different pagination mechanisms depending on the endpoint:

Token-based pagination for search endpoints

With this pagination mechanism 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:

{
  "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.

Timestamp-based pagination for accommodation changes

The /accommodations/details/changes endpoint uses timestamp-based pagination to help you retrieve updates incrementally.

How it works

1. You send a request with a last_change timestamp in ISO 8601 format (UTC only). Example:

{
  "last_change": "2025-06-22T12:00:00+00:00",
  "filters": {
    "countries": ["nl"]
  }
}

2. The response may include a next timestamp — this represents the next point in time from which to continue fetching updates.

Example — Response with next timestamp:

{
  "data": {
    "changes": {
      "changed": [403115, ...],
      "closed": [9876832, ...],
      "opened": [8034270, ...]
    },
    "from": "2025-06-22T12:00:00+00:00",
    "next": "2025-06-22T12:24:42+00:00",
    "total_changes": 5125
  }
}

3. To retrieve the next batch of changes, you make a new request using the value of next as your new last_change parameter.

Example — Requesting the next batch of changes:

{
  "last_change": "2025-06-22T12:24:42+00:00",
  "filters": {
    "countries": ["nl"]
  }
}

If no changes are returned

• The next field is omitted.
• You should repeat the call after one minute with the same last_change timestamp to check for new updates.

Important notes

• The endpoint returns up to around 5000 accommodation IDs per request. The actual number may vary due to grouping of result by second.
• You should continue requesting with the updated next timestamp until no further next field is returned, meaning you've retrieved all available changes.
• You keep requesting changes in chronological order by advancing the last_change timestamp based on the next value provided in the response.

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.

✔ For /accommodations/details/changes, always update your last_change parameter based on the next timestamp to ensure you do not miss updates.