Pagination

The Mobility API uses two pagination strategies depending on the endpoint type:

Cursor-Based Pagination

Cursor-based pagination is used for search endpoints that aggregate results from multiple mobility providers in real-time:

• POST /mobility-api/v2/cars
• GET /mobility-api/v2/cars/stations
• POST /mobility-api/v2/micromobility
• GET /mobility-api/v2/public-transport/stops (see note below)

Each cursor encodes an encrypted, server-side pagination session that tracks which providers have been queried, how far through each provider's results you are, and the original search parameters. This lets the API query only the providers that still have results on subsequent pages.

How It Works

You send your first request without a cursor. The response includes a pagination object with a hasMore boolean and, if more results exist, a nextCursor string. To fetch the next page, include the nextCursor value in your subsequent request. Continue this pattern until hasMore is false, at which point nextCursor will be absent.

Request Parameters

Request and Response Format

First page request — no cursor needed:

POST /mobility-api/v2/cars
{
  "pickup": {...},
  "dates": {...},
  "limit": 20
}

Subsequent pages — include cursor from previous response:

POST /mobility-api/v2/cars
{
  "pickup": {...},
  "dates": {...},
  "limit": 20,
  "cursor": "token_abc..."
}

For GET endpoints (/cars/stations, /public-transport/stops), pass cursor and limit as query parameters:

# First page
GET /mobility-api/v2/cars/stations?latitude=48.78&longitude=9.18&radius=1000&limit=20

# Subsequent pages
GET /mobility-api/v2/cars/stations?latitude=48.78&longitude=9.18&radius=1000&limit=20&cursor=token_abc...

Response format (the data key varies per endpoint — offers, stations, results, or stops):

{
  "success": true,
  "data": {
    "offers": [...],
    "pagination": {
      "hasMore": true,
      "nextCursor": "token_abc..."
    }
  }
}

Cursor Behavior

Cursors are opaque encrypted strings — never parse, decode, or construct them manually. Store and forward them exactly as received.

Session lifetime: Pagination sessions expire after 30 minutes of inactivity. Each successful page request resets the 30-minute window.

Parameter changes: If the search parameters (location, dates, filters) differ from those used to create the cursor, the API silently starts a fresh search and returns first-page results. No error is thrown — you simply receive fresh results.

Provider failures: If one provider fails during a page request, the session retains that provider's cursor. It will be retried on the next page request.

Offset-Based Pagination

Offset-based pagination is used for list endpoints that return database-backed collections: GET /mobility-api/v2/mobility-providers and GET /mobility-api/v2/bookings.

How Offset Pagination Works

Specify the page number (0-indexed) and limit per page. The response includes a pagination object with the total item count, currentPage, and limit, which allows you to calculate the total number of pages and determine whether next/previous pages exist.

Offset Parameters

Offset Request and Response

GET /mobility-api/v2/mobility-providers?page=0&limit=20

{
  "success": true,
  "data": {
    "providers": [...],
    "pagination": {
      "total": 55,
      "currentPage": 0,
      "limit": 20
    }
  }
}

To calculate total pages: Math.ceil(total / limit). A page beyond the total range returns an empty result set.

Limitations

Cursor-based pagination does not provide a total count because real-time aggregation from multiple providers makes this impossible to determine upfront. Cursors are forward-only — you cannot jump to an arbitrary page or go backwards with the same cursor. If you need "back" functionality, store previously received cursors or start a new search. Offset-based pagination supports random page access but may see slightly degraded performance at very high page numbers on large datasets.