Tile API

The Tile API lets you add Mountaya's geospatial layers — weather overlays, snow depth, activity routes, collection data, and custom drawings — directly into your own map. You keep full control over the UI and user experience while Mountaya handles the data pipeline.

Use it when you already have a map in your application and want to enrich it with Mountaya data. If you don't have a map yet and want a ready-made experience, use Map Embedding instead.

Authentication

Include your publishable key in the X-API-Key header of every request. If the require_session_token safety rule is enabled, also include a session token in the X-Session-Token header.

Your publishable key must have the tiles scope enabled. For a full guide on keys and tokens, see Authentication.

How it works

Every resource in the Tile API follows a two-step pattern:

Specification: Returns metadata: source type (vector or raster), tile URLs, layer configuration, legend, and zoom bounds. Call this once when initializing your map.
Tiles: Returns the actual tile data at a given {z}/{x}/{y} coordinate. Your map library calls this automatically once you register the source.

The specification response tells you exactly how to configure everything — no guesswork required. It returns an array of sources, each containing its own tile URLs, layers, and zoom bounds.

Response shape

{
  "status": "OK",
  "data": {
    "sources": [
      {
        "id": "source-uuid",
        "type": "vector",
        "tiles": ["https://tiles.mountaya.com/v1/overlays/snowdepth/{z}/{x}/{y}"],
        "zoom_min": 7,
        "zoom_max": 14,
        "attribution": "<a href=\"...\">...</a>",
        "layers": [
          {
            "id": "layer-uuid",
            "type": "fill",
            "source_layer": "snowdepthLayer",
            "zoom_min": 7,
            "zoom_max": 14,
            "paint": { "fill-color": "...", "fill-opacity": 0.8 },
            "layout": {},
            "legend": { "kind": "row", "unit": "cm", "steps": ["..."] }
          }
        ]
      }
    ]
  }
}

Resources

Overlays — Weather, snow depth, wind, and other environmental layers.

Specification: GET /v1/overlays/{overlay}/specification
Tiles: GET /v1/overlays/{overlay}/{z}/{x}/{y}

Activities — Routes for a specific activity (hiking, cycling, etc.).

Specification: GET /v1/activities/{activity}/specification
Tiles: GET /v1/activities/{activity}/{z}/{x}/{y}

Collections — All routes, itineraries, and drawings in a collection.

Specification: GET /v1/collections/{collection_id}/specification
Tiles: GET /v1/collections/{collection_id}/{z}/{x}/{y}

Drawings — Custom drawings created by your organization.

Specification: GET /v1/drawings/specification
Tiles: GET /v1/drawings/{z}/{x}/{y}

Passing authentication to tile URLs

Map libraries fetch tiles directly via URL, so you cannot set custom headers. Append your publishable key as a query parameter: ?publishable_key=pk_.... If session tokens are required, also append &session_token=sess_....

Quick start

Fetch the specification for a resource, then register each source and its layers in your map. This example adds the snowdepth overlay. The same pattern works for activities, collections, and drawings — just swap the URL.

const PUBLISHABLE_KEY = "pk_your_publishable_key";
const BASE = "https://tiles.mountaya.com";

// 1. Fetch the specification.
const res = await fetch(`${BASE}/v1/overlays/snowdepth/specification`, {
  headers: { "X-API-Key": PUBLISHABLE_KEY },
});
const spec = await res.json();

// 2. Register each source and its layers.
for (const source of spec.data.sources) {
  map.addSource(source.id, {
    type: source.type,
    tiles: source.tiles.map((url) => `${url}?publishable_key=${PUBLISHABLE_KEY}`),
    minzoom: source.zoom_min,
    maxzoom: source.zoom_max,
    ...(source.attribution && { attribution: source.attribution }),
  });

  for (const layer of source.layers) {
    map.addLayer({
      id: layer.id,
      type: layer.type,
      source: source.id,
      "source-layer": layer.source_layer,
      paint: layer.paint,
      layout: layer.layout,
      minzoom: layer.zoom_min,
      maxzoom: layer.zoom_max,
      ...(layer.filter && { filter: layer.filter }),
    });
  }
}

const PUBLISHABLE_KEY = "pk_your_publishable_key";
const BASE = "https://tiles.mountaya.com";

// 1. Fetch the specification.
const res = await fetch(`${BASE}/v1/overlays/snowdepth/specification`, {
  headers: { "X-API-Key": PUBLISHABLE_KEY },
});
const spec = await res.json();

// 2. Register each source and its layers.
for (const source of spec.data.sources) {
  map.addSource(source.id, {
    type: source.type,
    tiles: source.tiles.map((url) => `${url}?publishable_key=${PUBLISHABLE_KEY}`),
    minzoom: source.zoom_min,
    maxzoom: source.zoom_max,
    ...(source.attribution && { attribution: source.attribution }),
  });

  for (const layer of source.layers) {
    map.addLayer({
      id: layer.id,
      type: layer.type,
      source: source.id,
      "source-layer": layer.source_layer,
      paint: layer.paint,
      layout: layer.layout,
      minzoom: layer.zoom_min,
      maxzoom: layer.zoom_max,
      ...(layer.filter && { filter: layer.filter }),
    });
  }
}

const PUBLISHABLE_KEY = "pk_your_publishable_key";
const BASE = "https://tiles.mountaya.com";

// 1. Fetch the specification.
const res = await fetch(`${BASE}/v1/overlays/snowdepth/specification`, {
  headers: { "X-API-Key": PUBLISHABLE_KEY },
});
const spec = await res.json();

// 2. Register each source and its layers.
for (const source of spec.data.sources) {
  map.addSource(source.id, {
    type: source.type,
    tiles: source.tiles.map((url) => `${url}?publishable_key=${PUBLISHABLE_KEY}`),
    minzoom: source.zoom_min,
    maxzoom: source.zoom_max,
    ...(source.attribution && { attribution: source.attribution }),
  });

  for (const layer of source.layers) {
    map.addLayer({
      id: layer.id,
      type: layer.type,
      source: source.id,
      "source-layer": layer.source_layer,
      paint: layer.paint,
      layout: layer.layout,
      minzoom: layer.zoom_min,
      maxzoom: layer.zoom_max,
      ...(layer.filter && { filter: layer.filter }),
    });
  }
}

import { MVTLayer } from "@deck.gl/geo-layers";

const PUBLISHABLE_KEY = "pk_your_publishable_key";
const BASE = "https://tiles.mountaya.com";

// 1. Fetch the specification.
const res = await fetch(`${BASE}/v1/overlays/snowdepth/specification`, {
  headers: { "X-API-Key": PUBLISHABLE_KEY },
});
const spec = await res.json();

// 2. Create a deck.gl MVTLayer for each source.
// Vector tiles use MVTLayer. For raster overlays, use TileLayer + BitmapLayer.
const deckLayers = spec.data.sources.map(
  (source) =>
    new MVTLayer({
      id: source.id,
      data: source.tiles.map((url) => `${url}?publishable_key=${PUBLISHABLE_KEY}`),
      minZoom: source.zoom_min,
      maxZoom: source.zoom_max,
      getFillColor: [100, 100, 200, 180],
      getLineColor: [100, 100, 200, 255],
      getLineWidth: 1,
    }),
);

Legends

Each layer in the specification can include a legend object with color steps, units, and localized descriptions. Use it to build a legend UI in your application.

API reference

For the full list of endpoints, request parameters, and response schemas, see the API Reference.