Documentation menu
API endpoints
84 public endpoints, one page each. Every page on this index is generated at build time from the document the gateway publishes at /openapi.json, so what you read here is what that deployment declares, not a second copy of it maintained by hand.
gateway 0.3.0 · read from https://api.mapmap.ai/openapi.json on 2026-09-17 · 33 admin and console operations are not listed
The rules these endpoints share, authentication, coordinate order, quotas, the error model and the ADR tunnel codes, are defined once on API conventions. For the narrative version with worked requests, read the API reference guide.
assets
Static map assets: SDF font glyph ranges and sprite sheets referenced by compiled styles. Public, unmetered, immutable caching
`GET /fonts/{fontstack}/{range}.pbf`: one SDF glyph range.
`GET /sprite/{file}`; a sprite-sheet file: `<sheet>.json`, `<sheet>.png`, `<sheet>@2x.json` or `<sheet>@2x.png` (the four names MapLibre resolves from a style's `sprite` base URL), for either sheet in [`SPRITE_STEMS`].
boundaries
Administrative boundary lookup: point-in-polygon against the Valhalla admins.sqlite. Standard price class, metered per request. 501 unless the operator sets SN_ADMIN_BOUNDARIES_DB. OSM-derived (ODbL) — see docs/THIRD-PARTY-NOTICES.md
clearance
Measured overhead clearance along a route, from baked survey geometry (crates/sn-clearance). A within-survey difference with a stated uncertainty bound, never a signed or legal clearance and never a pass over ground the survey did not cover. Standard price class, never premium: a safety check carries no extra charge. 501 unless the deployment publishes at least one clearance artefact
collection
compliance
Metered ADR compliance endpoints
coordinates
Reprojection between reference systems, and the published list of the ones it will do it for. Every supported CRS states its own datum-shift error, and a code outside the table is refused by name rather than approximated. Standard price class, one unit per request whatever it carries
elevation
Point and along-route elevation via Valhalla's native /height action. Honest per-sample source/resolution metadata and a null (never a guess) wherever the engine has no DEM tile coverage. Standard price class, metered per request. 501 unless the operator sets SN_ELEVATION_ENABLED=true (off by default until DEM tiles are staged)
feedback
Integration retros: the structured end-of-integration report an agent (or human) submits once — what was built, problems, gotchas, wins and docs gaps. Key-authenticated, never charged, rate-limited per key. Content is stored verbatim and treated as untrusted text
geocode
geocoding
Metered Photon geocoding proxy (forward and reverse): GeoJSON passthrough, Standard price class. 501 unless the operator sets SN_PHOTON_URL
`GET /geocode?q=<text>&limit=<n≤10>&lang=<code>&bias=<lon>,<lat>&bbox=<minLon>,<minLat>,<maxLon>,<maxLat>&country=<cc>[,<cc>…]`.
`POST /geocode/batch`: many geocodes in one call.
`GET /geocode/retrieve?id=<document id>`.
`GET /geocode/reverse?lon=<f64>&lat=<f64>[&kinds=..&categories=..&name=..&radius_m=..&limit=..]`.
`GET /geocode/suggest?q=<text>&limit=<n≤10>&bias=<lon>,<lat>&bbox=…&lang=…`.
map-issues
User map-error reports ("Report a map issue"): a pin, a category and an optional note, key-authenticated and metered at the Standard price class. Reports never edit map data directly — the team triages them (see the admin surface) and verified fixes flow into the deployment's OSM-overrides file and upstream OpenStreetMap contributions
meta
Unauthenticated service metadata
Minimal service index.
Backend-aware health check: 200/`ok` when the primary routing backend answers, 503/`degraded` when it does not.
`llms.txt` (<https://llmstxt.org/>) describing the API for agent consumers, with runnable curl examples.
The generated OpenAPI 3.1 document, with the configured public URL as the server entry.
The read-only status surface: what this box is serving.
Terms of service: a 307 redirect to `SN_TERMS_URL` when the operator hosts the terms elsewhere (e.g. the website's `/terms` page), otherwise a plain-text pointer so the `tos` URL echoed by self-serve signup never dangles.
oauth
OAuth 2.1 authorization server: RFC 8414 discovery, RFC 7591 dynamic client registration, and the token endpoint. Public clients only (PKCE S256, no client secrets), rotating refresh tokens with reuse-revokes-chain, and client-id metadata document (CIMD) clients. An issued `sno_` access token resolves in the auth layer to a real API key, so every existing quota, metering and billing rule applies unchanged. The interactive authorization page lives on the website (SN_OAUTH_AUTHORIZE_URL); 501 unless the deployment has one
RFC 8414 authorization-server metadata.
Mints an authorization code for a signed-in identity. **Internal**: admin-token gated, exactly like `/admin/*` and the website's other server-to-server calls, and never reachable from a browser.
Dynamic client registration (RFC 7591). Public clients only: the response carries no `client_secret`, and any `token_endpoint_auth_method` other than `"none"` is refused rather than silently downgraded.
The token endpoint: authorization-code and refresh-token grants.
places
Customer places ("bring your own places"): per-key proprietary place datasets with full-text and nearest search over the caller's own tantivy index. Never merged into OSM-derived data (ODbL boundary). All routes key-authenticated and metered at the Standard price class
`DELETE /places`: remove the caller's dataset and index. Idempotent: deleting an empty slate is still a 204.
`GET /places`: the caller's stored dataset.
`PUT /places`: replace the caller's place dataset and rebuild its search index.
`GET /places/nearest?lat=…&lon=…&limit=…`: the caller's places nearest to a point, by haversine distance (no text query, no index).
`GET /places/search?q=…&lat=…&lon=…&limit=…&category=…`: full-text search over the caller's own places, proximity-biased when a focus point is given.
pointclouds
routing
Metered routing endpoints
Finds the least-cost meeting point of several locations (see module docs).
Isochrone endpoint (see module docs).
Snaps each location to the road graph (see module docs).
Matrix endpoint (see module docs).
Route-optimisation endpoint (see module docs). `/optimize` is an alias.
Re-plan a fleet mid-shift (see module docs). `/optimize/replan` is an alias.
Valhalla-compatible route endpoint (see module docs).
Along-route search endpoint (see module docs).
Progress endpoint (see module docs).
Report endpoint (see module docs).
OSRM-compatible route endpoint (see module docs).
Map matching to per-edge attributes (see module docs).
Map matching to a route (see module docs).
Safety cameras along a route shape (see module docs).
Best EV chargers along a route (see module docs).
Capacity-constrained clustering (see module docs).
Plans an EV journey with its charge stops (see module docs).
Cheapest fuel along a route (see module docs).
Traffic incidents and closures along a route shape (see module docs).
Submit a matrix to the asynchronous lane.
Submit an optimisation problem to the asynchronous lane.
Submit a mid-shift re-plan to the asynchronous lane.
Forecast weather along a route, aligned to each point's ETA (see module docs).
The curated UK zone dataset, with provenance.
self-serve
Agent-first self-serve keys: one-call signup, magic-link verification, quota-free status poll. Beyond the free tier, 402 responses use the x402 machine-payment wire format
List the caller's recent jobs (quota-free).
Read one job (quota-free).
One-call signup: issues a provisional key and emails a magic verification link.
Key status for the calling agent (quota-free: polling it never consumes the free tier).
Mint (or rotate) the calling key's webhook signing secret (quota-free).
Magic-link verification: upgrades every provisional key of the identity to the verified free tier. Answers HTML for browsers/email clients and JSON when `Accept: application/json`.
The calling key's own metered units, day by day and endpoint by endpoint (quota-free: reading it never spends units).
`POST /v1/x402/topup?usd={bundle}`.
static-maps
Rendered map images for callers that can look at a map but cannot run one: camera, overlays (encoded polyline, GeoJSON, markers) and format in the query string, or the GeoJSON overlay in a POST body. The gateway renders nothing itself — it checks the key, meters the call and proxies the same renderer the keyless website route uses, so the keyed image and the keyless one cannot disagree. The renderer's own ETag and Cache-Control pass through untouched. Standard price class, a flat block of units per image
styles
Hosted style API (MapMap Studio): versioned, immutable MapLibre styles compiled from sn-style theme documents. Compiled-style and theme reads are public and unmetered (browser map clients fetch them by bare URL); listing is authenticated and scoped to the caller's own styles; publishes are metered at the Standard price class and enforce ownership
`GET /styles`: the CALLER'S hosted styles with their latest versions.
`POST /styles`; create a style: validate and compile the theme, store it as version 1 under a freshly generated id.
`DELETE /styles/{id}`: remove a style and every version of it.
`GET /styles/{spec}`: a compiled MapLibre style.
`POST /styles/{id}`: publish a new immutable version of an existing style (existing versions are never modified).
`GET /styles/{id}/theme`: the latest theme document (the editable source a new version is published from; never cached).
territories
Metered territory update-channel downloads (signed static files; devices verify signatures and hashes themselves)
`GET /territories`: the signed channel index (`index.json`), byte exact so the detached signature verifies over the response body.
`GET /territories/{id}/{version}/layers/{addr}/{file}`: a content-addressed layer blob, streamed with a strong BLAKE3 ETag, single-range `Range` support and immutable cache headers.
`GET /territories/{id}/{version}/manifest`: a version's signed package manifest (`manifest.json`, exact signed bytes).
`GET /territories/{id}/{version}/manifest.sig`: the manifest's detached base64 ed25519 signature.
`GET /territories/index.sig`: detached base64 ed25519 signature over the exact bytes of `/territories`.
tiles
Hosted vector-tiles API: per-tile MVT, TileJSON and a MapLibre style from the territory PMTiles. Standard price class, metered per request
`GET /tiles/{territory}/{z}/{x}/{y}.mvt` (also `.pbf`): one vector tile.
`GET /tiles/{territory}/style.json`: a ready-to-render MapLibre style.
`GET /tiles/{territory}/tiles.json`: a TileJSON 3.0 document.
timezone
Timezone-at-coordinate: IANA zone id, UTC offset, DST offset and abbreviation at a given timestamp. Backed by Valhalla's own timezones.sqlite boundary database and chrono-tz's IANA rules. 501 unless the operator sets SN_TIMEZONE_SQLITE. Standard price class, metered per request