Zones
Zones as vector tiles, carrying each zone's name, severity and validity window, which a client labels and styles them by.
/v1/zones/specificationReturns the tile specification (sources and layers) for rendering zone annotations on a MapLibre GL map. The response includes tile URLs, layer configuration, paint properties, and zoom range constraints needed to add zones as a vector source.
Response 200
Tile specification: the sources and render-layers to register before the map starts fetching the zones {z}/{x}/{y} tiles.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataTileSpecification
Rendering specification for a tile resource. Returned by every /specification endpoint and consumed once while a map is initializing: iterate sources and call map.addSource() for each, then iterate the layers inside each source and call map.addLayer() for each. The map library then fetches the {z}/{x}/{y} tiles automatically. A collection's specification also carries bbox, the extent of the itineraries its tiles draw, which is where to fit the camera once the sources are registered.
Errors 400, 401, 402, 403, 405, 429, 500, 504. See Errors.
/v1/zones/{z}/{x}/{y}Returns a vector tile for zones at the given zoom level, x, and y coordinates. The response is Mapbox Vector Tile (MVT) binary data. The zones it draws are the ones getZones lists for the same credential: the organization's public zones as last published under a key alone or with a session token naming nobody; its public and private zones as drafts when a session token naming a member accompanies the key, unless surface=published asks for the published snapshots; and none under a share token, which is answered an empty tile. A collection holding a zone adds nothing to this aggregate. A collection's zones are drawn by the collection tile endpoint with with_zones=true, which renders a single collection in isolation, and only for a credential that could list them. There is no tile of one zone alone. A publishable-key request for a tile outside the organization's zoom bounds or geographic boundaries is a 400.
Path parameters
zinteger (int32)
in path
Zoom level. Higher values show more detail over a smaller area. On a publishable-key request for anything but the base map (a terrain's tiles, the tiles of the sources its style draws and the elevation raster's), the organization's zoom-bounds safety rule narrows the accepted range, and a z outside it is a 400 naming z, so a structurally valid value can still be refused. Each layer's zoom_min and zoom_max in the specification say where a map should ask for tiles; they are not a refusal. A specification served to a publishable key reports them already narrowed to that rule, so a map that follows it asks only for a z the rule accepts.
xinteger (int32)
in path
Tile column index at the given zoom level, from 0 to 2^z - 1 inclusive. An index at or past 2^z addresses no tile and is a 400 naming x, as a negative or non-integer one is, so an index computed wrongly is refused before anything is drawn or fetched for it.
yinteger (int32)
in path
Tile row index at the given zoom level, from 0 to 2^z - 1 inclusive. An index at or past 2^z addresses no tile and is a 400 naming y, as a negative or non-integer one is, so an index computed wrongly is refused before anything is drawn or fetched for it.
Query parameters
surfacestring
in query
One of: published
Reads the published snapshot rather than the draft. published is the only accepted value: there is deliberately no draft spelling, because the param only ever narrows what the caller is served. An unrecognized value is rejected with a validation error rather than silently ignored. A read of one itinerary, or of one zone, refuses it with 403 when it is personal, owned by no organization, to the person whose it is: the published surface is what a video and an embed are made of, and a personal itinerary or zone makes neither. Every other caller reads a personal itinerary or zone as published, and since one is never published it is answered as one that does not exist.
timestampstring (date-time)
in query
Selects the instant the tile is drawn for. When absent, the time filter is disabled and EVERY zone is returned whatever its validity window, which is the usual choice for a client that styles out-of-window zones itself. When present, only zones active at that instant are returned, the instant being rounded down to the hour, in UTC, first.
organization_idstring (uuid)
in query
The studio scope the map draws in, named by the organization's identifier. A value that is not a UUID in its canonical form, or the nil UUID, is a 400 naming organization_id.
Response 200 application/x-protobuf
Mapbox Vector Tile (MVT) binary for the requested {z}/{x}/{y} tile. Empty (zero-length) when no features fall inside the tile.
Errors 400, 401, 402, 403, 404, 405, 429, 500, 504. See Errors.