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

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

`POST /v1/route/heritage`

## Request

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

## Request body

- HeritageBody: Request body for `POST /v1/route/heritage`. `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 it had been honoured.
  - `duration_s` number, double, nullable: The route's own duration in seconds, typically `duration_s` from the same response. Supply it: without it the silence budget falls back to a distance, and "three to five lines an hour" is a claim about time that a distance answers wrongly at both ends.
  - `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_lines` integer, nullable: Ceiling on how many lines come back (1 to 50, default 12).
  - `max_offset_m` number, double, nullable: How near a plaque's own recorded coordinate must come to the route before its line may be spoken, metres (default 60, hard ceiling 80). Past about eighty metres the subject stops being something the driver is passing, so the ceiling cannot be lifted from a request body.
  - `min_gap_m` number, double, nullable: Least distance between two spoken lines, metres (default 400). A floor under the time budget in every case, and the whole budget when no duration is supplied.
  - `min_gap_s` number, double, nullable: Least time between two spoken lines, seconds (default 900, which is four an hour). Applied only when `duration_s` is given.
  - `voice_format` string, nullable: Container to give each line's audio clip address in: `opus` (Android) or `m4a` (iOS). Given, every line gains a `clip` with the synthesis cache key and the URL to fetch it from. Omitted, no clip is computed and the answer is text only.

## Response `200`

Lines in route order, each with `at_m`, the `say` sentence, the measured `offset_m` from the plaque's own coordinate to the route, the `plaque_ids` the claim rests on, and (when `voice_format` was given) the `clip` that speaks it; plus a `census` of what was not said, the `attribution` the source dataset is owed, and the standing `caveat`

- object

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `429`: Quota or rate limit exceeded
- `501`: `voice_format` was asked for on a deployment with no voice service configured (`urn:sn-gateway:problem:voice-not-enabled`)

---

[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)