Repository navigation
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.
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) |
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).
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.
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.
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.
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.
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.
| 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 |
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference