Skip to content

Spec Endpoints Transit and Accessibility

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Endpoints, Public Transport and Accessibility

Part of the Technical Specification. Requirement prefixes: FR-TRANSIT, FR-ACCESS. Shared inputs and types: Spec: Resource Model. Scopes: transit, accessibility.

1. Search stop places

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.

2. Departures

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.

3. Disruptions

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.

4. Station accessibility

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.

Requirements

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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally