Get started
Your content

Collections

Collections

A collection's itineraries and zones as tiles, addressed by the collection rather than one resource at a time.

Retrieve the tile specification for a collection

GET
/v1/collections/{collection_id}/specification

Returns the tile specification (sources and layers) for rendering a collection on a MapLibre GL map. The response includes tile URLs, layer configuration, paint properties, and zoom range constraints needed to add the collection as a vector source.

Path parameters

collection_id

string (uuid)

in path

required

Identifier of the collection the operation acts on. A collection this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which collection ids exist.

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.

with_zones

boolean

in query

Whether the collection's zones are part of the answer. On this route that is the zone layers the specification declares.

with_itineraries

boolean

in query

Whether the collection's itineraries are part of the answer. On this route that is the itinerary layers the specification declares, itinerary_lines and itinerary_points.

Response 200

Tile specification: the sources and render-layers to register before the map starts fetching this resource's {z}/{x}/{y} tiles, and bbox, the extent of the itineraries they draw, to fit the camera to.

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, 404, 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/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/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 a collection's itineraries and zones

GET
/v1/collections/{collection_id}/{z}/{x}/{y}

Returns a vector tile for a collection at the given zoom level, x, and y coordinates. The response is Mapbox Vector Tile (MVT) binary data containing the zones and itineraries tied to the collection that this credential could list: under a publishable key alone, the organization's public itineraries and zones, each as last published, so a member never published draws nothing, and the same under a key with a session token naming nobody; with a session token naming a member, every member the key's organization owns, as drafts unless surface=published asks for the published snapshots; under a collection share token, the itineraries and zones that collection contains, each as last published. Another organization's public collection is reachable, but its tile draws nothing.

Path parameters

collection_id

string (uuid)

in path

required

Identifier of the collection the operation acts on. A collection this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which collection ids exist.

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

timestamp

string (date-time)

in query

Selects the instant the tile is drawn for. When absent it defaults to the current date-time, so a tile asked for with no timestamp carries the zones active now. When present, only zones active at that instant are returned. Either way the instant is rounded down to the hour, in UTC, first.

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.

itinerary_id

string (uuid)

in query

Identifier of one itinerary inside this collection, to draw it alone. It only filters, and marks nothing as selected: with with_itineraries set to false, the tile carries that one itinerary and no other, and with with_itineraries set to true every itinerary of the collection is drawn and this parameter changes nothing. The layers that paint it are the itinerary layers of a specification read with with_itineraries on, so read it that way: one read with it false declares none. An identifier that names no itinerary of the collection is not an error; it matches nothing, so the tile carries no itinerary. The nil UUID, like any spelling but the canonical one, is a 400 naming this parameter. It draws nothing the organization's safety rule withholds: on a publishable-key request whose organization keeps collection itineraries off, the tile carries no itinerary whatever this names.

with_zones

boolean

in query

Whether the collection's zones are part of the answer. On this route that is the zone features the tile carries.

with_itineraries

boolean

in query

Whether the collection's itineraries are part of the answer. On this route that is the itinerary features the tile carries, split across three source layers: itinerary_lines for line geometries, itinerary_points for point geometries and itinerary_restrictions for the restricted stretches. Setting it to false still leaves in the one itinerary itinerary_id names, unless it is the organization's safety rule that keeps the itineraries off.

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= instead.
curl -s "https://tiles.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/12/2126/1458" \
  -H "X-API-Key: pk_your_publishable_key" -o tile.mvt