API Reference

Community Server API

The openpublictransport provider is powered by a community-hosted OpenTripPlanner 2 instance with Germany-wide GTFS data from gtfs.de.

Scheduled Maintenance — Every Sunday ~2:00 AM (Europe/Berlin)

The API is offline for approximately 80 minutes while the routing graph is rebuilt with fresh GTFS data. If your automations run on Sunday mornings, schedule them after 4:00 AM.

Endpoint

GraphQL https://api.openpublictransport.net/otp/gtfs/v1
Auth X-API-Key: <your-key>
Method POST (JSON body: {"query": "..."})
Engine OpenTripPlanner 2.9.0
Timezone Europe/Berlin
API Key Required — request a free key →

Data Freshness

The server combines a weekly-rebuilt static GTFS graph with continuously polled realtime data.

Data Type Update Frequency Source
Static timetables Weekly (Sunday ~2:00 AM) gtfs.de Germany Full (CC 4.0)
Realtime delays & cancellations Every 30 seconds realtime.gtfs.de GTFS-RT
Service alerts Every 30 seconds realtime.gtfs.de
Graph validity window ~4 months per build 1 month back + 3 months forward

Maintenance Schedule

Every week the server stops serving, rebuilds the routing graph with fresh GTFS data, then resumes.

Schedule Every Sunday, ~2:00 AM Europe/Berlin
Total downtime ~80 minutes (graph build ~57 min + loading ~20 min)
Expected back ~3:30 AM at the latest
Impact API returns connection errors; realtime updates paused
After rebuild Fresh GTFS data; realtime polling resumes within seconds

Example Queries

All queries use GraphQL POST to the endpoint above with X-API-Key header.

Search for a stop by name

{
  stops(name: "München Hbf") {
    gtfsId
    name
    lat
    lon
    parentStation { gtfsId name }
  }
}

Departures at a specific stop

{
  stop(id: "gtfsde:xxxxxxx") {
    name
    stoptimesWithoutPatterns(numberOfDepartures: 10) {
      scheduledDeparture
      realtimeDeparture
      departureDelay
      realtime
      trip {
        route { shortName longName mode }
        tripHeadsign
      }
    }
  }
}

Trip planning (A → B)

{
  plan(
    from: { lat: 48.1374, lon: 11.5755 }
    to:   { lat: 52.5200, lon: 13.4050 }
    numItineraries: 3
  ) {
    itineraries {
      duration
      legs {
        mode
        startTime
        endTime
        from { name }
        to   { name }
        trip { route { shortName } }
      }
    }
  }
}

Check graph validity range

Returns Unix timestamps — useful to verify the current graph covers your target date.

{
  serviceTimeRange {
    start
    end
  }
}

Realtime Coverage

Realtime data comes from realtime.gtfs.de, an aggregated GTFS-RT feed combining regional providers. Coverage varies by operator.

Verbund / Provider Region
VBB Berlin & Brandenburg
VRR Rhein-Ruhr (NRW)
VRS Rhein-Sieg (Köln/Bonn)
VRN / RNN Rhein-Neckar
VVO Dresden & Chemnitz (Oberelbe)
VBN Bremen, Niedersachsen, Schleswig-Holstein
NVBW Baden-Württemberg
DEFAS Bayern Bavaria (incl. MVV, S-Bahn München)
VAG Nürnberg Nürnberg city
Stadtwerke Münster Münster city
opentransportdata.swiss Baden-Württemberg / Swiss border
OVapi Netherlands / German border
DELFI SIRI feeds Various states

Error Reference

Code Meaning
401 Invalid or missing API key — check the X-API-Key header
503 / timeout Maintenance window active (Sunday ~2:00–3:30 AM) or graph is loading after restart (~20 min)
200 + errors[] GraphQL validation error — check field names and query structure against the schema

Self-Hosting

Run your own OTP2 instance with the same gtfs.de data. The Docker image handles GTFS download, OSM filtering, graph build, and serving automatically.

NerdySoftPaw/otp-gtfsde on GitHub