Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Pagination

The Occuspace API uses cursor-based pagination to navigate through large result sets. Cursors are more efficient and reliable than traditional page-number pagination, especially for real-time data that may change between requests.

How It Works

When a response contains more results than the requested limit, the API returns a cursor in the pagination object that you can use to fetch the next or previous page of results. Pagination is supported on all endpoints that return lists or time-series data.

Field
Type
Description

has_more

boolean

true if additional results are available beyond the current page

next_cursor

string

Pass this value as the cursor parameter to fetch the next page. null if there are no more results.

prev_cursor

string

Pass this value as the cursor parameter to fetch the previous page. null if you are on the first page.

Request Parameters

The following query parameters control pagination behavior and are supported on all paginated endpoints:

Parameter
Type
Required
Default
Description

limit

integer

No

1000

The maximum number of results to return per page. Must be between 1 and 1000.

cursor

string

No

-

The cursor value from a previous response's next_cursor or prev_cursor field. Omit this parameter on your first request.

Paginating Forward

To paginate forward through results, pass the next_cursor value from the current response as the cursor parameter in your next request. Keep paginating until has_more is false.

Always check has_more first. Rather than checking whether next_cursor is null, use has_more as your primary signal for whether more results are available. This is the most reliable way to detect the end of a result set.

# Step 1 — First request, no cursor needed
curl -X GET "https://api.occuspace.io/v2/locations?limit=3" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response pagination object:
# {
#     "has_more": true,
#     "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2MX0",
#     "prev_cursor": null
# }

# Step 2 — Pass next_cursor to fetch the next page
curl -X GET "https://api.occuspace.io/v2/locations?limit=3&cursor=eyJsb2NhdGlvbl9pZCI6MTU2MX0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response pagination object:
# {
#     "has_more": true,
#     "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2NH0",
#     "prev_cursor": "eyJsb2NhdGlvbl9pZCI6MTU1OX0"
# }

# Step 3 — Continue until has_more is false
curl -X GET "https://api.occuspace.io/v2/locations?limit=3&cursor=eyJsb2NhdGlvbl9pZCI6MTU2NH0" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Response pagination object:
# {
#     "has_more": false,
#     "next_cursor": null,
#     "prev_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2MX0"
# }

Paginating Backward

To paginate backward through results, pass the prev_cursor value from the current response as the cursor parameter in your next request. prev_cursor is null when you are on the first page of results.

Pagination With Metric Endpoints

Pagination works the same way on the Metric endpoints (/occupancy, /traffic, /dwell_time, /availability). The limit parameter controls how many data points are returned per page, and cursor is used to navigate between pages of time-series data.

Include all original parameters when paginating. When fetching subsequent pages of metric data, always include the same start_date, end_date, and interval parameters alongside your cursor. Omitting them may produce unexpected results.

Pagination With Child Locations

When using include=children on the /locations/{id} or /locations/{id}/now endpoints, the limit and cursor parameters apply to the child locations returned in children_data, not the parent location. The parent location is always returned regardless of pagination.

PreviousError HandlingNextFilters

Last updated