Skip to content

Spec Endpoints Roads

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Endpoints, Roads

Part of the Technical Specification. Requirement prefix: FR-ROAD. Shared inputs and types: Spec: Resource Model. Scope: roads (history also needs history). Cache family: roads.

1. The road situation

A road situation is anything that affects travel on a road: a closure, roadworks, a jam, a hazard or a restriction.

{
  "id": "rs_Q8mf3",
  "kind": "roadworks",
  "severity": "lane_closed",
  "road": "A8",
  "direction": "west",
  "directionText": "Stuttgart",
  "position": {"fromKm": 112.4, "toKm": 115.0, "junctionFrom": "Ulm-Ost", "junctionTo": "Ulm-West"},
  "location": {"lat": 48.421003, "lon": 9.912775},
  "validity": {
    "from": "2026-11-01T05:00:00Z", "fromLocal": "2026-11-01T06:00:00+01:00",
    "until": "2026-11-14T17:00:00Z", "untilLocal": "2026-11-14T18:00:00+01:00"
  },
  "lanes": {"closed": 1, "total": 3},
  "delayMin": null,
  "lengthM": 2600,
  "headline": "Roadworks, one lane closed",
  "description": "…",
  "textLanguage": "de",
  "updatedAt": "2026-11-01T12:58:00Z",
  "updatedAtLocal": "2026-11-01T13:58:00+01:00",
  "geometry": {"type": "LineString", "coordinates": [[9.93, 48.42], [9.91, 48.42]]},
  "sourceFamily": "roads.federal"
}
Field Type Meaning
kind open enum closure, roadworks, jam, accident, hazard, restriction, weather, other What it is
severity open enum, ordered info < minor < lane_closed < major < road_closed Effect on traffic
direction enum north, east, south, west, both, unknown Affected carriageway
directionText string, nullable The signed destination, as published
position object, nullable for non-motorway roads Chainage in km and junction names
validity TimeWindow Planned or observed validity; until null when open-ended
lanes object, nullable Closed and total lanes where published
delayMin, lengthM integer, nullable Published delay and length
headline, description plain text headline in meta.language where a translation exists, else the original with textLanguage
geometry GeoJSON geometry or absent Governed by geometry= (ENV-012)

2. List motorways

GET /v1/motorways · operationId listMotorways · MCP counterpart: motorway overview

Parameters: state (ISO 3166-2, optional), lamp (filter, optional), limit (default 200, max 500), cursor, lang. Order: road number ascending (A1, A2, … A995), then id.

Item: road, name, lamp, situations ({"total": n, "byKind": {"roadworks": n, …}}), states[] (ISO 3166-2).

3. Motorway conditions

GET /v1/motorways/{road}/conditions · operationId getMotorwayConditions · MCP counterpart: road status

Parameter Type Required Default Meaning
road (path) road reference yes A8
direction enum no both
from, to or from_km, to_km location or km no whole road Section (FR-LOC-004)
kinds list of situation kinds no all
min_severity severity no info
active_at instant no now Situations valid at this instant, within roads.max_lookahead_h
limit, cursor, fields, geometry, lang no 50
{
  "data": {
    "corridor": {"road": "A8", "direction": "west", "fromKm": 0.0, "toKm": 230.0, "fromName": "München", "toName": "Stuttgart"},
    "lamp": "amber",
    "lampReason": "lane_closed",
    "situations": [ { "id": "rs_Q8mf3", "kind": "roadworks", "severity": "lane_closed" } ]
  }
}

Order of situations: position along the direction of travel, then severity descending, then id. Errors: 404 not-found for an unknown road, 422 ambiguous-place / outside-coverage for section ends, 422 invalid-section when from and to do not lie on the road within roads.snap_distance_m.

4. Roadworks ahead

GET /v1/motorways/{road}/roadworks-ahead · operationId getRoadworksAhead · MCP counterpart: roadworks ahead

Parameter Type Required Default Bounds
at lat,lon yes snapped to the road within roads.snap_distance_m
direction enum (not both) yes
within_km integer no roads.ahead_default_km (design 50) 1 – roads.ahead_max_km (design 300)
kinds list no roadworks,closure,restriction

Items are situations with an added distanceAheadKm (one decimal), ordered by it ascending, then id.

5. Conditions in an area

GET /v1/road-conditions · operationId listRoadConditions · MCP counterpart: road status (area form)

Location (at/place/q with radius_m, or bbox), kinds, min_severity, road_class (open enum motorway, federal, state, urban, other, default all), paging. Covers every road class for which data is held. Answer: {"area": {...}, "lamp": "...", "situations": [...]}; order: severity descending, distance ascending, id.

6. Get a situation

GET /v1/road-situations/{situationId} · operationId getRoadSituation. One situation with geometry=simplified by default. A situation that has ended keeps answering 200, with validity.until in the past, for roads.ended_retention_h (design 24 h); after that it answers 404 (not-found). 410 Gone is not used, because the service cannot always tell a retired id from an unknown one.

7. Condition history

GET /v1/motorways/{road}/conditions/history · operationId getMotorwayConditionHistory · API only

Parameter Type Required Bounds
from, to instants (UTC) yes to − from ≤ history.max_window (design 24 h); from not earlier than the plan's history depth; to ≤ now
direction, kinds, section parameters no
limit (default 100, max plan), cursor no

Items are observations: a situation as it was at observedAt, ordered by observedAt ascending, then id. A missing window is 400 window-required; a too large one 400 window-too-large; a window before the plan's depth 403 scope-denied with the depth in detail.

Requirements

ID Requirement Verification
FR-ROAD-001 Road references MUST be normalised per CONV-011; an unknown road MUST be 404 not-found. Unit
FR-ROAD-002 Every situation MUST carry kind, severity, validity, updatedAt and sourceFamily; unmappable codes become other (ENV-051). Mapping
FR-ROAD-003 Motorway conditions MUST order situations by position in the direction of travel; for both, by ascending chainage. Unit
FR-ROAD-004 The corridor lamp MUST be computed by one documented domain rule shared with the MCP server and reported with lampReason. Parity
FR-ROAD-005 Roadworks ahead MUST snap at to the given carriageway, MUST return only situations ahead of that point in the direction of travel within within_km, and MUST report distanceAheadKm. Unit
FR-ROAD-006 Conditions in an area MUST include every road class held, and MUST be filterable by road_class. Handler
FR-ROAD-007 A situation reported by several publishers MUST be returned once, with the attribution of every contributing family. Mapping
FR-ROAD-008 History MUST require a bounded window within history.max_window and the plan's history depth, and MUST read only data inside the window. Load
FR-ROAD-009 History pages MUST be stable: repeating a request with the same cursor returns the same items. Unit
FR-ROAD-010 Situation texts MUST be served in the requested language where a translation exists; otherwise in the original with textLanguage, and the language_fallback warning. Handler
FR-ROAD-011 Section ends MUST be projected to the road within roads.snap_distance_m; ends that do not lie on the road MUST yield 422 invalid-section. Unit

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally