Quickstart

Each overlay describes itself through a specification: the MapLibre sources and layers to register, with zoom ranges and attribution already filled in. Fetch it with your publishable key in the X-API-Key header. Here we request the hillshade overlay.

const response = await fetch(
  "https://tiles.mountaya.com/v1/overlays/hillshade/specification",
  { headers: { "X-API-Key": "pk_your_publishable_key" } },
);

// The Tile API wraps payloads in a `data` envelope.
const { data } = await response.json();
const { sources } = data;

A specification returns one or more sources. Each source carries an id, a type (vector or raster), its tiles URL templates, a zoom_min and zoom_max, attribution, and the layers to draw from it. Every layer already includes its paint and layout, so you do not style anything by hand.

Register each source on your map by its id. A raster source also carries a size; a vector source does not. Wait for the map's load event before adding anything.

for (const source of sources) {
  map.addSource(
    source.id,
    source.type === "raster"
      ? {
          type: "raster",
          tiles: source.tiles,
          minzoom: source.zoom_min,
          maxzoom: source.zoom_max,
          tileSize: source.size,
          attribution: source.attribution,
        }
      : {
          type: "vector",
          tiles: source.tiles,
          minzoom: source.zoom_min,
          maxzoom: source.zoom_max,
          attribution: source.attribution,
        },
  );
}

Each source lists the layers to draw from it. Add them in order. The paint and layout come from the specification, so pass them straight through; just set each layer's source to the source id it belongs to. For a vector source, also forward the layer's source-layer.

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

The hillshade overlay now renders on your map. To layer a forecast overlay such as temperature-actual instead, swap the slug in the specification URL and add a ?timestamp= parameter to its tile requests; see overlays for the catalog and the time dimension.