POST/v1/route/observations

Auth	An API key, as `Authorization: Bearer snk_…` or `?api_key=snk_…`. Metered. Needs a full key; a browser (`maps`) key is refused.
Price	A flat 10 calls. Class: standard, or premium for truck and ADR work. Published as `unit_rules.route_observations` in /pricing.json.
Premium	When the body asks for truck routing: `"costing": "truck"`, a top-level `adr` object or `"hazmat": true`

What it does

POST /v1/route/observations.

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 '{"geometry_polyline6":"string"}'

Request body

application/json · ObservationsBody

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

Field	Type	Required	Description
geometry_polyline6	string	yes	The route shape as a Google encoded polyline, six-digit precision, typically `geometry_polyline6` straight out of a prior `/route` response.
max_observations	integer	no	Ceiling on how many observations come back (1 to 200, default 40).
min_gap_m	number	no	Least 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.
units	string	no	Units 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.

Example: A request assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json

{
  "geometry_polyline6": "string"
}

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

Field	Type	Required	Description
attribution	string	no	Map data attribution.
caveat	string	no	How the observations are derived, and their limits.
coverage	object	no	How much of the route the map data covered, by kind.
observations	object[]	no	Observations in route order: `kind`, `subject`, `at_m`, `offset_m`, `basis` and `say`.
route	object	no	The route read: `length_m` and `shape_points`.

Example: Recorded from the hosted gateway on 2026-11-05 with a test key: POST /v1/route/observations on a central London route shape; lists trimmed to their first items

json

{
  "attribution": "Map data © OpenStreetMap contributors, ODbL. Basemap schema © OpenMapTiles, CC-BY 4.0.",
  "caveat": "Observations are computed by intersecting the route's geometry with OpenStreetMap-derived basemap tiles at zoom 13 and with this deployment's elevation model. A crossing means the route's mapped line crosses a named river or canal's mapped line. A settlement means the route passed within a stated distance of that settlement's mapped centre point, published as `offset_m`, NOT that a town boundary was crossed: the basemap carries settlements as labelled points, not as boundaries. A road means one named or numbered road was the only one within 25 m of the route for the stated distance. A climb is the height the road itself reached, measured at the route's own points. Nothing here claims anything can be seen from the driving seat, and nothing here names a hill, a peak or a view. Streams, drains and ditches are excluded from crossings because a culvert is not an event. Anything the tiles do not name is counted in `coverage` and not spoken.",
  "coverage": {
    "elevation": {
      "found": 4,
      "named": 4
    },
    "elevation_source": "model",
    "road": {
      "ambiguous_m": 0,
      "named_m": 0,
      "unnamed_m": 1000
    },
    "settlements": {
      "found": 8,
      "named": 1
    },
    "tiles_missing": 0,
    "tiles_read": 1,
    "tiles_unreadable": 0,
    "uncovered_m": 0,
    "watercourse_crossings": {
      "found": 0,
      "named": 0
    }
  },
  "observations": [
    {
      "at_m": 0,
      "basis": "place.name",
      "kind": "settlement",
      "offset_m": 595.2643863089617,
      "say": "Passing through Covent Garden.",
      "subject": "Covent Garden"
    }
  ],
  "route": {
    "length_m": 934.5,
    "shape_points": 113
  }
}

400Invalid request