Repository navigation
Data Model Roads
Part of the Data Model. A logical model for the API's read side, not a copy of any physical schema; storage names may differ. Conventions, the record envelope and retention classes: Data Model section 5. API side: Endpoints, Roads.
The domain holds the road network the API can speak about (roads and their junctions) and the traffic events on it: closures, roadworks, jams, accidents, hazards, restrictions and weather effects. The API calls a traffic event, as served, a road situation.
erDiagram
road ||--o{ junction : "has"
road |o--o{ traffic_event : "carries"
junction |o--o{ traffic_event : "bounds"
traffic_event ||--o{ event_extent : "spans"
traffic_event ||--o{ traffic_event_observation : "was observed as"
traffic_event |o--o{ traffic_event : "duplicates"
source ||--o{ traffic_event : "describes"
road {
string road_ref PK
string road_class
string name
decimal length_km
line geometry
}
junction {
string junction_id PK
string road_ref FK
string number
string name
string junction_kind
decimal chainage_km
point location
}
traffic_event {
string event_id PK
string event_kind
string severity
string road_ref FK
string road_class
string direction
string direction_label
decimal from_km
decimal to_km
string from_junction_id FK
string to_junction_id FK
point location
geometry shape
instant valid_from
instant valid_to
int lanes_closed
int lanes_total
int delay_min
int affected_length_m
string headline
string description
string text_lang
string primary_event_id FK
string source_ref FK
}
event_extent {
string event_id FK
int position
string road_ref FK
decimal from_km
decimal to_km
geometry shape
}
traffic_event_observation {
string event_id FK
instant observed_at
int version_no
string event_kind
string severity
instant valid_from
instant valid_to
int lanes_closed
int delay_min
}
A road the API can name, keyed by its official designation. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
road_ref |
key |
yes | upper case, no space (A8, B27) |
CONV-011 | Identity and designation | road |
road_class |
enum<road_class> |
yes |
motorway, federal, state, urban, other
|
Class of the road |
road_class filter |
|
name |
ltext |
no | A descriptive name, for example the end points | name |
||
length_km |
decimal(6,1) |
no | km | > 0 | Signed length |
toKm of the whole road |
geometry |
line |
no | WGS 84 | Centre line, both directions | corridor building | |
states |
list<key> |
yes | ISO 3166-2 | States the road crosses | states[] |
A numbered or named point on a road: an exit, an interchange, a motorway triangle or a service area. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
junction_id |
id |
yes | Identity |
nearestJunction.id (jn_…) |
||
road_ref |
key → road
|
yes | The road it lies on | nearestJunction.road |
||
number |
text |
no | as signed (61, 12a) |
Junction number | nearestJunction.number |
|
name |
text |
yes | Junction name as signed |
nearestJunction.name, position.junctionFrom/junctionTo
|
||
junction_kind |
enum<junction_kind> |
yes |
exit, interchange, triangle, service_area, other
|
What it is | none in v1 | |
chainage_km |
decimal(6,1) |
no | km | 0 … road.length_km
|
Position along the road | snapping of from/to
|
location |
point |
yes | WGS 84 | Position | nearestJunction.distanceM |
One situation as its source publishes it, in its current version. Retention: the current version is an event record; each version is also an observation in traffic_event_observation (OBS); an ended event stays readable for the grace period (TRN).
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
event_id |
id |
yes | Identity |
id (rs_…) |
||
event_kind |
enum<event_kind> |
yes | see dictionary | What it is | kind |
|
severity |
enum<severity> |
yes | ordered info < minor < lane_closed < major < road_closed
|
Effect on traffic, by a documented mapping from the published facts |
severity, lampReason
|
|
road_ref |
key → road
|
no | null off the held network | Affected road | road |
|
road_class |
enum<road_class> |
yes | Class of the affected road |
road_class filter |
||
direction |
enum<direction> |
yes |
north, east, south, west, both, unknown
|
Affected carriageway | direction |
|
direction_label |
text |
no | Signed destination of the carriageway, as published | directionText |
||
from_km, to_km
|
decimal(6,1) |
no | km |
from_km ≤ to_km after orientation |
Chainage of the primary stretch |
position.fromKm, position.toKm
|
from_junction_id, to_junction_id
|
id → junction
|
no | Junctions that bound the stretch |
position.junctionFrom, position.junctionTo
|
||
location |
point |
no | WGS 84 | null when the source gives no position and none can be derived | Representative point |
location, distance ordering |
shape |
geometry |
no | WGS 84 | Line or point geometry of the primary stretch | geometry |
|
valid_from |
instant |
yes | UTC | Start of validity, planned or observed | validity.from |
|
valid_to |
instant |
no | UTC | > valid_from; null = open-ended |
End of validity | validity.until |
lanes_closed |
int |
no | ≥ 0 | Lanes closed, where published | lanes.closed |
|
lanes_total |
int |
no | ≥ lanes_closed
|
Lanes in that direction, where published | lanes.total |
|
delay_min |
int |
no | min | ≥ 0 | Published delay | delayMin |
affected_length_m |
int |
no | m | ≥ 0 | Published length of the affected stretch | lengthM |
headline |
ltext |
yes | plain text | Short title | headline |
|
description |
ltext |
no | plain text | Longer text | description |
|
text_lang |
text |
yes | BCP 47 | Language of the original text | textLanguage |
|
primary_event_id |
id → traffic_event
|
no | not self | Set when this record describes the same real-world situation as another source's record; the primary is served, the duplicates add their attribution (FR-ROAD-007) | meta.attribution[] |
|
| envelope |
changed_at is the last content change |
updatedAt, sourceFamily
|
Further stretches of one event that affects more than one place, for example roadworks with several lane closures. Position 0 is the primary stretch held on the event itself. Retention follows the event.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
event_id |
id → traffic_event
|
yes | Owning event | none | ||
position |
int |
yes | ≥ 1, unique per event | Order of the stretch | none | |
road_ref |
key → road
|
no | Road of this stretch | corridor matching | ||
from_km, to_km
|
decimal(6,1) |
no | km | Chainage | corridor matching | |
shape |
geometry |
no | WGS 84 | Geometry |
geometry (full) |
One version of an event as it was at observed_at. A new observation is added whenever the event's content changes; none is ever updated. Retention OBS.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
event_id |
id → traffic_event
|
yes | The event | history item id
|
||
observed_at |
instant |
yes | UTC | When this version was current | observedAt |
|
version_no |
int |
yes | ≥ 1, increasing per event | Version counter | none | |
event_kind, severity, direction, from_km, to_km, valid_from, valid_to, lanes_closed, lanes_total, delay_min, affected_length_m, headline, description, text_lang, location
|
as on traffic_event
|
as there | The event's fields as of this version | history item fields |
| Relationship | Cardinality | Rule |
|---|---|---|
road → junction
|
one to many | A junction lies on exactly one road; an interchange of two roads is one junction per road |
traffic_event → road
|
many to zero-or-one | Null for events off the held network or without a road reference |
traffic_event → junction (from, to) |
many to zero-or-one each | Bounding junctions where known |
traffic_event → event_extent
|
one to many | Extra stretches only |
traffic_event → traffic_event_observation
|
one to many | At least one per event |
traffic_event → primary traffic_event
|
many to zero-or-one | Duplicate folding across sources; a primary is never itself a duplicate |
Natural key: origin_key within source_ref, the publisher's own situation identifier.
-
Active at instant t:
valid_from≤ t and (valid_tois null or t <valid_to) and not withdrawn. "Active within the look-ahead" widens t to a window bounded byroads.max_lookahead_h. -
Ended events (past
valid_to, or withdrawn by their source) stay readable by id forroads.ended_retention_h(classTRN), then leave the read side. -
History is read from
traffic_event_observationonly, inside a window bounded byhistory.max_windowand the plan's history depth (classOBS, horizon configurable).
| Path | Used by |
|---|---|
By road_ref and direction, active events, ordered by chainage in the direction of travel |
motorway conditions, list motorways |
Along a corridor: road_ref plus chainage range over the event and its extents; or a buffered route line tested against each event's box |
conditions along a section, route briefing |
Ahead of a point: snap the point to the carriageway, then chainage greater (or smaller, by direction) up to within_km
|
roadworks ahead |
Within an area: spatial test on location or shape, by road_class
|
conditions in an area |
By key on event_id
|
get a situation |
By time window on traffic_event_observation.observed_at for one road |
condition history |
Nearest junction to a point |
describe a point, section snapping |
Each event names its source. When several sources describe one situation, the primary record is served once and meta.attribution[] carries every contributing source (FR-ROAD-007). Event texts are kept in the original language; translations are text_variant rows (Provenance).
| Entity | Operations | Resource members |
|---|---|---|
road |
GET /v1/motorways, path {road} everywhere |
motorway item, corridor
|
junction |
conditions, describe a point |
position.junctionFrom/To, nearestJunction, corridor.fromName/toName
|
traffic_event, event_extent
|
conditions, roadworks ahead, conditions in an area, get a situation, route briefing, place overview | road situation |
traffic_event_observation |
GET /v1/motorways/{road}/conditions/history |
history item |
The corridor lamp is not stored: it is a domain rule over the active events (FR-ROAD-004). Field-level mapping: Mapping.
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