Get started

Zones

Zones as vector tiles, carrying each zone's name, severity and validity window, which a client labels and styles them by.

Retrieve the tile specification for the organization's zones

GET
/v1/zones/specification

Returns 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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

TileSpecification

required

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.

See the TileSpecification object.

Errors 400, 401, 402, 403, 405, 429, 500, 504. See Errors.

# The specification is JSON in the usual envelope: register everything under
# .data.sources, then the layers inside each source.
curl -s "https://tiles.mountaya.com/v1/zones/specification" \
  -H "X-API-Key: pk_your_publishable_key" | jq '.data.sources[] | {id, type, tiles, zoom_min, zoom_max}'
200
Response
{
  "data": {
    "sources": [
      {
        "id": "fc79978a-0e9c-4491-a5e4-b0de35a8b508",
        "type": "vector",
        "attribution": "<a href=\"https://mountaya.com/\" target=\"_blank\">&copy; Mountaya</a>",
        "tiles": [
          "https://tiles.mountaya.com/v1/zones/{z}/{x}/{y}"
        ],
        "zoom_min": 5,
        "zoom_max": 18,
        "layers": [
          {
            "id": "zones/fc79978a-0e9c-4491-a5e4-b0de35a8b508/fills",
            "key": "",
            "type": "fill",
            "source": "fc79978a-0e9c-4491-a5e4-b0de35a8b508",
            "source_layer": "fills",
            "zoom_min": 5,
            "zoom_max": 18,
            "layout": null,
            "paint": {
              "fill-color": [
                "match",
                [
                  "get",
                  "level"
                ],
                "info",
                "#1c7ed6",
                "warning",
                "#f59f00",
                "danger",
                "#f03e3e",
                "resolved",
                "#37b24d",
                "#1c7ed6"
              ],
              "fill-opacity": 0.3
            }
          }
        ]
      }
    ]
  }
}

Retrieve a vector tile of the organization's zones

GET
/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

z

integer (int32)

in path

required

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.

x

integer (int32)

in path

required

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.

y

integer (int32)

in path

required

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

surface

string

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.

timestamp

string (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_id

string (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.

# The body is the tile's bytes, not JSON. A map library fetches these URLs
# itself and cannot set a header, so a browser sends ?publishable_key= and
# ?session_token= instead. With a session naming a member the zones are
# drawn as drafts; the key alone draws the published public ones.
curl -s "https://tiles.mountaya.com/v1/zones/12/2126/1458" \
  -H "X-API-Key: pk_your_publishable_key" -H "X-Session-Token: sess_your_session_token" -o tile.mvt