---
title: "Traffic incidents and closures along a route shape (see module docs)."
method: POST
path: "/v1/incidents/along"
tags: ["routing"]
---

# Traffic incidents and closures along a route shape (see module docs).

`POST /v1/incidents/along`

## Request

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

## Request body

- IncidentsAlongRequest: Request body.
  - `buffer_m` number, double, nullable: Corridor half-width in metres; default 60, clamped to at most 500.
  - `shape` string, required: The route shape as a polyline6 string.

## Response `200`

Incidents along the route (arc-ordered) and every configured source's coverage metadata. Rows from drivers' traffic reports (`source_kind: "driver"`, `source: "mapmap-drivers"`) appear only once two distinct drivers report the same thing nearby in the same direction, only for a route travelling that direction, always with `severity: "other"` and never with a delay; they add `driver_kind`, `reports`, `reported_at` and `expires_at`

- IncidentsAlongResponse: Response body.
  - `attribution` string[]: Attribution notices for the sources actually configured, to display verbatim.
  - `incidents` IncidentAlong[], required: Incidents within the corridor, `arc_m` ascending.
    - `arc_m` number, double, required: Distance along the route shape to the incident's nearest matched point, metres (ascending in the response).
    - `category` string, nullable: What the feed says the incident is (`accident` | `roadworks` | `obstruction` | `congestion` | `closure` | `other`). Present for NTIS events rows only: the closures feed states no record type, and `severity` already says how much of the road it takes.
    - `cause` string, required: Cause, as the feed states it (`causeType` and, when it adds detail, `causeType: detail`) for the closures source; the record's own type (`accident`, `roadworks`, …) for the NTIS events source, which publishes no separate cause. `"unknown"` when neither is stated.
    - `closure_type` string, nullable: The feed's own closure-type value (`laneClosures`, `carriagewayClosures`, `roadClosed`, …), when present.
    - `comment` string, nullable: The feed's free-text public comment, when it carries one.
    - `confidence` number, double, nullable: Camera rows only: the verifier's confidence, `0..=1`.
    - `delay_s` integer, nullable: Delay in seconds **as the source feed reports it**, when it reports one. Never a MapMap estimate and never derived: the engine consumes no live speed data, so this figure is the operator's claim about their own network, passed through unchanged.
    - `driver_kind` string, nullable: Driver rows only: what the drivers answered (`queue` | `accident` | `roadworks` | `breakdown` | `closure`).
    - `evidence_url` string, nullable: Camera rows only: the clip the verdict was made on (the camera provider's own URL; MapMap stores URLs, never pixels).
    - `expires_at` string, nullable: Driver rows only: the most recent report plus its time limit (30 minutes for a queue, 60 otherwise), RFC 3339, to the minute. The latest the row lasts without a new report; it goes sooner when fewer than two drivers' reports remain within their time limit.
    - `from_arc_m` number, double, required: Distance along the route to the nearest of the incident's geometry vertices that fell inside the corridor, equal to `arc_m` for a point incident. For a line, this bounds where the closure enters this route's corridor, not necessarily where the closure itself begins.
    - `id` string, required: The source feed's own record id.
    - `lanes_operational` integer, nullable: Lanes still operational, when the feed states a count.
    - `lanes_restricted` integer, nullable: Lanes restricted, when the feed states a count.
    - `location_name` string, nullable: The matched geometry's own name in the source's network model (e.g. a junction-to-junction link name), when it carries one.
    - `offset_m` number, double, required: Perpendicular distance from the route to the incident's nearest point, metres.
    - `overall_end` string, nullable: Planned/actual end time, RFC 3339, when the feed states one.
    - `overall_start` string, nullable: Planned/actual start time, RFC 3339, when the feed states one.
    - `planned` boolean, required: `true` when the closure's `overallStartTime` is still in the future, an imminent planned closure, not yet active.
    - `probable` boolean, required: `true` when the feed's `probabilityOfOccurrence` is not `certain`.
    - `reported_at` string, nullable: Driver rows only: the most recent report, RFC 3339, to the minute.
    - `reported_severity` string, nullable: The source feed's own severity word, verbatim (NTIS events: `lowest` | `low` | `medium` | `high` | `highest`). Absent when the feed states none, or states `unknown`, never mapped onto [`IncidentSeverity`], which answers a different question.
    - `reports` integer, nullable: Driver rows only: how many distinct drivers reported it (at least two).
    - `road` string, nullable: The first road name the feed's location reference carries. A closure spanning a junction may affect roads not named here.
    - `severity` string, required: Derived severity: `closure` | `lane_restriction` | `other`, see [`IncidentSeverity`].
    - `side` string, required: Which side of the route's local bearing the incident sits on (`left` | `right` | `unknown`); see the module docs on directionality.
    - `situation_id` string, nullable: The feed's situation id, when it has one, several rows (records) can belong to one situation, and this is the key that groups them.
    - `source` string, required: The `sources[].source_id` this record came from.
    - `source_kind` string, required: Which feed family that source is: `closures` | `ntis-events` | `camera`.
    - `status` string, required: `active` or `unknown`, `suspended` records and records whose `overallEndTime` has passed are dropped before matching, never returned as `status`.
    - `to_arc_m` number, double, required: Distance along the route to the farthest matched vertex. May equal `from_arc_m` for a point, or for a line that only clips the corridor briefly.
    - `verifier` string, nullable: Camera rows only: which verifier answered.
  - `sources` IncidentSourceMetaOut[], required: Every configured source's coverage metadata, present even when `incidents` is empty.
    - `coverage_note` string, required
    - `licence` string, required
    - `network` string, required
    - `source_id` string, required

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `429`: Quota or rate limit exceeded
- `501`: Incident data is not enabled (SN_INCIDENTS_DIR unset)

---

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