Skip to content

50,000 free calls a month, card-free. Get an API key →

Log inGet an API key
Documentation menu
docs / api / post-v1-route-observations
routing

POST/v1/route/observations

API key required, sent as Authorization: Bearer snk_… or ?api_key=snk_….

Call it

bash
curl -fsS -X POST "https://api.mapmap.ai/v1/route/observations" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Request body

application/json · ObservationsBody

The route shape as polyline6, plus optional units and silence budget

FieldTypeRequiredDescription
geometry_polyline6stringyesThe route shape as a Google encoded polyline, six-digit precision, typically geometry_polyline6 straight out of a prior /route response.
max_observationsintegernoCeiling on how many observations come back (1 to 200, default 40).
min_gap_mnumbernoLeast distance along the route between two observations, metres (default 2000). This is a floor, not a target: when a route holds more observations than max_observations, the gap widens beyond this on its own so the survivors stay spread over the whole journey.
unitsstringnoUnits for spoken distances: miles (the default), or kilometers, spelled as the routing engine spells it so a body pasted from a /route request works. kilometres and km are accepted too.

Responses

200Observations in route order, each with at_m, a kind, the map's own subject name, a say sentence short enough to speak, and the basis the claim rests on; plus a coverage census of what the data could and could not answer (including tiles_missing against tiles_unreadable, and elevation_source: model, disabled or unavailable), the attribution both source licences require, and the standing caveat
400Invalid request
401Missing or invalid API key
429Quota or rate limit exceeded
501This deployment has no basemap archive configured, or none of its tiles covers this route (urn:sn-gateway:problem:observations-not-enabled), so nothing could be observed
503The basemap archive is configured and could not be read (urn:sn-gateway:problem:observations-archive-unreadable); no tile was readable, so an empty list would have been a lie about the ground

Error bodies follow the shared problem model documented on API conventions.

Also under routing

POST /centroidPOST /isochronePOST /locatePOST /matrixPOST /optimisePOST /optimise/replanPOST /routePOST /route/alongPOST /route/progressPOST /route/reportGET /route/v1/{profile}/{coordinates}POST /trace_attributesPOST /trace_routePOST /v1/cameras/alongPOST /v1/charging/alongPOST /v1/clusterPOST /v1/errands/planPOST /v1/ev/planPOST /v1/fuel/alongPOST /v1/incidents/alongPOST /v1/jobs/matrixPOST /v1/jobs/optimisePOST /v1/jobs/replanPOST /v1/route/heritagePOST /v1/weather/alongGET /v1/zones

Generated from https://api.mapmap.ai/openapi.json on 2026-09-22 · operationId post_route_observations