Repository navigation
Data Model Transit
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, Public Transport and Accessibility.
The domain holds public transport: stop places and their platforms, lines and their operators, the timetable as journeys with scheduled calls, live call observations (expected times, platform changes, cancellations), service alerts and published punctuality figures. A departure in the API is a scheduled call joined with its newest call observation.
erDiagram
stop_place |o--o{ stop_place : "contains"
stop_place ||--o{ stop_point : "contains"
transit_operator ||--o{ transit_line : "operates"
transit_line ||--o{ journey : "runs"
journey ||--|{ scheduled_call : "calls at"
stop_point ||--o{ scheduled_call : "is served by"
scheduled_call ||--o{ call_observation : "is updated by"
service_alert ||--|{ alert_scope : "affects"
transit_line |o--o{ alert_scope : "is named in"
stop_place |o--o{ alert_scope : "is named in"
admin_region ||--o{ punctuality_figure : "is measured by"
source ||--o{ stop_place : "describes"
source ||--o{ journey : "describes"
source ||--o{ call_observation : "describes"
source ||--o{ service_alert : "describes"
stop_place {
string stop_place_id PK
string name
point location
string national_stop_code
string parent_id FK
string region_code FK
string source_ref FK
}
stop_point {
string stop_point_id PK
string stop_place_id FK
string platform_label
point location
}
transit_operator {
string operator_id PK
string name
}
transit_line {
string line_id PK
string operator_id FK
string line_name
string transport_mode
}
journey {
string journey_id PK
string line_id FK
date service_date
string destination_label
string source_ref FK
}
scheduled_call {
string journey_id FK
int call_order
string stop_point_id FK
instant planned_arrival_at
instant planned_departure_at
string planned_platform
}
call_observation {
string journey_id FK
int call_order
instant observed_at
instant expected_arrival_at
instant expected_departure_at
string expected_platform
string call_status
string source_ref FK
}
service_alert {
string alert_id PK
string alert_severity
string cause
string effect
instant valid_from
instant valid_to
string headline
string description
string text_lang
string source_ref FK
}
alert_scope {
string alert_id FK
string scope_kind
string line_id FK
string stop_place_id FK
string transport_mode
}
punctuality_figure {
string region_code FK
instant period_from
instant period_to
decimal on_time_share_pct
string source_ref FK
}
A station or stop as a traveller names it ("Köln Hbf"). Stop places can nest (a large station and its bus terminal). Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
stop_place_id |
id |
yes | Identity |
id (sp_…), stopPlace.id
|
||
name |
text |
yes | Name as published |
name, stopPlace.name
|
||
location |
point |
yes | WGS 84 | Representative point |
location, distanceM
|
|
national_stop_code |
key |
no | the national stop identifier format | The national identifier, where published | globalId |
|
parent_id |
id → stop_place
|
no | not self | Enclosing stop place | none; search returns the outermost | |
region_code |
key → admin_region
|
no | Enclosing region | region |
||
modes |
list<enum<transport_mode>> |
yes | may be empty | Modes served, derived from the lines calling |
modes[], modes filter |
|
search_fold |
text |
yes | folded | Name search key | none (storage-only) | |
| envelope | sourceFamily |
A platform, track or bay inside a stop place, where vehicles actually call. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
stop_point_id |
id |
yes | Identity | none | ||
stop_place_id |
id → stop_place
|
yes | Owning stop place | departures grouping | ||
platform_label |
text |
no | as signed | Platform or track |
platform.planned fallback |
|
location |
point |
no | WGS 84 | Position | none |
A transport operator. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
operator_id |
id |
yes | Identity | none | ||
name |
text |
yes | Name as published | line.operator |
A line as passengers know it ("RE 1", "U3", "Bus 132"). Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
line_id |
id |
yes | Identity | none | ||
operator_id |
id → transit_operator
|
no | Operator | line.operator |
||
line_name |
text |
yes | Public name |
line.name, line filter, affected.lines[]
|
||
transport_mode |
enum<transport_mode> |
yes | see dictionary | Mode |
line.mode, modes filter |
One run of a line on one service day. Retention OBS for past service days, REF for the current timetable window.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
journey_id |
id |
yes | Identity | none | ||
line_id |
id → transit_line
|
yes | Line | line |
||
service_date |
date |
yes | Europe/Berlin | Operating day; calls may fall after midnight of it | none | |
destination_label |
text |
no | Headsign | destination |
||
extra |
bool |
yes | True for a run not in the published timetable | status: extra |
||
| envelope | sourceFamily |
One planned stop of a journey. Retention follows the journey.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
journey_id |
id → journey
|
yes | The journey | none | ||
call_order |
int |
yes | ≥ 0, increasing along the journey | Position in the journey | ordering | |
stop_point_id |
id → stop_point
|
yes | Where it calls | stopPlace |
||
planned_arrival_at |
instant |
no | UTC | null at the first call | Planned arrival | none in v1 |
planned_departure_at |
instant |
no | UTC | null at the last call | Planned departure | planned |
planned_platform |
text |
no | Planned platform | platform.planned |
One live update of one call. Retention OBS. The current state of a call is its newest observation; a call without one has no real-time information (realtime: false).
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
journey_id, call_order
|
→ scheduled_call
|
yes | The call | none | ||
observed_at |
instant |
yes | UTC | When the update was published or observed | freshness | |
expected_arrival_at |
instant |
no | UTC | Expected arrival | none in v1 | |
expected_departure_at |
instant |
no | UTC | Expected departure |
expected, input of delayMin
|
|
expected_platform |
text |
no | null when unchanged | Changed platform | platform.expected |
|
call_status |
enum<call_status> |
yes |
scheduled, cancelled, extra, unknown
|
Published status of the call |
status (with the domain rule for on_time and delayed) |
|
source_ref |
key → source
|
yes | Source of the update | sourceFamily |
delayMin is not stored: it is expected − planned in whole minutes by the documented rounding (FR-TRANSIT-003). on_time and delayed are derived from it by a documented threshold.
A published disruption notice. Retention: event record; versions kept as observations (OBS); ended alerts leave the read side after a configurable grace period (TRN).
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
alert_id |
id |
yes | Identity |
id (ds_…), disruptionIds[]
|
||
alert_severity |
enum<alert_severity> |
yes |
info, minor, major, severe
|
Severity |
severity, severity filter |
|
cause |
enum<alert_cause> |
no | see dictionary | Cause | cause |
|
effect |
enum<alert_effect> |
yes |
no_service, reduced_service, significant_delays, detour, stop_moved, other
|
Effect | effect |
|
valid_from |
instant |
yes | UTC | Start of validity |
validity.from, active_at filter |
|
valid_to |
instant |
no | UTC | null = open-ended | End of validity | validity.until |
headline |
ltext |
yes | plain text | Title | headline |
|
description |
ltext |
no | plain text | Text | description |
|
text_lang |
text |
yes | BCP 47 | Original language | textLanguage |
|
| envelope |
updatedAt, sourceFamily
|
What an alert affects: a line, a stop place, a mode or a region. Retention follows the alert.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
alert_id |
id → service_alert
|
yes | The alert | none | ||
scope_kind |
enum<scope_kind> |
yes |
line, stop_place, mode, region
|
What the row names | which list it fills | |
line_id |
id → transit_line
|
no | set when scope_kind = line
|
Affected line | affected.lines[] |
|
stop_place_id |
id → stop_place
|
no | set when scope_kind = stop_place
|
Affected stop place |
affected.stopPlaces[], stop disruptions |
|
transport_mode |
enum<transport_mode> |
no | set when scope_kind = mode
|
Affected mode | affected.modes[] |
|
region_code |
key → admin_region
|
no | set when scope_kind = region
|
Affected region | area disruptions |
A punctuality figure as a publisher states it for a region and a period. The API passes it on and computes none of its own (FR-TRANSIT-007). Retention OBS.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
region_code |
key → admin_region
|
yes | Region | punctuality.region |
||
period_from, period_to
|
instant |
yes | UTC |
period_from < period_to
|
Period |
punctuality.periodFrom, periodUntil
|
on_time_share_pct |
decimal(5,2) |
yes | % | 0 to 100 | Share on time, as published | punctuality.onTimeSharePct |
source_ref |
key → source
|
yes | Publisher's source | sourceFamily |
| Relationship | Cardinality | Rule |
|---|---|---|
stop_place → parent |
many to zero-or-one | One level of nesting is typical |
stop_place → stop_point
|
one to many | |
transit_line → journey → scheduled_call
|
one to many, one to one-or-more | A journey has at least two calls |
scheduled_call → call_observation
|
one to many | Keyed by journey_id and call_order
|
service_alert → alert_scope
|
one to one-or-more |
Timetable and live updates of one region share one natural key space within their source; a live update is matched to its scheduled call by the publisher's journey key and call order within that source.
- Network entities are
REF. The timetable is held for a window around now; past service days fall toOBS. - A planned call time may lie after midnight of its service date; instants are stored, so no time-of-day arithmetic leaks to the API.
- Cancelled calls stay with
call_status = cancelled(FR-TRANSIT-004).
| Path | Used by |
|---|---|
| Text search on the stop place's fold, or nearest stop places to a point | search stop places |
| Calls of all stop points of a stop place inside a bounded time window, ordered by expected or planned time, with the newest observation each | departures |
Active alerts by stop_place_id through alert_scope, or by area |
disruptions |
| Newest figure per region | data.punctuality |
Timetable, live updates and alerts may come from different sources; each record names its own. Share-alike transit records carry the share-alike flag and offer.
| Entity | Operations | Resource members |
|---|---|---|
stop_place, stop_point
|
GET /v1/stop-places, path {stopPlaceId}
|
stop place item, stopPlace
|
transit_line, transit_operator, journey, scheduled_call, call_observation
|
GET /v1/stop-places/{stopPlaceId}/departures |
departure item |
service_alert, alert_scope
|
GET /v1/stop-places/{stopPlaceId}/disruptions, GET /v1/disruptions
|
disruption item |
punctuality_figure |
GET /v1/disruptions |
data.punctuality |
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