Pagination

If a metrics or geometry query returns enough data it will be paginated. This is typically when querying more than 10,000 segments/rows, but can happen with fewer segments if requesting large numbers of fields. The first page of results will be returned as part of the main response as well as the URL for the next page in the paging part of the response.

Occasionally, if our systems are experiencing an unusual delay (>10 seconds), the endpoint will return no data rows and a paging offset of 0, indicating that the data was not yet ready to be returned. Requesting the next URL after a short delay should return results as normal. In this case the response status will be pending.

Navigating the responses

If the response is sufficiently large, a metrics or geometry call includes a next URL that navigates to the next page of results. The structure of the page response will be similar to the main response.

It is possible to navigate to any in-range offset, including offset=0 to re-query the data. Log your paging URLs in case an error occurs during processing, in order to maximize the chances of being able to retrieve data without doing another query.

🚧

The last page of your results will not have a next paging URL or paging object.

Using the paging endpoints

If you have already performed a metrics or geometry query, you can return a subset of the results from a previous call using their respective paging endpoints:

• Paging for a metrics query
• Paging for a geometry query

The uuid in the URLs above are the request_id from the response of your initial query. request_id is a unique identifier for each request that allows you to refer to it in subsequent calls; it can be helpful to log the request_id when you make a geometry or metrics query.

Set the paging offset

When you call a paging endpoint, you can enter an offset to specify how many rows will be excluded from the paging response. For example, if you ran a metrics query for 8,000 segments, you can use the metrics/paging/{uuid} endpoint with an offset of 4000 to return metrics for the latter 4,000 segments in the initial metrics response.