---
title: "`POST /v1/route/observations` (see module docs)."
method: POST
path: "/v1/route/observations"
tags: ["routing"]
---

# \`POST /v1/route/observations\` (see module docs).

`POST /v1/route/observations`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/v1/route/observations`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

## Request body

- ObservationsBody: Request body for `POST /v1/route/observations`. `deny_unknown_fields` on purpose. A caller who sent `"costing": "truck"` asked for something this endpoint does not do, and silently ignoring it would let them believe a truck-aware answer came back.
  - `geometry_polyline6` string, required: The route shape as a Google encoded polyline, six-digit precision, typically `geometry_polyline6` straight out of a prior `/route` response.
  - `max_observations` integer, nullable: Ceiling on how many observations come back (1 to 200, default 40).
  - `min_gap_m` number, double, nullable: 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, nullable: 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.

## Response `200`

Observations 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`

- object

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `429`: Quota or rate limit exceeded
- `501`: This 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
- `503`: The 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

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)