Repository navigation
Spec Endpoints Transit and Accessibility
Part of the Technical Specification. Requirement prefixes: FR-TRANSIT, FR-ACCESS. Shared inputs and types: Spec: Resource Model. Scopes: transit, accessibility.
GET /v1/stop-places · operationId searchStopPlaces · MCP counterpart: station lookup within departures
| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
q or near (lat,lon) |
string or point | one of them | Name text, or the stops nearest a point | |
radius_m |
integer | no | 1 000 | With near, up to transit.max_stop_radius_m
|
modes |
list of open enum long_distance_rail, regional_rail, suburban_rail, subway, tram, bus, ferry, other
|
no | all | Served modes |
limit, cursor, fields, lang
|
no | 10 (max 50) |
Item: id (sp_…), name, location, distanceM (with near), modes[], region, globalId (the national stop identifier where published, nullable), sourceFamily.
GET /v1/stop-places/{stopPlaceId}/departures · operationId listDepartures · MCP counterparts: departures, train departures · cache family: departures
| Parameter | Type | Required | Default | Bounds |
|---|---|---|---|---|
from |
instant | no | now | now − transit.max_past_min to now + transit.max_ahead_h
|
duration_min |
integer | no |
transit.default_window_min (design 60) |
1 – transit.max_window_min (design 240) |
modes |
list | no | all | |
line |
string | no | Line name filter | |
limit, cursor, fields, lang
|
no | 30 (max 200) |
{
"data": {
"stopPlace": {"id": "sp_4tQ", "name": "Köln Hbf"},
"departures": [
{
"line": {"name": "RE 1", "mode": "regional_rail", "operator": "Example rail operator"},
"destination": "Aachen Hbf",
"planned": "2026-11-01T13:12:00Z", "plannedLocal": "2026-11-01T14:12:00+01:00",
"expected": "2026-11-01T13:17:00Z", "expectedLocal": "2026-11-01T14:17:00+01:00",
"delayMin": 5,
"platform": {"planned": "4", "expected": "5"},
"status": "delayed",
"realtime": true,
"disruptionIds": ["ds_k1"],
"sourceFamily": "transit.realtime"
}
]
}
}| Field | Meaning |
|---|---|
planned |
Timetabled departure instant |
expected |
Real-time estimate; null when no real-time information exists (realtime: false) |
delayMin |
expected − planned in whole minutes, rounded half away from zero; null without expected
|
status |
open enum scheduled, on_time, delayed, cancelled, extra, unknown
|
platform.expected |
Null when no change is published |
Order: expected (or planned where null) ascending, then planned, then line, then destination. Errors: 404 unknown stop place, 400 window-too-large.
GET /v1/stop-places/{stopPlaceId}/disruptions (operationId listStopDisruptions) and GET /v1/disruptions (near or bbox, operationId listDisruptions) · MCP counterpart: transit disruption check · cache family: departures
Parameters: active_at (instant, default now), modes, severity (open enum info, minor, major, severe), paging.
Item: id (ds_…), headline, description, textLanguage, severity, cause (open enum, nullable), effect (open enum no_service, reduced_service, significant_delays, detour, stop_moved, other), validity (TimeWindow), affected ({"lines": [...], "stopPlaces": [{"id","name"}], "modes": [...]}), updatedAt, sourceFamily. Order: severity descending, then validity.from ascending, then id.
Where a family publishes punctuality figures for a region, GET /v1/disruptions MAY add data.punctuality ({"region", "onTimeSharePct", "periodFrom", "periodUntil"}) as published; the API never computes statistics of its own.
GET /v1/stop-places/{stopPlaceId}/accessibility · operationId getStationAccessibility · MCP counterpart: station facilities check · cache family: accessibility
{
"data": {
"stopPlace": {"id": "sp_4tQ", "name": "Köln Hbf"},
"stepFreeAccess": "partial",
"facilities": [
{
"id": "fc_77a",
"kind": "elevator",
"description": "Platform 4/5 to the main hall",
"state": "inoperative",
"stateSince": "2026-10-31T21:40:00Z", "stateSinceLocal": "2026-10-31T22:40:00+01:00",
"observedAt": "2026-11-01T13:00:00Z", "observedAtLocal": "2026-11-01T14:00:00+01:00",
"expectedBack": null,
"sourceFamily": "accessibility.facilities"
}
]
}
}kind: open enum elevator, escalator, ramp, other. state: operative, inoperative, unknown. stepFreeAccess: yes, partial, no, unknown, derived by a documented domain rule from the facility states and the published step-free routes; it is unknown whenever any input is unknown. Parameters: kind (filter), state (filter), lang.
| ID | Requirement | Verification |
|---|---|---|
| FR-TRANSIT-001 | Stop search MUST accept a name text or a point, and MUST order by relevance or distance, then id. | Handler |
| FR-TRANSIT-002 | Departures MUST carry the planned instant and, where real-time information exists, the expected instant; realtime MUST say which. |
Contract |
| FR-TRANSIT-003 |
delayMin MUST be derived from expected − planned with the documented rounding, never copied from a differently rounded source value. |
Unit |
| FR-TRANSIT-004 | Cancelled departures MUST remain in the list with status: cancelled; they MUST NOT be silently dropped. |
Handler |
| FR-TRANSIT-005 | The departures window MUST be bounded by transit.max_window_min and transit.max_ahead_h. |
Config |
| FR-TRANSIT-006 | Disruptions MUST list affected lines, stop places and modes, and MUST be filterable by active_at. |
Handler |
| FR-TRANSIT-007 | Published punctuality figures MAY be passed on as published, with their period; the service MUST NOT compute or publish its own usage or performance statistics. | Review |
| FR-ACCESS-001 | Every facility MUST carry state, observedAt and, where known, stateSince. |
Contract |
| FR-ACCESS-002 |
stepFreeAccess MUST be unknown whenever any input to the rule is unknown, and the rule MUST be documented and shared with the MCP server. |
Parity |
| FR-ACCESS-003 | A facility whose state is older than the family's stale threshold MUST be reported with stale freshness and the data_stale warning, not as operative. |
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