Get started
All releases
Map Studio API
Data API
MCP server
Documentation

One read path for pagination, real error codes on the Data API

Eleven wire changes break an existing consumer: pagination metadata nests under pagination, Data API errors carry a real extensions.code, the unlimited sentinel is null rather than -1, six Data API fields are renamed, removed, or retyped, thirteen public Map Studio API operations are renamed with the /groups route becoming /segment-groups, and a filtered search narrows Way.activityCompatible to the activity it was asked about. The Map Studio API also gains a public 50-operation surface, a documented 504, and a rate limit on session exchange.

Changed:

Pagination metadata moved from the flat extensions.metadata.{limit, offset, total} to a nested extensions.metadata.pagination object carrying the same three fields. A client still reading the flat path now reads undefined. It affects the four plain list endpoints: GET /v1/itineraries/{itinerary_id}/collections, GET /v1/zones/{zone_id}/collections, GET /v1/users/{user_id}/collections, and GET /v1/collections/{collection_id}/users. GET /v1/itineraries reports the same nested object beside its own count and limit, so one read path now serves every list endpoint whether or not it also carries domain data.

Fixed:

Data API errors populate extensions.code, and the message is the localized sentence alone. Both were broken together: the wrong error presenter was rendering an error's whole string form, so the message arrived as "FORBIDDEN: <message> (input)" and extensions arrived empty. Anything parsing that prefix to recover a code must read extensions.code instead: a client that branched on the prefix will not find it, and one that branched on an absent code was treating every 402, 403, 404, 429, and 500 as a bad argument.

Changed:

The entitlement sentinel for an unlimited dimension is null, replacing -1. It reads the same everywhere the value appears: an organization's limits map, and the limit beside the itineraries listing. A client comparing against -1 now never matches and treats an unlimited dimension as capped at whatever it defaults to; compare against null instead. A dimension absent from the map still means no limit was granted at all, which is not the same as unlimited.

Changed:

Six fields changed shape on the Data API. Place.housenumber and Isochrone.reachfactor are now houseNumber and reachFactor, spelled the way every other field in the schema is. Place.score and Way.score are gone: both carried the upstream geocoder's own relevance figure, which is not comparable between two responses, so rank on the order results arrive in instead. Isochrone.center is nullable, because the value is forwarded verbatim from the routing provider rather than reconstructed from the origin you sent: a provider that reports no centre now reports null where it used to report an empty array. ZoneSearchResult.level and mode are the ZoneLevel and ZoneMode enums rather than free-form strings, so their values arrive upper-snake-cased: WARNING, POLYGON, and the rest. Selecting a renamed or removed field is not a null in the response: it is a validation error, Cannot query field, raised before a resolver runs, so a selection set that still names one of them comes back with no data at all.

Changed:

Every Map Studio API operation name is now derived from its path rather than chosen, so a method's name says where it goes. Thirteen public names change: the itinerary sub-resources regain the parent the path already carries, so postSegment is postItinerarySegment, putWaypoint is putItineraryWaypoint, and the segment-group trio follows the same shape. The route /v1/itineraries/{itinerary_id}/groups is now /v1/itineraries/{itinerary_id}/segment-groups, which is what the payloads have always called it (SegmentGroupCreateParams, ItinerarySegmentGroup), and the old path is gone rather than aliased. Twenty-seven console-only names changed the same way and reach no API key.

Changed:

A search filtered to one activity now reports Way.activityCompatible as that activity alone, where it used to list every activity the way accepts. The field reports what was established rather than a catalogue: a filtered search verifies only the activity it was asked about, so naming the others would claim a routing check that never ran. Read an absent activity as unreported, not as refused. An unfiltered search is unchanged.

Added:

The Map Studio API has a public surface of its own: 50 operations covering itineraries, segments, waypoints, segment groups, zones, collections, and sessions, published as their own OpenAPI document and rendered as a reference in the developer portal. The console-only operations are filtered out of it, so what the reference shows is what an API key can reach.

Added:

POST /v1/sessions declares 429 Too Many Requests. It is now rate limited, per calling address and, on failed exchanges, per secret key: a session exchange that presents an unknown key is the one cheap way to probe for a valid one, and it was previously unbounded. A working integration mints roughly one token per four minutes per key thanks to the existing get-or-mint cache, so legitimate traffic sits far below the ceiling.

Added:

Every public Map Studio API operation declares 504 Gateway Timeout with the GATEWAY_TIMEOUT code. Routes run under a request time budget, and a spent budget used to surface as whichever internal error the interruption happened to produce. The restatement only ever replaces a 5xx, so an expiring deadline never turns a 404 into a 504.

Added:

A page documenting the error contract both APIs share: the envelope, all sixteen codes with their statuses, where each surface puts the offending field path, and what separates a PAYMENT_REQUIRED from a CARD_REQUIRED.