Maps: vector tiles, styles & Studio

MapMap is a maps platform as well as a routing one: the gateway serves vector tiles, TileJSON and ready-to-render MapLibre styles straight from the same territory data the routing engine uses. Style them in Studio, or let an agent style them through the MCP style tools.

Status, honestly: the hosted gateway at https://api.mapmap.ai is live: sign up for a key, or run the self-host distro; every call below works identically against your own deployment. These endpoints are enabled per deployment: they answer 404 until the operator stages the tile and asset directories (the hosted gateway has them enabled, with territories on every continent; see territories for coverage).

Set up your shell once so every snippet on this page is copy-pasteable:

export BASE=https://api.mapmap.ai   # or your self-host gateway
export API_KEY=snk_…                # issued by POST /v1/keys; see the quickstart

Metered endpoints accept the key as Authorization: Bearer $API_KEY (preferred) or as an ?api_key=snk_… query parameter; the query form exists for URL-only contexts like a style URL handed to MapLibre. Ask for a style or a TileJSON with ?api_key= and every URL in the document comes back carrying the same key, so a client that just follows them keeps authenticating; ask with the header and the URLs stay keyless, because that client keeps sending its header. No key yet? The quickstart issues one in a single curl; base URL, auth and the error envelope are defined in full on the conventions page.

Vector tiles

All three take your normal API key and are metered per request at the Standard price class (see pricing). They are not charged against the offline download allowance, which applies only to bulk territory-package downloads.

Territory slugs (uk below) are listed in the territories guide; on a self-hosted deployment GET /territories reports what you have staged.

curl -fsS "$BASE/tiles/uk/tiles.json" -H "Authorization: Bearer $API_KEY"

{
  "tilejson": "3.0.0",
  "name": "uk",
  "scheme": "xyz",
  "tiles": ["https://api.mapmap.ai/tiles/uk/{z}/{x}/{y}.mvt?v=1720981132"],
  "minzoom": 0,
  "maxzoom": 14,
  "bounds": [-8.65, 49.86, 1.77, 60.86],
  "center": [-2.0, 54.0, 6.0],
  "attribution": "© OpenStreetMap contributors © OpenMapTiles",
  "data_updated": "2026-07-01"
}

(The ?v= discriminator busts caches atomically when the operator republishes a territory archive; keep it in the URLs you pass through.)

That sample was fetched with the Authorization header, so the tile template comes back keyless. The same request as "$BASE/tiles/uk/tiles.json?api_key=$API_KEY" returns …/{z}/{x}/{y}.mvt?v=1720981132&api_key=snk_… instead. Either way the document is usable as it stands, which is the point: whichever way you sent the key is the way the URLs in the answer expect you to keep sending it.

data_updated is the ISO-8601 date of the OSM extract behind the territory's latest published package, read from the update channel the operator publishes alongside the tiles. It is null when the deployment has no channel configured or the territory is not published there; null means unknown, never "current", so show nothing rather than today's date.

Stable vs hash-versioned tile URLs

The PMTiles CDN serves every territory archive under two names:

• Stable alias: https://tiles.mapmap.ai/uk.pmtiles, https://tiles.mapmap.ai/planet.pmtiles. Always points at the current build; survives every rebuild. Use this in demos, docs and anything long-lived. The web SDK's defaults use the stable aliases.
• Hash-versioned snapshot: uk-a4b331db419a.pmtiles. Immutable and cacheable forever, but a world/tile rebuild retires it: any app that hardcodes a hashed name breaks on the next data refresh. Only pin a hashed snapshot when you specifically need a frozen dataset (a reproducible benchmark, a point-in-time archive), and expect it to be garbage-collected eventually.

If you copied a hashed URL out of your browser's network tab, swap it for the stable alias before shipping.

Render a map in one move: point MapLibre GL at the style URL. This example is complete; note the container div must have an explicit height, or the map renders zero pixels tall and the page looks silently blank (the classic MapLibre gotcha, see troubleshooting, including the Tailwind v4 cascade-layer variant of it):

<!-- MapLibre GL JS 6 is ESM-only: there is no UMD build and no `maplibregl`
     browser global, so a plain page needs an import map and a module script.
     In production, pin an exact maplibre-gl version (as here) and add SRI to
     the stylesheet and the import map, or bundle it via npm. Regenerate an
     SRI hash with:
       curl -sL <url> | openssl dgst -sha384 -binary | openssl base64 -A -->
<link href="https://unpkg.com/maplibre-gl@6.9.0/dist/maplibre-gl.css" rel="stylesheet" />

<div id="map" style="height: 100vh"></div>

<script type="importmap">
  { "imports": { "maplibre-gl": "https://unpkg.com/maplibre-gl@6.9.0/dist/maplibre-gl.mjs" } }
</script>
<script type="module">
  import * as maplibregl from "maplibre-gl";

  const map = new maplibregl.Map({
    container: "map",
    style: "https://api.mapmap.ai/tiles/uk/style.json?api_key=snk_…",
    center: [-1.5, 52.6], // lon, lat
    zoom: 6,
  });
</script>

Loaded from a real https URL like this, MapLibre resolves its own worker from import.meta.url and needs no extra setup.

Under a bundler, serve the worker yourself. MapLibre 6 ships its worker as a separate ES module resolved from import.meta.url. Where the bundler cannot rewrite that URL to something the browser can fetch as a module worker, and Turbopack and Vite both fall into that class, no tiles arrive and nothing at all is logged: the map is blank, with no console error, no error event and no failed request. Serve both files yourself (the worker imports the shared chunk, so serving the worker alone fails the same silent way) and point MapLibre at your copy before the first map is constructed:

mkdir -p public/vendor/maplibre
cp node_modules/maplibre-gl/dist/maplibre-gl-worker.mjs public/vendor/maplibre/
cp node_modules/maplibre-gl/dist/maplibre-gl-shared.mjs public/vendor/maplibre/

import * as maplibregl from "maplibre-gl";

maplibregl.setWorkerUrl("/vendor/maplibre/maplibre-gl-worker.mjs");

setWorkerUrl does not exist on MapLibre 5, so feature-detect it if you support both majors. Vite needs this recipe too: MapLibre 6's defaultWorkerUrl() builds the worker filename from a variable, so Vite emits no worker asset and serves the SPA fallback HTML in its place. Bisected across six fresh installs on 17 September 2026: the documented Vite quickstart renders a blank map on maplibre-gl 6.9.0, 6.9.1 and 6.10.0 (Vite 7 and 8, dev and build alike), and 5.24.0 works. The CDN page above is the one case that needs none of this, because it loads MapLibre from a real https URL.

On MapLibre 5 that page works instead as a classic <script src="…/dist/maplibre-gl.js"> tag reading the maplibregl global. MapLibre 6 ships no such file, so the import-map form is the one to copy.

That is the whole integration. The style's source URL, the TileJSON it resolves and the tile template under that all come back carrying the key from the style URL, so MapLibre needs no transformRequest hook to put it back on.

Territory base maps include ocean and land at all zooms: the map factory stages the global sources (OSM ocean water polygons, Natural Earth, lake centrelines) into every territory build.

Server-side raster/PNG rendering is not offered; clients render the vector tiles themselves.

Hosted styles (the style API)

Styles are versioned and immutable: publishing writes a new version, and a versioned style URL can be cached forever.

Compiled-style and theme reads are public and unmetered, so a style can be referenced by bare URL from a browser map client, which can attach no credential. The listing is not: GET /styles needs your key and returns only the styles that key created (or a sibling key of the same account). A style you publish is yours: nobody else can list it, and nobody else can publish a new version over its id.

The hosted gateway's own house styles (MapMap Light and MapMap Dark) are served from /tiles/{territory}/style.json and are unaffected by any of this: they are not hosted styles you own, so they never appeared in your listing and are still fetched by bare URL.

Create a style: POST /styles

curl -fsS -X POST "$BASE/styles" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Midnight Fleet",
    "theme": {
      "name": "midnight-fleet",
      "base": "dark",
      "palette": { "water": "#0b2038" }
    }
  }'

201 Created:

{
  "id": "midnight-fleet-9f3a2c",
  "version": 1,
  "style_url": "https://api.mapmap.ai/styles/midnight-fleet-9f3a2c@1.json",
  "theme": { "name": "midnight-fleet", "base": "dark", "palette": { "water": "#0b2038" } }
}

The id is the name's slug plus six hex characters, so same-named styles never collide. style_url is the immutable compiled style: drop it straight into a MapLibre client.

Publish a new version: POST /styles/{id}

The body is not the theme itself: it is a wrapper with the full theme document under "theme". POSTing a bare theme is a 400.

Read-modify-write: fetch the current document from GET /styles/{id}/theme (served no-store, so you never publish from a stale base), edit it, and POST it back:

curl -fsS -X POST "$BASE/styles/midnight-fleet-9f3a2c" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": {
      "name": "midnight-fleet",
      "base": "dark",
      "palette": { "water": "#0d2742" }
    }
  }'

200 OK:

{
  "id": "midnight-fleet-9f3a2c",
  "version": 2,
  "style_url": "https://api.mapmap.ai/styles/midnight-fleet-9f3a2c@2.json"
}

Existing versions are never modified; GET /styles/{id}.json starts serving the new version within its 60-second TTL.

Errors

An invalid theme is a 422 (application/problem+json) whose problems list names the offending slot or layer and the accepted values, so agents can self-correct and resubmit:

{
  "type": "urn:sn-gateway:problem:invalid-theme",
  "title": "Theme validation failed",
  "status": 422,
  "detail": "theme validation failed: unknown palette slot \"watr\"; accepted slots: background, water, waterway, …",
  "problems": [
    "unknown palette slot \"watr\"; accepted slots: background, water, waterway, landcover, landuse, park, ice, building, aeroway, road, roadMajor, roadMotorway, path, rail, boundary, boundaryMinor, textPrimary, textSecondary, textHalo"
  ]
}

The full error envelope, quota behaviour and the 402-vs-429 distinction are on the conventions page.

The theme document

A theme is a small JSON document the theme engine compiles into a full MapLibre style-spec v8 style.json. The same engine runs in Studio, in the gateway and in signed territory packages, so a theme renders identically everywhere.

{
  "name": "midnight-fleet",
  "base": "dark",
  "palette": { "water": "#0b2038", "roadMajor": "#8a6d3b" },
  "layers": {
    "building": { "visible": false },
    "road-minor": { "paint": { "line-width": 2 }, "minzoom": 10 }
  }
}

• base is light or dark; the 25 palette slots below recolour the whole map. Colours are #rgb/#rrggbb/#rrggbbaa or rgb()/rgba()/hsl()/hsla().
• Per-layer overrides: visible, paint/layout (per-key merge), filter, minzoom/maxzoom.
• fonts.regular sets the label fontstack (default "MapMap Sans Regular"); keep it on a bundled fontstack or labels drop.
• fonts.labels optionally retypesets label types individually: { "country", "city", "place", "road", "water", "poi", "housenumber" }, each a fontstack string; absent kinds inherit fonts.regular. Example: "fonts": { "regular": "MapMap Sans Regular", "labels": { "place": "MapMap Sans Bold", "water": "MapMap Sans Italic" } }. Publishing a fontstack this server does not host is a 422 naming the hosted stacks.
• glyphs and sprite optionally override the compiled style's glyph and sprite URLs.
• extra_layers: extra fully-formed MapLibre layers inserted above the base map, below labels. Each must use the territory source and one of the source-layers the tiles emit: aerodrome_label, aeroway, boundary, building, housenumber, landcover, landuse, mountain_peak, park, place, poi, transportation, transportation_name, water, water_name, waterway.
• extra: an opaque block the compiler ignores (capped at 256 KB serialised); Studio stores its navigation design and POI theming here.
• buildings_3d: true renders buildings as 3D extrusions from OSM height data; see 3D buildings for where to (and not to) use it.
• terrain: 3D ground. { "hillshade": true } is the usual value: hillshading is what makes relief legible from overhead, where the displacement alone is close to invisible. Also takes exaggeration (default 1, clamped 0–8), url and encoding for your own DEM. The compiler emits the raster-dem source, MapLibre's terrain block and, for hillshade, a second identical source. Sharing one between terrain and a hillshade layer renders with artefacts. Shading is inserted below the first line or symbol layer, so it lands on the ground rather than on top of roads and building tops. The DEM carries its own attribution; the OpenStreetMap credit does not cover it. Studio exposes this under Land & landuse; the SDK equivalent is terrain: true.

  • terrain.sea_relief colours the SEA FLOOR on its own, so the one hillshade layer's colours stop being shared by the land and the sea. Its depth ramp is set out further down, beside terrain.seabed.

  • terrain.shading styles the relief. Every field is optional, and anything left unset is derived from your landcover colour, so shading matches the map without being configured, and recolouring the ground moves the relief with it. MapLibre's own defaults are pure black and pure white, which suit no palette in particular: on a dark theme the highlights blow out, and on a warm palette black shadows read as dirt rather than relief.

    Field	Default
    shadow	landcover blended 50% toward black	slopes facing away from the light
    highlight	landcover blended 50% toward white	slopes facing the light
    accent	landcover blended 20% toward black	ridges and valleys
    intensity	0.5	strength, 0–1
    direction	335	degrees clockwise from north
    anchor	"map"	what the light is fixed to

    direction defaults to 335 because that is the cartographic convention: light from the top-left. Lighting from below inverts the read and hills look like holes. Values wrap rather than clamp, so -25 is a legitimate way to write 335.

    anchor defaults to "map", which pins the light to the ground so hills shade the same however the map is rotated. "viewport" is MapLibre's own default and glues the light to the screen, so every hill re-shades as the user turns, fine for a fixed-bearing view, disorienting in one the user can spin.

• Attribution is structural: every compiled style carries "© OpenStreetMap contributors © OpenMapTiles" on its tile source, and validation rejects any theme that tries to drop it.

Palette slots

All 25 slots, with the light/dark base defaults, in palette order.

Seven slots INHERIT rather than sit at a fixed default: roadMotorway follows whatever roadMajor resolves to, and the six landcover-class slots follow a mix of their parent slot, until you set each one explicitly. So recolouring roadMajor alone moves motorways too (set both for the classic orange-motorways-over-yellow-primaries look), and recolouring park alone moves wood, grass and wetland with it. The Light/Dark columns below are what those mixes resolve to at the default palette:

Styleable layer ids

Per-layer overrides target these 30 skeleton layer ids (paint order, first = bottom): background, landcover, landuse, park, water, waterway, aeroway, building, building-outline, rail, pedestrian-areas, road-path, road-minor-casing, road-major-casing, road-minor, road-major, road-bridge-casing, road-bridge, boundary-minor, boundary, then road-oneway and the label layers. Both boundary layers filter out maritime=1 features, so territorial-water and EEZ borders are never drawn: they read as dotted lines floating in open sea dividing nothing housenumber, road-labels, water-name, poi-labels, mountain-peak-labels, aerodrome-labels, place-labels, city-labels, country-labels.

landuse and landcover carry a match on the feature class so hospitals, schools, cemeteries, military land, retail, grass and wood read distinctly; the tints are blended from existing palette slots, and an unrecognised class falls through to the plain slot colour. Roads tagged brunnel: tunnel are dimmed in place, while brunnel: bridge roads are redrawn by road-bridge-casing/road-bridge above the flat network so an overpass reads as crossing over what it spans. road-oneway draws one-way direction arrows from z16 using a pinned Noto Sans Regular glyph, so it needs no sprite.

road-minor-casing and road-major-casing draw the darker edge under each road. Both casings paint beneath both road fills, so a minor road's casing never crosses a major road at a junction. Their colours are derived from the road/roadMajor slots blended toward textSecondary rather than being separate palette slots, so overriding road restyles its casing too. building-outline is derived from building the same way.

Agents get the same catalogue programmatically from the list_style_layers MCP tool; an unknown id in a theme is a 422 echoing this list.

3D buildings

Setting "buildings_3d": true in a theme (or the Studio toggle under Layers → Buildings) adds a building-3d fill-extrusion layer: from zoom 15 the flat footprints rise into volumes using the OpenStreetMap render_height/render_min_height attributes already in MapMap tiles. City centres carry real surveyed heights; elsewhere buildings fall back to a uniform default, so the effect is strongest where it matters most. Tilt the map (pitch) to see it.

On the web you can also toggle it at runtime without recompiling the style:

const map = createMap({ container: "map", style: "light" });
map.setBuildings3d(true); // and false to return to flat footprints

Mobile: off by default, and never in navigation views. MapLibre Native (the iOS/Android renderer) currently has prohibitive fill-extrusion memory use at street-level zooms (maplibre-native#4107; 900 MB+ at zoom 17, which iOS answers by killing the app). The native SDKs ship two pure JSON transforms: styleWithBuildings3d(styleJson, enabled) to opt a map browsing view in on hardware you've measured, and styleForNavigation(styleJson) which strips 3D and should wrap any style you load into a turn-by-turn view. The default will flip once MapLibre Native lands level-of-detail culling for extrusions.

Studio

Studio is the browser editor over the same theme engine, in four tabs: Map design (pick the base, recolour the palette slots, toggle layers and adjust widths and opacities per layer, colour the POI categories, with a live map preview), Navigation (below), Markers (place coloured glyph pins, dots or small custom images with labels, saved with the style so the SDKs draw them), and Publish. Your working theme autosaves in the browser.

The Map design tab's preset picker offers first-party starting points. The plain Light and Dark bases head the list; the designed styles sit below the divider:

• Streets: the light flagship. Warm paper, green landcover, blue water, white minor roads with amber majors and a warmer motorway, and every label family on.
• Midnight: the dark flagship. A blue-black ground with the road network as the brightest thing on the map and one warm motorway accent.
• Navigator Day: low-glare daylight guidance. Muted landcover, dimmed water, a prominent road hierarchy, POI and house-number label noise off.
• Navigator Night: the same map after dark. Near-black and warm-biased, with a grey-blue major network and an amber motorway spine.
• Outdoor: walking and touring. Landcover-led greens and sands, warm relief shading, emphasised peaks and parks, quiet roads.
• Dataviz: a near-monochrome cool grey for your own data that keeps the road network, with one accent on the motorways.
• Backdrop: the quietest base in the set. Near-paper land, faint water, the road network dropped to hairlines under labels only.
• Print: greyscale for paper. Heavier road casings, serif labels a touch larger, no tint in the halo.

Both Navigator presets are tuned so the default route line stays the highest-contrast element on screen. A preset loads into the editor as an ordinary theme document (your navigation design is kept), so everything remains editable and publishable as your own style.

From the Publish tab's "Use this style" panel: paste your snk_ key and publish: the first publish creates the hosted style (POST /styles), and each one after publishes the next immutable version (POST /styles/{id}). Drop the returned style URL into @mapmap/maps or raw MapLibre, or download the compiled style.json instead. Agents get the same powers through the MCP style tools (list_style_layers, get_style, create_style, set_palette, set_layer_paint); see the MCP guide.

Navigation design

Studio's Navigation panel designs the turn-by-turn look (route line, current-position puck and banner instruction), previewed live on the map. The result is a small design-token block stored under extra.nav in the theme JSON Studio downloads and copies:

{
  "extra": {
    "nav": {
      "version": 1,
      "route":  { "color": "#ff7a1f", "width": 4.5, "opacity": 1, "casingColor": "#8a3d00" },
      "puck":   { "color": "#1f6fff", "size": 14, "headingArrow": true,
                  "imageUrl": "data:image/png;base64,…" },
      "banner": { "background": "#101418", "textColor": "#ffffff", "fontSize": 16, "showLanes": true,
                  "padding": 10, "cornerRadius": 10, "maxWidth": 340 },
      "camera": { "pitch": 60, "zoom": 17.5, "speedMps": 12 },
      "alerts": {
        "background": "#101418", "textColor": "#ffffff", "outlineColor": "#ffffff",
        "cornerRadius": 10, "outlineWidth": 1.5,
        "escalatedBackground": "#c0392b", "escalatedTextColor": "#ffffff",
        "iconSet": "european", "mapIconSize": 1, "mapMinZoom": 12,
        "alertSound": "cameraCalm", "escalatedSound": "cameraUrgent",
        "leadDistance": "standard", "chipPosition": "aboveSpeed",
        "corridorColor": "#e05c6c", "corridorOpacity": 0.55,
        "kinds": {
          "fixed": { "showOnMap": true, "showOnMapWhileNavigating": true,
                     "alertWhileDriving": true, "showInRoutePreview": true,
                     "alertMode": "always", "audioMode": "earcon" }
        }
      }
    }
  }
}

• terrain.seabed (0..1, default absent) reveals the seabed through the sea while hillshade is on: the DEM carries bathymetry, so lowering ocean water's opacity lets the relief show through, tinted by the water colour. Only class=ocean water is affected — lakes and rivers stay opaque — and it composes with a per-layer water opacity override rather than replacing it. The compiled water layer carries the reveal on its ocean branch, at every zoom:

  jsonCopy

  ["match", ["get", "class"], ["ocean"], 0.3, 1]
  

  Turning the dial up also emits an opaque water-sea-base fill — the same ocean polygons, the same colour, at the bottom of the relief sandwich, so the draw order under the sea is:

  textCopy

  water-sea-base → seabed-relief → hillshade → water
  

  That floor is not optional. The reveal makes the ocean fill translucent, and both relief layers are transparent wherever the DEM has no sea floor to draw — so without it a translucent sea shows the background layer, i.e. the theme's LAND colour. Its second job is keeping the sea a sea when the data runs out (below).

  Where the seabed actually reads. The default DEM (Mapzen terrarium on AWS Open Data) carries bathymetry only to tile zoom 10. Above that, open-ocean tiles are a uniform 0 m placeholder. Two things follow, and they are different:

  • the depth colour holds at every zoom, where sea_relief is set. seabed-relief reads its own seabed-dem source, capped at zoom 10 (see below), so past that zoom MapLibre overzooms the last real bathymetry rather than mixing it with the placeholders. Zoom in on the Ligurian Sea and the water stays the same deep blue it was at zoom 10. Without sea_relief there is no depth ramp to hold: the sea is the water colour at every zoom, as it always was.
  • the shading needs data it does not have. There is one hillshade, it reads the DEM at full resolution because it shades the land, and a uniform 0 m tile has no slope to shade. So from about map zoom 11 the sea loses its relief while its colour stays put.

  Both statements are about the compiled style, which paints the sea from the tiles' own water polygons — so they hold wherever those tiles have data. The Studio preview additionally paints the sea OUTSIDE a partial archive's coverage from the elevation model, and that stand-in fades out over map zooms 11.5 to 12.5 as the tiles' own water polygons take the veil back; beyond coverage there are none, so from zoom 12.5 the water out there carries no veil and reads at full strength. That is a preview artefact of a partial archive only. Production Studio runs on planet tiles, where "outside coverage" does not exist, and a published style never carries the stand-in at all.

  Land tiles are unaffected and keep their full resolution. Shelf seas (the Channel, the North Sea) keep real depths a few zooms further. Point terrain.url at a DEM with deeper bathymetric coverage and both the colour and the relief follow it up the zooms with no style change — raise SEABED_DEM_MAXZOOM with it.

  Corrupt DEM tiles, and what the Studio preview does about them. Mapzen's 0 m placeholder is a 757-byte PNG whose every pixel decodes to exactly 0 m. A small number of tiles in that same size class are corrupt, in two measured flavours: a 270-byte tile whose every pixel is (0,0,0), which decodes to −32,768 m; and a 0 m placeholder with a few full-height one-pixel columns of garbage baked in — 13/3413/3100.png is 96.9% exactly 0 m with eight columns reading −2,590 to −14,840 m. Either way the tile carries a cliff of thousands of metres across one DEM pixel, and the hillshade's slope operator lights it as a hard bright/dark line across open sea. The −32,768 m flavour spreads further: MapLibre copies each tile's edge row into its neighbours' 1-pixel border pad, so the four neighbours get the cliff too. Known instances: zoom 14 near 6.95°E and 8.01°E (out of reach behind the render DEM's maxzoom: 13) and a patch at 30.000°W, 40°N that shows from zoom 10 to 13.

  The default DEM is served through a sanitising proxy, and that is the repair. The compiled default terrain.url is https://mapmap.ai/terrain/{z}/{x}/{y}.png, not the archive's own URL. That route fetches the Mapzen tile server-side and, when a tile under 2 KB decodes as one of the two corrupt placeholders, serves a clean 0 m tile in its place. Everything else passes through byte for byte, and a real tile is never even decoded — the smallest tile carrying genuine content anywhere in a 126-tile sweep was 5,267 bytes, well clear of the 2 KB ceiling. Responses are Cache-Control: public, max-age=31536000, immutable and Access-Control-Allow-Origin: *, so a published style running on your own origin gets them from the CDN edge like any other tile. An upstream 404 or 5xx passes its status straight through.

  This applies to published and exported styles, not just the preview: a downloaded style.json carries the proxy URL, so a map rendered in your own MapLibre with no MapMap code in it still gets the repair.

  The DEM is still Mapzen's, and its attribution is contractual: every compiled style carries Terrain data — Mapzen, AWS Open Data on the source, and serving the bytes from our origin does not change that. Keep the credit visible.

  Self-hosters. Setting terrain.url opts out of the proxy entirely — your DEM, your URL, fetched directly. If you point terrain.url at raw Mapzen, the Studio preview still repairs it client-side through a MapLibre custom protocol (one request per tile, no caching of its own), but an exported style with that URL in it carries the defect: that is what the default exists to avoid.

• terrain.sea_relief (default absent) gives the SEA FLOOR its own colour, independent of the land's relief shading. There is only ever one hillshade layer, and it shades the land and the seabed with the same shadow/highlight colours — so a green land turns the sea green too, which is the thing this fixes. Set shallow and deep (both required; a block missing either is dropped whole) and optionally opacity (0..1, default 0.8):

  jsonCopy

  "terrain": {
    "hillshade": true,
    "seabed": 0.7,
    "sea_relief": { "shallow": "#7fb2d9", "deep": "#123b66", "opacity": 0.8 }
  }
  

  The compiler emits a MapLibre color-relief layer, seabed-relief, inserted directly BELOW the hillshade and below water — colour first, shading over it, the same order the land is drawn in (landcover fill, then hillshade), so the depth ramp owns the sea's hue while the shading keeps its full contrast. It rides a third raster-dem source, seabed-dem: the same DEM as hillshade-dem, capped at maxzoom: 10 (see "The seabed ramp reads a z10 DEM" below). color-relief colours the DEM by height, so the ramp runs on ["elevation"] in metres rather than on zoom — a real depth ramp, deep water reading differently from a continental shelf:

  jsonCopy

  ["interpolate", ["linear"], ["elevation"],
    -6000,  "#123b66",
    -20,    "#7fb2d9",
    -20, "rgba(0,0,0,0)",
    9000,   "rgba(0,0,0,0)"]
  

  Everything above −20 m is fully transparent, which is what makes this a sea-only colour: land keeps whatever the hillshade and the landcover give it. The cut-off is −20 m rather than 0 m so the DEM's own vertical error cannot bleed a blue rim along every coastline; the known cost is that genuine land below −20 m — the Dutch polders, the floor of Death Valley — takes a faint tint at the shallow end of the ramp.

  It pairs with terrain.seabed, which decides how much of it you can see: the water fill still paints on top, so with seabed at 0 the sea is opaque and the ramp is invisible — wherever there is a water polygon to paint it, which in a published style is everywhere the tiles cover (see "Where the seabed actually reads" above for the preview's out-of-coverage exception). The layer itself is emitted whether or not hillshade is on — it is a colour of its own, not a reveal of something underneath — and requires terrain.

  There is only ever ONE hillshade, and its shadow and highlight colours belong to the land, so a green land shadow tints the sea's shadows green-blue. A second hillshade in the sea's own colours is not possible: a raster layer cannot be clipped to the ocean polygons, and a second one above water would double-shade the land. The depth ramp underneath owning the hue is the answer to that, not a workaround for it.

• route: line colour, width (px at mid zoom), opacity and casing colour; the defaults are the web SDK RouteLayer look.

• puck: current-position colour, diameter in px, and whether the heading arrow is drawn. imageUrl (optional since v1) sets a custom puck image: an https: or data: URI (PNG/SVG) that replaces the built-in dot and arrow; size still scales it, and it rotates to the heading.

• banner: background/text colours, primary text size in px, and whether the lane diagram row is shown, matching the web SDK GuidanceBanner conventions. padding (px, 6–24, default 10), cornerRadius (px, 0–24, default 10), maxWidth (px, 200–520, default 340) and height (px, 40–120, unset = auto content height) are optional since v1; the block stays "version": 1 and themes saved without them load with the defaults.

• alerts (optional since v1): the safety-camera alert design, written by Studio's "Safety alerts" section. Chip tokens are background, textColor, outlineColor, cornerRadius (px, 0–24) and outlineWidth (px, 0–4); escalatedBackground and escalatedTextColor style the over-the-limit state. iconSet is one of european, us, minimal or brand, with optional per-kind iconUrlOverrides (https: or data: URIs only). alertSound and escalatedSound pick the two earcons from the built-in library (cameraCalm, cameraUrgent, overspeedSoft, zoneEnter, zoneClear), each with an optional alertSoundUrl / escalatedSoundUrl override under the same https: or data: rule. mapIconSize (0.75–1.5 of the default pin ramp) and mapMinZoom (9–14) control the map pins, corridorColor and corridorOpacity (0–1) tint the average-speed corridor on the route line, leadDistance is one of short, standard or long (150 m, 250 m and 400 m floors), and chipPosition is one of aboveSpeed, topLeading or topTrailing. kinds carries one entry per camera kind (fixed, average, red_light, mobile_site, unknown), each with showOnMap, showOnMapWhileNavigating, alertWhileDriving and showInRoutePreview booleans, an alertMode of always, whenSpeeding or never, and an audioMode of off, earcon or earcon_and_speech. Themes saved without the block load unchanged and stay "version": 1; a block that is present always parses complete, escalated tokens included.

  showOnMap and showOnMapWhileNavigating are separate on purpose: browsing the map and driving it are different decisions, and the market warns with or without a planned route, so map display is not gated behind active guidance. A theme written before the split carries only showOnMap, and its navigating value reads as true.

  There are two sounds, not ten. The calm earcon and its escalated variant are the whole audible vocabulary: which camera it is travels in the icon and in speech, and how urgent it is travels in the timbre, so a driver is never asked to learn one chime per camera kind. Set a kind's audioMode to off if you want it silent. The average-speed corridor keeps its own entry and exit pair, which marks a boundary rather than a point alert.

  The built-in earcons are served from https://mapmap.ai/earcons/ (earcon-camera-calm.mp3, earcon-camera-urgent.mp3, earcon-overspeed-soft.mp3, earcon-zone-enter.mp3, earcon-zone-clear.mp3). They are public and unmetered; self-host them by passing your own base URL to navAlertSoundUrl.

  Two behaviours are deliberate rather than configurable. The visual chip is unconditional and calm while audio is the escalation channel, so a driver within the limit still sees the alert and only hears it when alertMode says so. And the chip position is a fixed set of slots rather than free coordinates, so an alert can never cover the speed or the limit, which are the two numbers it is asking the driver to act on.

  Jurisdiction policy is server side and is not styleable. Whether camera positions may be returned at all is decided per country by the gateway before any camera leaves it. This block designs how a permitted alert looks; it cannot widen what is permitted, and a theme carrying an alert design still shows nothing in a territory whose policy omits cameras.

• camera (optional since v1, whole block and each field): the drive camera Studio's "Drive the route" demo uses and the web SDK's NavigationCamera reads as its defaults. pitch (degrees, 0–85, default 60), zoom (14–20, default 17.5) and speedMps (drive speed in metres per second, 2–40, default 12). Explicit NavigationCamera options still win: option > design > built-in. Themes saved without the block load unchanged.

The block never enters the compiled style.json (the compiler ignores it entirely), but it does travel with the theme document, hosted ones included: Studio's publish sends extra with the theme (whenever the design differs from the defaults), the gateway stores it verbatim with that version, capped at 256 KB serialised, and serves it back from GET /styles/{id}/theme. So teams consuming a style via the API get the navigation design too. Pass a downloaded theme file to the web SDK's createMap, which parses extra.nav into map.navDesign and applies it across the navigation UI:

import { createMap, RouteLayer, GuidanceBanner, PositionPuck } from "@mapmap/maps";
import theme from "./midnight-fleet.theme.json"; // downloaded from Studio

const map = createMap({ container: "map", apiKey: "snk_…", style: theme });
await map.whenReady();

const routes = new RouteLayer(map);            // route line + casing from extra.nav.route
const banner = new GuidanceBanner(document.body, map.navDesign?.banner);
const puck = new PositionPuck(map);            // dot + arrow or custom image
puck.setLocation({ lat: 51.5074, lon: -0.1278 }, 45);

…or fetch the design straight from a hosted style's theme endpoint (public, uncached, always the latest publish):

import { navDesignFromThemeUrl } from "@mapmap/maps";

const design = await navDesignFromThemeUrl(
  "https://api.mapmap.ai/styles/midnight-fleet-a1b2c3/theme",
);

Parsing is lenient and clamped exactly as Studio previews it; without a nav block everything keeps the SDK's built-in look. See SDKs for the full reference.

POI theming

The POIs panel (Map design tab) colours the eight POI categories the MapMap maps group OpenMapTiles poi classes into: food_drink, shopping, transport, lodging, health, culture_leisure, education and services (the fallback for any class not grouped elsewhere). Per category you can recolour the dot drawn under the label and the label text; both preview live. The result is a block under extra.poi, alongside the navigation design:

{
  "extra": {
    "poi": {
      "version": 1,
      "categories": {
        "food_drink": { "color": "#ff6b35", "textColor": "#b34700" },
        "transport":  { "color": "#0aa8a8" }
      }
    }
  }
}

Both fields are optional per category: an absent color keeps the built-in dot colour, an absent textColor keeps the theme's textSecondary label colour. Studio omits the whole block while everything is at the defaults, so existing themes are untouched.

Like the navigation design, the block never enters the compiled style.json: it travels with the theme document, publishes with it, and comes back from GET /styles/{id}/theme. The MapMap website maps (Studio's preview included) apply it to their category dots and label text automatically. In the web SDK, a theme document passed to createMap parses into map.poiDesign, and the label-text part applies to any live map:

import { createMap, applyPoiDesign, poiDesignFromThemeUrl } from "@mapmap/maps";
import theme from "./midnight-fleet.theme.json"; // downloaded from Studio

const map = createMap({ container: "map", style: theme });
await map.whenReady();
if (map.poiDesign) applyPoiDesign(map.map, map.poiDesign);

// …or from a hosted style's theme endpoint:
const design = await poiDesignFromThemeUrl(
  "https://api.mapmap.ai/styles/midnight-fleet-a1b2c3/theme",
);

The SDK's default styles label POIs as text (no dots), so applyPoiDesign covers the text colours; the coloured dot icons are drawn by the MapMap website maps today, and packaged sprite icons are planned as part of marker packs. Parsing is lenient: unknown categories and invalid colours are dropped, never fatal.

Label languages

Tiles carry OpenStreetMap name:* translations, 70+ languages on populated tiles, alongside each place's local name. The web SDK's buildStyle takes a labelLanguage option: an ISO code ("de", "ja", "ar", …) renders labels in that language with local-name fallback, "local" shows every place in its own language, and the default is English-first. Pass the built style to createMap:

import { createMap, buildStyle } from "@mapmap/maps";

const map = createMap({
  container: "map",
  apiKey: "snk_…",
  style: buildStyle({ theme: "dark", labelLanguage: "ja" }),
});

See it live on the map: the language picker offers English, local names and fifteen more. Every script renders: the bundled Noto fontstacks are the OpenMapTiles merged builds, covering Arabic, Hebrew, Thai, Myanmar, Khmer, the Indic scripts, CJK and more. On MapLibre GL JS 6.9 and later Arabic and Hebrew shaping is built in: there is nothing to load, and setRTLTextPlugin / getRTLTextPluginStatus are deprecated. On MapLibre 5 you still need the plugin: call maplibregl.setRTLTextPlugin(…) once in your app.

Fonts and sprites

Compiled styles reference glyphs and sprites served by the gateway (public, unmetered, immutable caching):

• GET /fonts/{fontstack}/{range}.pbf: SDF glyph ranges for the bundled fontstacks: MapMap Sans Regular (plus Bold and Italic, all three composited with the merged Noto stacks so every script renders), Noto Sans Regular (plus Bold and Italic), Barlow Regular, Fira Sans Regular, IBM Plex Sans Regular, Inter Regular, Lato Regular, Montserrat Regular, Noto Serif Regular, Nunito Regular, Open Sans Regular, Rubik Regular, Source Sans 3 Regular and Work Sans Regular, all SIL Open Font Licence, static instances. Keep every fontstack the theme names on one of these or those labels drop. Families added in a release reach the hosted fonts endpoint with the next assets deploy; Studio previews them immediately.
• GET /sprite/sprite[@2x].json|png: the first-party sprite sheet (marker, dot, arrow, lane diagrams, road shields, tunnel-restricted).

Status, honestly: compiled styles default their glyph URL to https://fonts.mapmap.ai/{fontstack}/{range}.pbf, which is live and serving. On self-hosted deployments, set the theme's glyphs field to your own gateway's route, e.g. $BASE/fonts/{fontstack}/{range}.pbf. Using your own hand-written style instead of a compiled theme? Point its glyphs and sprite fields at these same routes.

On self-hosted deployments these routes serve when SN_MAP_ASSETS_DIR is set; tiles need SN_TILES_DIR and hosted styles need SN_STYLES_DIR (see self-hosting).

Web SDK quickstart

Availability: @mapmap/maps is live on npm.

@mapmap/maps wraps MapLibre GL with the MapMap style, the pmtiles protocol and typed routing helpers:

npm install @mapmap/maps maplibre-gl pmtiles

As with raw MapLibre, the page needs a container element with an explicit height, <div id="map" style="height: 100vh"></div>, or the map renders blank. The SDK console.errors when it detects this and the other silent blank-map causes; see troubleshooting.

import { createMap, RouteLayer } from "@mapmap/maps";
import "maplibre-gl/dist/maplibre-gl.css";

const map = createMap({
  container: "map",
  apiKey: "snk_…",
  style: "light", // "light" | "dark" | a Studio theme | a style URL
  center: [-1.5, 52.6], // lon, lat
  zoom: 6,
});

await map.whenReady();

const routes = new RouteLayer(map);
await routes.route(
  { lng: -0.1278, lat: 51.5074 },
  { lng: -1.5106, lat: 52.4081 },
  { profile: "truck", truck: { heightM: 4.0, weightT: 40, hazmat: true, tunnelCode: "C" } },
);

createMap is the entry point used throughout these docs and by Studio's publish snippet. It is a functional alias for the MapMapMap class, so new MapMapMap({ … }) takes the same options if you prefer the constructor form.

The truck options cover ADR (the European agreement on carriage of dangerous goods by road; tunnel codes B–E restrict which tunnels a hazmat load may use); the full tunnel-code table is on the conventions page. The style option accepts a Studio theme document directly, so a style built in Studio drops straight into your app. Full SDK reference: SDKs.

Two routes on one map (comparison)

A car-vs-truck (or before-vs-after) comparison is two RouteLayers with distinct ids; recolour the second with setLineStyle, no raw MapLibre sources or layers, and no full design document, needed:

import { RouteLayer } from "@mapmap/maps";

const car = new RouteLayer(map, { id: "route-car" });
const truck = new RouteLayer(map, { id: "route-truck" });
truck.setLineStyle({ color: "#e07b39" }); // dash and casingOpacity too

const a = { lng: -0.1278, lat: 51.5074 };
const b = { lng: -1.5106, lat: 52.4081 };
const [carRoute, truckRoute] = await Promise.all([
  car.route(a, b),
  truck.route(a, b, { profile: "truck", truck: { heightM: 4.5 } }),
]);
// carRoute/truckRoute carry distanceM and durationS for a comparison panel.

setLineStyle survives style reloads (theme swaps) and {} clears it back to the design. If you would rather fetch the second route yourself, the pure helpers do the assembly and parsing, but note buildRouteUrl does not embed the API key in the URL; add the Authorization header on manual fetches (RouteLayer does this internally):

import { buildRouteUrl, parseOsrmRoute } from "@mapmap/maps";

const url = buildRouteUrl("https://api.mapmap.ai", "truck", [a, b], { heightM: 4.5 });
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const parsed = parseOsrmRoute(await res.json());
truck.drawGeometry(parsed.geometry.coordinates);

Exporting the map as an image (design-tool plugins, PNG downloads, server-side thumbnails)? Two gotchas: MapLibre 5 moved preserveDrawingBuffer into canvasContextAttributes, and captures should render offscreen at the target size rather than screenshot the interactive map. The full recipe is in the @mapmap/maps README ("Map screenshots / static image export").

3D terrain

Availability: shipped in @mapmap/maps 0.10.0.

Any MapMap map can drape itself over real elevation and shade the relief:

const map = createMap({
  container: "map",
  apiKey: "snk_…",
  terrain: true, // sensible defaults
});

// or tuned:
createMap({
  container: "map",
  terrain: { exaggeration: 1.4, hillshade: true },
});

// and off again at runtime:
map.setTerrain(false);

The default DEM is the same dataset the gateway samples for POST /elevation. A rendered mountain and a queried one agree with each other, which matters the moment you draw elevation numbers over a 3D map.

The SDK carries the MapLibre terrain lifecycle for you: terrain does not survive a style swap (the SDK re-applies it on every style load, so theme switching just works), hillshading needs its own DEM source rather than sharing the terrain's (sharing produces rendering artefacts), and the DEM's attribution rides alongside the OSM credit automatically.

Two things to know when building on top:

• Terrain displaces the ground by absolute elevation. map.queryTerrainElevation(lngLat) returns metres above sea level, not height above some local zero. A custom layer that draws in a local frame must add the terrain elevation at its anchor, or every distance-derived effect computes from a camera underground.
• Mind the vertical datum when overlaying your own data. GNSS/survey heights are usually ellipsoidal; DEMs are orthometric (geoid). The difference is tens of metres in most of Europe, enough to sink a building into a hillside. Convert before you overlay; the elevation API reports orthometric heights.

Landmark directions

Turn instructions on the map can reference a recognisable place instead of a bare street name: "Turn right just after KFC". The landmarks come from MapMap's first-party POI index, queried around each manoeuvre point on the selected route.

The feature is confidence-gated, because a wrong landmark is worse than none. A place only replaces the street name when it clears a salience bar (petrol stations, supermarkets, stations, places of worship, hospitals, pubs and department stores score highest at 5.0 against a bar of 4.0; fast food sits at 3.0 and only clears it with the brand bonus), sits within 40 m of the junction, and shows no signs of staleness: places whose records carry closed or disused markers are never referenced. When no candidate clears the bar, the instruction keeps the street name.

Toggle it with "Landmark directions" under Options in the directions panel; the choice is remembered on your device. Voice guidance itself already ships in the SDKs; what is not wired up yet is landmark phrasing inside it, so a spoken instruction still names the street.

Report a map issue

Spotted a map error: a road that doesn't exist, a vehicle restriction that's wrong, a shop that closed years ago? Use the flag button on the map: click the map to pin the exact spot, pick a category, optionally add a note and an email for follow-up, and submit. API users can file the same report directly with POST /map-issues (one Standard-class call; the request body is {lat, lon, category, note?, contact?}; see /openapi.json on your gateway for the accepted categories).

Every report is picked up by an agent, which investigates it against OpenStreetMap ground truth, our own geocoder and satellite imagery, and publishes its diagnosis on the public Map Health board. Reports are answered and triaged in minutes, and many fixes go live the same hour.

Reports never edit the map directly, and neither does the agent. A human-verified fix ships in two directions: immediately, as a data override on our own routing gateways, and upstream as a proper OpenStreetMap contribution, so your report improves the map for everyone, not just MapMap users.

Troubleshooting a blank map

Tiles load, no errors, and still a blank page: every cause below is silent by design somewhere in the stack, so the SDK diagnoses them for you. Each issue logs one console.error per page, tagged with the codes below: check the browser console first. (Raw MapLibre users can opt in with the SDK's exported runMapDiagnostics(…).)

Zero-height container

The number-one cause. MapLibre renders into a canvas the size of its container; a container that measures 0px tall gets an invisible canvas (often stuck at MapLibre's small default size, e.g. ~400×300) and no error. Tiles and glyphs load fine, which makes it look like a data problem. The SDK logs [container-zero-height] at construction.

Two common ways to get there:

• A bare <div id="map"> with no height. Fix: <div id="map" style="height: 100vh"> (or any real height from your layout).

• Tailwind v4 / CSS cascade layers. Tailwind v4 emits its utilities inside a cascade layer; maplibre-gl.css is unlayered, and unlayered CSS beats layered CSS regardless of specificity. So absolute inset-0 on the map container silently loses to .maplibregl-map { position: relative } the moment MapLibre adds its class, and the container collapses to 0px. Fix: set the container's position/size with inline styles (style={{ position: "absolute", inset: 0 }}), or import maplibre's CSS into a layer that your utilities can override:

  cssCopy

  /* app.css: declare the layer order, then place maplibre inside it */
  @layer vendor, theme, base, components, utilities;
  @import "maplibre-gl/dist/maplibre-gl.css" layer(vendor);
  

If the height legitimately arrives later (CSS load, layout pass), the warning can be ignored. MapLibre picks up the size on its next resize.

Container not in the DOM

A container element created but never appended renders nothing. [container-detached]: append it before constructing the map.

Two maplibre-gl copies

A duplicate dependency, a CDN <script> next to the bundled copy, or micro-frontends: maps, styles and the pmtiles protocol registration are not shared between two maplibre-gl instances, with confusing partial failures. [duplicate-maplibre]: de-duplicate so the app owns exactly one copy; maplibre-gl is a peerDependency of @mapmap/maps for this reason.

WebGL unavailable

Headless browsers without --use-gl, blocked hardware acceleration, remote desktops. [webgl-unavailable]: the map cannot render at all.

401 unauthorised

A missing, mistyped or revoked API key: the style loads (public), the metered tile/routing requests 401, and the map stays empty. [invalid-api-key]: check the apiKey (keys look like snk_…), or issue one with POST https://api.mapmap.ai/v1/keys. Related gotcha: the pure URL builders (buildRouteUrl, buildGeocodeUrl) never embed the key. Manual fetches need the Authorization: Bearer header.

Basemap tiles 404

The style loads, the PMTiles archive 404s, nothing paints. [basemap-not-found]: check territoryTilesUrl (or your custom style's tiles URL). The hosted archives live at the CDN root (https://tiles.mapmap.ai/planet.pmtiles), and a hash-versioned snapshot URL stops existing after a data rebuild. Use the stable alias.

Web SDK reference: types and helpers

The exported types and helpers of @mapmap/maps that back the classes above. Everything here is importable from the package root (import { createMap, applyTerrain } from "@mapmap/maps"). The pure helpers (coordinates, style assembly, terrain) are browser-free and safe to run in Node.

Constructing the map

new MapMapMap(options) (or the createMap(options) alias) takes a MapMapOptions:

• container, apiKey (snk_…), baseUrl (defaults to https://api.mapmap.ai), style (a MapMapTheme name, a Studio Theme document, a full MapLibre StyleSpecification or a style URL; defaults to "light"), center ([lng, lat]), zoom, territoryTilesUrl, and mapOptions (extra MapLibre MapOptions merged last).
• terrain is true or a TerrainOptions object (see below).
• logo is a LogoOptions object to reposition or relink the MapMap mark. The mark cannot be removed: passing false is accepted so existing code compiles, but it is ignored and logs one warning. Carrying the mark is a condition of the SDK licence.
• attributionPosition is an AttributionPosition ("bottom-left" | "bottom-right" | "top-left" | "top-right", default "bottom-left") for the attribution (the OpenStreetMap and OpenMapTiles credits). The attribution is never removable, and the mark and the attribution are never allowed to share a corner.

SetRouteEffectOptions is the argument to map.setRouteEffect(name, options): the RouteFlowOptions (color, width, speed) plus an optional geometry (a RouteGeometry); omit geometry and the effect arms itself and attaches to whatever route a RouteLayer next draws.

registerPmtilesProtocol(gl?) installs the pmtiles:// protocol on a MapLibre instance. It is idempotent per instance, and MapMapMap calls it for you; call it directly only if you build your own maplibregl.Map (for example from your own bundled maplibre-gl copy) and still want to read MapMap PMTiles.

The MapMap logo control

• LogoControl is the MapLibre IControl that renders the MapMap wordmark. It is typed structurally (onAdd / onRemove) so it needs no maplibre-gl import.
• LogoOptions is { position?: LogoPosition, href? }.
• LogoPosition is "bottom-right" | "bottom-left" | "top-right" | "top-left" (default "bottom-right", the opposite corner from the credit).
• LOGO_SVG is the inline wordmark SVG string (20 px tall, white halo), used by the control; it needs no network fetch, so it works offline and under strict CSPs.

The search box control

SearchBox is a drop-in MapLibre IControl search bar: debounced suggestions as the user types, arrow-key navigation, a typed "select" event with the picked feature, and, optionally, a fly-to and a marker. Like LogoControl it is typed structurally, so it imports maplibre-gl neither at module load nor at runtime.

import { MapMapMap, SearchBox } from "@mapmap/maps";

const map = new MapMapMap({ container: "map", apiKey: "snk_…" });
const search = new SearchBox({ apiKey: "snk_…" });
search.on("select", ({ suggestion, hit }) => {
  console.log(suggestion.name, hit?.postcode);
});
map.map.addControl(search, "top-left");

SearchBoxOptions:

What it costs, plainly. The control calls GET /geocode/suggest once per debounced keystroke and GET /geocode/retrieve once per pick. The suggests are free up to 5,000 a day across every key on your account, then one Standard call each; the retrieve is one Standard call every time. debounceMs is what keeps a busy box inside the allowance: at the 250 ms default a typed word costs a call or two, not one per character, so 5,000 covers a few thousand searches a day rather than a few hundred. If you only need a point, the "select" event's suggestion already carries lat/lon, so you can ignore the retrieve entirely and pay nothing for search inside the allowance; see Search as you type for why our suggestions include coordinates when the market's usually do not.

The control also fires the quota-free POST /geocode/selection relevance ping when a result is picked, so what your users actually choose feeds back into ranking. It is fire-and-forget: a refused ping never surfaces to the user and never delays the "select" event.

• SearchBoxSelectEvent is { suggestion, hit?, query }. hit is the full GeocodeHit from the retrieve, and is undefined when the retrieve failed. The suggestion's own coordinates always survive, so a failed retrieve still leaves you with a usable point.
• SearchBoxSelectListener is the "select" handler type. on("select", fn) returns an unsubscribe function; off("select", fn) also works.
• SearchSuggestion is one dropdown row: { id, name, context, kind, lat, lon }.
• SearchBoxMap is the structural slice of a MapLibre map the control needs: a maplibregl.Map, a MapMapMap's .map, or your own fake.

For a search UI of your own, the wire helpers are exported too:

• buildSuggestUrl(gatewayUrl, query, options) assembles the suggest URL; SuggestUrlOptions is { limit?, bias?, zoom? } with bias as [lon, lat]. The API key is never embedded; send it as a bearer header.
• buildRetrieveUrl(gatewayUrl, id) does the same for one document id.
• parseSuggestResponse(body) turns the response into SearchSuggestion[], dropping any row the retrieve endpoint could not resolve.
• DEFAULT_DEBOUNCE_MS is the 250 ms default, exported so your own input can match the control's rhythm.

Accessibility: the input is an aria-combobox with aria-expanded, aria-controls and aria-activedescendant; the dropdown is a listbox of options; arrow keys wrap, Enter picks, Escape closes; and focus is visible.

3D terrain helpers

TerrainOptions configures a DEM: exaggeration (1 is true to life, clamped 0 to 8), url (DEM tile template), encoding ("terrarium" or "mapbox"), maxzoom, tileSize, attribution and hillshade (add a relief-shading layer). MapMapMap owns the terrain lifecycle, but the primitives are exported for maps you build yourself:

• resolveTerrain(true | TerrainOptions) normalises the input into a full, clamped config (or null when off).
• applyTerrain(map, cfg) adds the raster-dem source and switches terrain on; safe to call on every style.load, which is required because terrain does not survive setStyle.
• removeTerrain(map) turns terrain off and removes what applyTerrain added.
• DEFAULT_TERRAIN_URL is the Mapzen terrarium tile set on AWS Open Data, the same dataset the gateway reports from POST /elevation, so a map and an elevation query agree. DEFAULT_TERRAIN_ATTRIBUTION is its required credit (the DEM is not covered by the OSM credit the vector tiles carry).

Coordinates

LngLatLike is a longitude/latitude accepted in three shapes: [lng, lat] (GeoJSON/MapLibre order), { lng, lat }, or { lon, lat }.

• toLngLat(point) normalises any of those to a [lng, lat] tuple, throwing on a non-finite or out-of-range coordinate (a guard against swapped axes).
• formatCoord(point) formats one point as an OSRM lon,lat string.
• formatCoords(points) formats an ordered list as an OSRM path (lon,lat;lon,lat;…); it requires at least two points, matching the gateway.

Routing types

• RouteOptions is a single route request: profile (a RouteProfile, default "driving"), truck (TruckParams), voice, banner and language (BCP 47, e.g. "en-GB").
• TruckParams is the truck/ADR vehicle profile forwarded to the gateway's OSRM truck extensions: heightM, widthM, lengthM, weightT, hazmat and tunnelCode (ADR 8.6.4, e.g. "C" or "B/D"; the slash is URL-encoded for you).
• RouteGeometry is a GeoJSON LineString ({ type, coordinates: [lng, lat][] }), ready to hand to a MapLibre source.
• AdrDimensions is the physical truck profile for the ADR check (heightM, widthM, lengthM, grossWeightT, axleLoadT, axleCount); unset fields default to the EU 96/53/EC maximum artic (4.0 m / 2.55 m / 16.5 m / 40 t).
• AdrCheckRequest is the input to POST /adr/check: hazmat, tunnelCode? (the vehicle load's code), dimensions? and tunnelCategory ("A" to "E"). AdrCheckResult is the parsed response: { status, reason?, raw }.

Drawing routes

RouteLayer draws routes; these types shape its look:

• RouteLayerOptions (its constructor argument): baseUrl, apiKey, id (source/layer id prefix, default "mapmap-route"), design (a Studio NavRouteDesign), alertsDesign, progressColor (the travelled part of a vanishing route line), alternativeCasingColor, alternativeColor, ferryColor, and endpoints (true or an EndpointsDesign).
• RouteLayerIds is the object returned by layer.ids, naming every generated MapLibre source and layer (source, casing, line, maneuverSource, maneuver, corridorSource, corridor, endpointsSource, endpoints) so you can reach them with setPaintProperty or queryRenderedFeatures.
• RouteLineStyle ({ color?, dash?, casingOpacity? }) is a runtime override applied over the design or built-in look.
• EndpointsDesign chooses how start, end and waypoints are drawn: start, end, waypoint (each an EndpointMarker or false) and numberWaypoints. EndpointMarker is one designed pin ({ icon?, text?, colour?, size?, label? }); these are symbol-layer markers, so they appear in canvas exports.
• SIGNAL_BLUE (#3a86ff) is the MapMap brand signal blue, the default route-line colour.

Reachability rings

IsochroneLayer renders reachability contours from POST /isochrone:

• ShowReachabilityOptions is the argument to showReachability: origin (LngLatLike), mode (a ReachabilityMode, default "walk"), minutes (contours, e.g. [5, 10, 15]), color and costingOptions (forwarded Valhalla costing options).
• ReachabilityMode is "walk" | "cycle" | "drive" | "truck" or any raw Valhalla costing string; the friendly names map onto pedestrian, bicycle and auto.
• IsochroneLayerOptions (its constructor argument) is { baseUrl?, apiKey?, id? }.
• IsochroneFeatureCollection is the GeoJSON FeatureCollection the gateway returns and showReachability resolves to (each feature carries a contour in minutes).

Custom markers

MarkersLayer draws a theme's designed markers and labels (the extra.markers block, schema v1) on a MapLibre map, alongside the parser, renderer and constants that back it. Everything here is a locked contract shared with MapMap Studio's markers panel and the gateway's Rust validator: ids, defaults and cache-key formats must match across all three.

Reading markers off a theme:

import { MarkersLayer, markersFromThemeUrl, hasBakedMarkers } from "@mapmap/maps";

const markers = await markersFromThemeUrl(
  "https://api.mapmap.ai/styles/midnight-fleet-a1b2c3/theme",
);
if (markers) new MarkersLayer(map.map, markers);

• markersFromTheme(theme) reads and leniently parses the extra.markers block from a theme document already in hand; markersFromThemeUrl(url, fetchImpl?) fetches a hosted theme and does the same. Both return undefined when the theme carries no markers block, so "no markers" is distinguishable from "an empty designed set".
• parseMarkers(value) is the underlying lenient parser: it returns a MarkersBlock ({ version: 1, items: MarkerItem[] }), skipping invalid items (bad or duplicate id, out-of-range coordinates) and falling bad fields back to their defaults, so a hand-edited theme can never break the map. At most MAX_MARKER_ITEMS (200) survive.
• MarkerItem is one parsed marker: id, lng, lat, icon (a MarkerGlyphId), optional image (a custom data: URI), colour, size (a MarkerSize) and optional label.
• MarkersLayerOptions (the layer's third argument) carries onImageError, called when a custom image passes the schema but MapLibre cannot rasterise it (usually an SVG with no intrinsic size). MarkersLayerIds is the object returned by layer.ids, naming the shared source and layer (both the contract id mm-user-markers) for escape-hatch styling.

The glyph set is a fixed, ordered contract:

• MARKER_GLYPH_IDS is the 21 glyph ids in order (pin, dot, star, heart, flag, home, work, food, cafe, bar, shop, hotel, parking, fuel, charging, transit, bike, camera, music, warning, info); MarkerGlyphId is that union type; isMarkerGlyphId(v) is the type guard.
• markerGlyphPaths is the 24×24-viewBox SVG path data for every glyph, keyed by id; MARKER_PIN_BODY_PATH is the coloured teardrop pin body every glyph except dot is drawn on; MARKER_GLYPH_VIEWBOX (24) is their coordinate space.

Rendering and cache keys:

• renderMarkerImage(options) rasterises one marker to ImageData ready for map.addImage, taking a RenderMarkerImageOptions (icon, colour, size, and text for short 1–3 character pins, numbered waypoints, lettered stops). It returns a RenderedMarkerImage ({ image, pixelRatio: 2 }), or null in non-DOM environments.
• markerImageKey(icon, colour, size), markerTextImageKey(text, colour, size) and markerImageDataKey(dataUri) build the stable map.addImage cache keys (glyph pins, short-text pins, and hashed custom images respectively) so identical markers share one registered image.
• markerImage(v) validates a custom data: image URI (png/jpeg/webp/svg, at most 64 KB decoded) or returns undefined; markerText(v) normalises a short pin text; truncateChars(text, max) cuts a string by Unicode scalar (the same count the Rust validator uses).
• hasBakedMarkers(map) reports whether the style already carries compiler-baked marker layers, in which case the markers render in any MapLibre client with no SDK code, and you only need a MarkersLayer to change them at runtime or to draw custom-image markers a static sprite cannot carry. BAKED_MARKERS_GLYPH_ID (mm-user-markers-glyph) is the baked glyph layer that signals it; MARKERS_ID (mm-user-markers) is the runtime source and layer id.

The contract constants and their defaults: MARKER_SIZES (["s", "m", "l"]), MARKER_SIZES_PX (the CSS pixel size of each preset), MARKER_LABEL_TEXT_SIZES (label px per preset), MARKER_DEFAULT_COLOUR (#1a6bff, marker blue), MAX_MARKER_IMAGE_BYTES (64 KB), MAX_MARKER_ITEMS (200), MAX_MARKER_ID_LENGTH (64), MAX_MARKER_LABEL_LENGTH (120) and MAX_MARKER_TEXT_LENGTH (3). The MarkerSize type and MarkersBlock interface complete the set.

POI category design

The POI theming helpers (see POI theming above) are all exported for building your own tooling:

• PoiDesign is the parsed extra.poi block ({ version: 1, categories }); PoiCategoryDesign is one category's optional color (dot) and textColor (label) overrides.
• parsePoiDesign(value) leniently parses a raw block. Unknown category ids and invalid colours are dropped, never fatal. poiDesignFromTheme(theme) reads it from a theme document (returning undefined when no block is present), the in-hand counterpart to poiDesignFromThemeUrl.
• defaultPoiDesign() is the empty (all-built-in) design; poiDesignIsDefault(design) is true when a design changes nothing.
• poiTextColorExpression(design, fallback) builds the MapLibre text-color value applyPoiDesign sets on the poi-labels layers: a plain colour when nothing overrides label text, else a match on the tile's class.
• POI_CATEGORY_COLORS is the ordered [id, colour] list of the eight categories with their built-in dot colours; POI_CATEGORY_IDS is just the ids in order; POI_CLASS_CATEGORIES maps each OpenMapTiles poi class into its category (anything unlisted falls through to services). builtInPoiColor(categoryId) looks up one category's default dot colour.

Your own places (store finder)

PlacesLayer drops your own points (stores, depots, POIs) onto a map with clustering, popups and nearest-branch helpers (the store-finder use case). Its supporting types:

• PlacesInput is what the layer and setPlaces accept: a Place[] or a PlacesFeatureCollection (a GeoJSON FeatureCollection of PlacePointFeature points). placesFromGeoJSON(collection) is the normaliser that turns the collection into Place[], deriving each id from feature.id, then properties.id, then the index.
• PlacesLayerOptions (the constructor argument) covers cluster, clusterRadius, clusterMaxZoom, color, clusterColor, icon (a PlacesIcon or a record of them for per-place pins), iconProperty, label, fitBounds, onPlaceClick and popup. PlacesIcon is one custom pin image ({ url, size? }); PlacesLabelOptions configures the per-place name labels (property, size, and colours in both British and American spellings).
• PlacesLayerIds is the object returned by layer.ids, naming every generated source and layer (source, points, clusters, clusterCounts, labels, pointsFallback) for escape-hatch styling.
• PlacesSelectOptions is the argument to layer.select(id, options) for list-to-map sync: popup, flyTo and zoom.
• nearest(origin, n) returns PlaceWithDistance[] (a Place plus straight-line distanceM); nearestByDriveTime(origin, options) returns PlaceWithDriveTime[] (durationS plus driven distanceM) via the gateway POST /matrix, taking a NearestByDriveTimeOptions (n, costing, costingOptions). haversineDistanceM(a, b) is the pure straight-line distance helper behind nearest.

Manoeuvre and lane icons

The turn-by-turn glyph set (also the @mapmap/maps/direction-icons subpath) and the lane helpers GuidanceBanner renders:

• directionIcons is the record of inline 20×20 SVG markup for every manoeuvre, keyed by name; DirectionIconName is that key union.
• iconNameForManeuver(type, modifier, drivingSide?) maps an OSRM-shaped manoeuvre to a DirectionIconName, degrading unknown input gracefully to a renderable turn icon; directionIconSvg(type, modifier, drivingSide?) returns the markup directly.
• iconNameForStep(step) is the preferred single-step entry point: it reads a DirectionIconStep (maneuver, driving_side, mode) and resolves u-turn direction and ferry mode from the step itself. iconNamesForSteps(steps) resolves a whole turn list, because a roundabout's through-angle icon can only be worked out by pairing its enter and exit steps.
• LaneIndication is one lane's guidance (directions, valid, active, activeDirection); laneArrowDirection(lane) picks the direction to draw (the resolved activeDirection, else the first permitted direction); directionArrow(direction) is the Unicode-arrow text fallback for a direction (sprite lane icons ship with the map assets).

Style assembly and constants

buildStyle(options) compiles a BuildStyleOptions into a full MapLibre style over the MapMap territory tiles, mirroring the sn-style crate so client-side and build-side styles compile identically.

• BuildStyleOptions is { labelLanguage?, theme?, territoryTilesUrl? }, where theme is a MapMapTheme name or a full Theme document.
• MapMapTheme is the built-in palette name, "light" | "dark".
• LayerOverride is one per-layer override merged onto a skeleton layer: { visible?, paint?, layout?, filter?, minzoom?, maxzoom? }.
• ThemeEffects is the optional visual-effects block ({ route?: "flow" | "none", params? }), compiled into the style's metadata so a hosted style URL or a baked package can carry it.
• toPmtilesUrl(url) prefixes a tiles URL with pmtiles:// if it is not already there.
• PALETTE_SLOTS is the ordered list of [slot, lightDefault, darkDefault] palette entries, and SOURCE_LAYERS is every OpenMapTiles source-layer the tiles emit and the skeleton styles. Honestly: the SDK's list has 17 entries where the gateway accepts 25. ice, roadMotorway and the six landcover-class slots (wood, grass, wetland, farmland, sand, rock) landed on the gateway first and are not in the published @mapmap/maps constant yet, so treat it as a convenience export and the gateway's own 422 (or the list_style_layers MCP tool) as the authority. Setting any of those slots in a theme works today regardless; only the client-side constant lags.
• OSM_ATTRIBUTION (© OpenStreetMap contributors), OPENMAPTILES_ATTRIBUTION (© OpenMapTiles) and FULL_ATTRIBUTION (both combined) are the legally required credits stamped on every compiled style's tile source; no theme field can remove them.
• DEFAULT_GLYPHS_URL is the default PBF fontstack endpoint, and DEFAULT_TERRITORY_TILES_URL is the default territory PMTiles URL (overridable per map).
• effectsFromStyleMetadata(metadata) reads a compiled style's effects block back out ({ route: "flow", params? } or undefined), and EFFECTS_METADATA_KEY ("mapmap:effects") is the metadata key it lives under. MapMapMap uses these to auto-enable a route effect from the style alone.

Attribution

Map data derives from OpenStreetMap and the tiles follow the OpenMapTiles schema and cartography. Anything you render or republish must credit "© OpenStreetMap contributors" with a link to openstreetmap.org/copyright (ODbL), and "© OpenMapTiles" with a link to openmaptiles.org (CC-BY 4.0). Every document the tiles API serves carries both credits, and so do the compiled styles, so a MapLibre map renders them for you.

Next steps

• Conventions: base URL, auth, error envelope, quotas and ADR tunnel codes
• Territories: which territories exist and what they cover
• SDKs: the full @mapmap/maps reference
• MCP guide: style the map from an agent

The seabed ramp reads a z10 DEM

seabed-relief reads seabed-dem — the same tiles, encoding and tile size as hillshade-dem, with maxzoom: 10 instead of 14. Mapzen terrarium carries real bathymetry to tile zoom 10 and uniform 0 m placeholders above it, so a z14 source hands the depth ramp two different answers for one patch of open sea depending on which tile the cache kept: a tile painted from a cached z10 parent takes the deep end of the ramp, its neighbour painted from a real, flat z14 tile paints nothing. That rendered as a hard-edged navy/pale patchwork on tile boundaries at z13-z14 — cache-dependent, so it came and went as you zoomed. Capping the source removes the choice: above z10 every tile is an overzoom of the same real bathymetry (measured over the Ligurian Sea at z13, open-sea luminance spread p05-p95: 89.8 before, 0.2 after). The hillshade keeps maxzoom: 14, because it shades the land, where every level is real data. The source is emitted only alongside sea_relief, so a style without it is byte-identical.

3D mesh stops at z10

The terrain-dem source (the 3D mesh) is capped at maxzoom: 10, the last level at which the default DEM carries bathymetry, while hillshade-dem keeps maxzoom: 14. MapLibre builds each terrain tile's bounding box from the DEM one level up and its far plane from the tile itself; where a DEM switches from real bathymetry to flat placeholders (Mapzen terrarium does at z11), an ancestor's box can sit wholly below the child's far plane and the whole subtree is culled — nothing is drawn over open sea. Capping the mesh keeps the ranges nested. Land relief comes from the hillshade source and is unaffected; the mesh cap shifts 3D silhouettes by about a pixel at z13–z15.