Get started

Overlays

Raster and vector overlays (slope, aspect, weather, points of interest) as tiles and as the specification a client needs to style and read them.

The Overlay object

A built-in overlay layer drawn on top of a terrain base map, such as slope steepness or snow depth. Carries everything needed to add it to a map: the tile sources to register and which side of the wire handles each optional capability.

capabilities

object

required

Which of this overlay's options each side of the wire resolves, so read this before building the control. Where server.timestamp is true, a tile's timestamp selects the instant it depicts. Where it is false, the instant sent is ignored, and any change over time is the client's to draw from what it already holds. Two settings are refused. A timestamp that is not an RFC 3339 instant, or that lies more than three days before or six days after the request, is a 400 on every overlay tile, whether or not the overlay has a time dimension. Where server.timestamp is true, an instant more than 15 minutes from the current one is a 403 unless the organization's with_overlays_control safety rule allows it, a share-token request included.

content_type

string

required

One of: image/png, application/x-protobuf, image/webp

What the overlay's tiles carry, which decides how they are drawn: a raster overlay is an image layer, a vector one is styled by the layers its specification declares. For a raster overlay it names the format of the tiles within its source's zoom range; a tile asked for deeper than that is cut from its ancestor and is always PNG, so read each tile's Content-Type header rather than this.

id

string (uuid)

required

Identifier of the overlay. slug is the value the Tile API takes; this is the one the catalog keys on.

locales

object

required

The overlay's display name and blurb per language. A language absent here is null rather than missing, which is the case to fall back from.

slug

string

required

Stable, URL-safe identifier of the overlay, and the value the Tile API takes in /v1/overlays/{overlay}/.... Lowercase letters, digits and single hyphens, so it is safe in a path segment without escaping. The shape is declared here and on that path parameter identically, because a value this read hands a client is a value that client sends straight back.

sources

array of TileSource

required

Tile sources to register with the map renderer before this overlay can be drawn.

Retrieve the tile specification for a map overlay

GET
/v1/overlays/{overlay}/specification

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

Path parameters

overlay

string

in path

required

Overlay slug, such as wind or snowdepth. It is the slug this API's getTileLayers, and the Map Studio API's getLayers, report for each overlay, and it carries that field's shape exactly: lowercase letters, digits and single hyphens. Which overlays a publishable key or a share token may draw is set by the organization's overlay allowlist safety rule, and an overlay outside it answers 403 rather than 404. The allowlist starts empty on a new organization, which admits no overlay, so every slug answers 403 under a key until the allowlist names slugs or *, which Mountaya sets as the organization's agreement states. From Mountaya's web application the studio scope organization_id names decides instead, and an overlay outside it answers 403 as well. Read the matching specification endpoint for the ones it serves.

Query parameters

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

Tile specification: the sources and render-layers to register before the map starts fetching this overlay's {z}/{x}/{y} tiles. When the request named an organization_id, every URL template under sources[].tiles carries the same organization_id, so the tiles a map fetches are drawn in the scope the specification was served for.

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/overlays/snowdepth/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 tile of a map overlay

GET
/v1/overlays/{overlay}/{z}/{x}/{y}

Returns a tile (raster or vector) for a map overlay at the given zoom level, x, and y coordinates. Overlays include weather layers such as wind speed and snow depth, terrain analyses such as slope steepness, and points of interest.

Path parameters

overlay

string

in path

required

Overlay slug, such as wind or snowdepth. It is the slug this API's getTileLayers, and the Map Studio API's getLayers, report for each overlay, and it carries that field's shape exactly: lowercase letters, digits and single hyphens. Which overlays a publishable key or a share token may draw is set by the organization's overlay allowlist safety rule, and an overlay outside it answers 403 rather than 404. The allowlist starts empty on a new organization, which admits no overlay, so every slug answers 403 under a key until the allowlist names slugs or *, which Mountaya sets as the organization's agreement states. From Mountaya's web application the studio scope organization_id names decides instead, and an overlay outside it answers 403 as well. Read the matching specification endpoint for the ones it serves.

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

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.

timestamp

string (date-time)

in query

Selects the instant the tile is drawn for. When absent it is NOW: an overlay is a field of values over time, so there is no such thing as drawing one outside time, and this is where the parameter reads differently from the zone routes, where absence disables a filter instead.

Response 200 application/x-protobuf, image/png, image/webp

Tile data for the requested {z}/{x}/{y} tile. Vector overlays (weather, snow and POIs) return a Mapbox Vector Tile (application/x-protobuf); raster overlays (hillshade, slope steepness and aspect/slope) return an image, WebP (image/webp) or PNG (image/png) as the Content-Type header says. Which kind an overlay serves is given by its source type in the specification. A square its upstream holds no tile on is a zero-length vector tile for a vector overlay, which is a valid empty one, and a 404 for a raster one.

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/overlays/snowdepth/12/2126/1458" \
  -H "X-API-Key: pk_your_publishable_key" -o tile.mvt