Get started

Your content

Itineraries

Routes as vector tiles, drawn from the published snapshot or, when a session token naming a member accompanies the key, from the key's own organization's drafts, so a map draws a whole set of them without fetching each one's geometry.

The TileSpecification object

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.

bbox

array of number (double) | null

The extent of the itineraries this specification's tiles draw, as [west, south, east, north] in WGS 84 decimal degrees. This is the flat four-tuple every bounding box on every Mountaya surface uses. Exactly four numbers, longitude first in each pair, every longitude between -180 and 180.

sources

array of TileSource

required

Map sources to register, in order. Each becomes one map.addSource() call and carries the render-layers to draw from it.

Retrieve the tile specification for the organization's itineraries

GET
/v1/itineraries/specification

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

Response 200

Tile specification: the sources and render-layers to register before the map starts fetching these itineraries' {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/itineraries/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 itineraries

GET
/v1/itineraries/{z}/{x}/{y}

Returns a vector tile of the organization's itineraries at the given zoom level, x, and y coordinates. The response is Mapbox Vector Tile (MVT) binary data. The itineraries it draws are the ones getItineraries lists for the same credential: the organization's public itineraries as last published under a key alone or with a session token naming nobody; its public and private itineraries as drafts when a session token naming a member accompanies the key; and none under a share token, which is answered an empty tile. 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.

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= instead.
curl -s "https://tiles.mountaya.com/v1/itineraries/12/2126/1458" \
  -H "X-API-Key: pk_your_publishable_key" -o tile.mvt

Retrieve the tile specification for a single itinerary

GET
/v1/itineraries/{itinerary_id}/specification

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

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary 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 itinerary ids exist.

Response 200

Tile specification: the sources and render-layers to register before the map starts fetching this resource's {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, 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/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/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 single itinerary

GET
/v1/itineraries/{itinerary_id}/{z}/{x}/{y}

Returns a vector tile for a single itinerary at the given zoom level, x, and y coordinates. The response is Mapbox Vector Tile (MVT) binary data.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary 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 itinerary 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

revision

string

in query

Opaque change-feed token from the collaboration event stream. It never changes what is drawn: the tile is always the latest content. It changes only how the response may be cached: a draft's response to a URL carrying a token may be kept for good when the tile was cut from the version of the itinerary's tiles the server holds, and is private otherwise, while a published snapshot's is cached as it would be without one (see the Cache-Control response header), and an itinerary's tokens only move forward, so every peer that asks for the same ?revision=<token> URL after a change event asks for a URL no cache has seen before. Accepted syntax is a plain integer or an event stream id (two integers joined by a hyphen, e.g. 1720512345678-0), at most 64 characters.

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.

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. An itinerary this credential is served nothing of is the 404 below, never an empty 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/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/12/2126/1458" \
  -H "X-API-Key: pk_your_publishable_key" -o tile.mvt