v5.db.transport.rest API documentation

v5.db.transport.rest is a REST API. Data is being returned as JSON.

You can just use the API without authentication. There's a rate limit of 100 request/minute (burst 200 requests/minute) set up.

OpenAPI playground

Note: The examples snippets in this documentation uses the url-encode CLI tool of the url-decode-encode-cli package for URL-encoding.

Routes

Note: These routes only wrap hafas-client@5 methods, check their docs for more details.

GET /locations

Uses hafasClient.locations() to find stops/stations, POIs and addresses matching query.

Query Parameters

parameterdescriptiontypedefault value
queryRequired.stringโ€“
fuzzyFind more than exact matches?booleantrue
resultsHow many stations shall be shown?integer10
stopsShow stops/stations?booleantrue
addressesShow points of interest?booleantrue
poiShow addresses?booleantrue
linesOfStopsParse & return lines of each stop/station?booleanfalse
languageLanguage of the results.stringen
prettyPretty-print JSON responses?booleantrue

Example

curl 'https://v5.db.transport.rest/locations?query=halle&results=1' -s | jq
[
	{
		"type": "stop",
		"id": "8010159",
		"name": "Halle (Saale) Hbf",
		"location": {
			"type": "location",
			"id": "8010159",
			"latitude": 51.477079,
			"longitude": 11.98699
		},
		"products": {
			"nationalExpress": true,
			"national": true,
			// โ€ฆ
		}
	}
]

GET /stops/nearby

Uses hafasClient.nearby() to find stops/stations close to the given geolocation.

Query Parameters

parameterdescriptiontypedefault value
latitudeRequired.numberโ€“
longitudeRequired.numberโ€“
resultsmaximum number of resultsinteger8
distancemaximum walking distance in metersintegerโ€“
stopsReturn stops/stations?booleantrue
poiReturn points of interest?booleanfalse
linesOfStopsParse & expose lines at each stop/station?booleanfalse
languageLanguage of the results.stringen
prettyPretty-print JSON responses?booleantrue

Example

curl 'https://v5.db.transport.rest/stops/nearby?latitude=53.5711&longitude=10.0015' -s | jq
[
	{
		"type": "stop",
		"id": "694800",
		"name": "BรถttgerstraรŸe, Hamburg",
		"location": {
			"type": "location",
			"id": "694800",
			"latitude": 53.568356,
			"longitude": 9.995528
		},
		"products": { /* โ€ฆ */ },
		"distance": 498,
	},
	// โ€ฆ
	{
		"type": "stop",
		"id": "694802",
		"name": "Bahnhof Dammtor, Hamburg",
		"location": {
			"type": "location",
			"id": "694802",
			"latitude": 53.561048,
			"longitude": 9.990315
		},
		"products": { /* โ€ฆ */ },
		"distance": 1340,
	},
	// โ€ฆ
]

GET /stops/reachable-from

Uses hafasClient.reachableFrom() to find stops/stations reachable within a certain time from an address.

Query Parameters

parameterdescriptiontypedefault value
latitudeRequired.numberโ€“
longitudeRequired.numberโ€“
addressRequired.stringโ€“
whenDate & time to compute the reachability for. See date/time parameters.date+timenow
maxTransfersMaximum number of transfers.integer5
maxDurationMaximum travel duration, in minutes.integerinfinite
languageLanguage of the results.stringen
nationalExpressInclude InterCityExpress (ICE)?booleantrue
nationalInclude InterCity & EuroCity (IC/EC)?booleantrue
regionalExpInclude RegionalExpress & InterRegio (RE/IR)?booleantrue
regionalInclude Regio (RB)?booleantrue
suburbanInclude S-Bahn (S)?booleantrue
busInclude Bus (B)?booleantrue
ferryInclude Ferry (F)?booleantrue
subwayInclude U-Bahn (U)?booleantrue
tramInclude Tram (T)?booleantrue
taxiInclude Group Taxi (Taxi)?booleantrue
prettyPretty-print JSON responses?booleantrue

Example

curl 'https://v5.db.transport.rest/stops/reachable-from?latitude=53.553766&longitude=9.977514&address=Hamburg,+Holstenwall+9' -s | jq
[
	{
		"duration": 1,
		"stations": [
			{
				"type": "stop",
				"id": "694815",
				"name": "Handwerkskammer, Hamburg",
				"location": { /* โ€ฆ */ },
				"products": { /* โ€ฆ */ },
			},
		]
	},
	// โ€ฆ
	{
		"duration": 5,
		"stations": [
			{
				"type": "stop",
				"id": "694807",
				"name": "FeldstraรŸe (U), Hamburg",
				"location": { /* โ€ฆ */ },
				"products": { /* โ€ฆ */ },
				// โ€ฆ
			},
			// โ€ฆ
		]
	},
	// โ€ฆ
]

GET /stops/:id

Uses hafasClient.stop() to find a stop/station by ID.

Query Parameters

parameterdescriptiontypedefault value
linesOfStopsParse & expose lines at each stop/station?booleanfalse
languageLanguage of the results.stringen
prettyPretty-print JSON responses?booleantrue

Example

curl 'https://v5.db.transport.rest/stops/8010159' -s | jq
{
	"type": "stop",
	"id": "8010159",
	"ids": {
		"dhid": "de:15002:8010159",
		"MDV": "8010159",
		"NASA": "8010159"
	},
	"name": "Halle (Saale) Hbf",
	"location": {
		"type": "location",
		"id": "8010159",
		"latitude": 51.477079,
		"longitude": 11.98699
	},
	"products": { /* โ€ฆ */ },
	// โ€ฆ
}

GET /stops/:id/departures

Uses hafasClient.departures() to get departures at a stop/station.

Query Parameters

parameterdescriptiontypedefault value
whenDate & time to get departures for. See date/time parameters.date+timenow
directionFilter departures by direction.stringย 
durationShow departures for how many minutes?integer10
resultsMax. number of departures.integer*whatever HAFAS wants
linesOfStopsParse & return lines of each stop/station?booleanfalse
remarksParse & return hints & warnings?booleantrue
languageLanguage of the results.stringen
nationalExpressInclude InterCityExpress (ICE)?booleantrue
nationalInclude InterCity & EuroCity (IC/EC)?booleantrue
regionalExpInclude RegionalExpress & InterRegio (RE/IR)?booleantrue
regionalInclude Regio (RB)?booleantrue
suburbanInclude S-Bahn (S)?booleantrue
busInclude Bus (B)?booleantrue
ferryInclude Ferry (F)?booleantrue
subwayInclude U-Bahn (U)?booleantrue
tramInclude Tram (T)?booleantrue
taxiInclude Group Taxi (Taxi)?booleantrue
prettyPretty-print JSON responses?booleantrue

Example

# at Halle (Saale) Hbf, in direction Berlin Sรผdkreuz
curl 'https://v5.db.transport.rest/stops/8010159/departures?direction=8011113&duration=120' -s | jq
[
	{
		"tripId": "1|317591|0|80|1052020",
		"direction": "Berlin Hbf (tief)",
		"line": {
			"type": "line",
			"id": "ice-702",
			"name": "ICE 702",
			"mode": "train",
			"product": "nationalExpress",
			// โ€ฆ
		},

		"when": "2020-05-01T21:06:00+02:00",
		"plannedWhen": "2020-05-01T21:06:00+02:00",
		"delay": 0,
		"platform": "8",
		"plannedPlatform": "8",

		"stop": {
			"type": "stop",
			"id": "8010159",
			"name": "Halle (Saale) Hbf",
			"location": { /* โ€ฆ */ },
			"products": { /* โ€ฆ */ },
		},

		"remarks": [],
		// โ€ฆ
	}
]

GET /stops/:id/arrivals

Works like /stops/:id/departures, except that it uses hafasClient.arrivals() to arrivals at a stop/station.

Query Parameters

parameterdescriptiontypedefault value
whenDate & time to get departures for. See date/time parameters.date+timenow
directionFilter departures by direction.stringย 
durationShow departures for how many minutes?integer10
resultsMax. number of departures.integerwhatever HAFAS wants
linesOfStopsParse & return lines of each stop/station?booleanfalse
remarksParse & return hints & warnings?booleantrue
languageLanguage of the results.stringen
nationalExpressInclude InterCityExpress (ICE)?booleantrue
nationalInclude InterCity & EuroCity (IC/EC)?booleantrue
regionalExpInclude RegionalExpress & InterRegio (RE/IR)?booleantrue
regionalInclude Regio (RB)?booleantrue
suburbanInclude S-Bahn (S)?booleantrue
busInclude Bus (B)?booleantrue
ferryInclude Ferry (F)?booleantrue
subwayInclude U-Bahn (U)?booleantrue
tramInclude Tram (T)?booleantrue
taxiInclude Group Taxi (Taxi)?booleantrue
prettyPretty-print JSON responses?booleantrue

Example

# at Halle (Saale) Hbf, 10 minutes
curl 'https://v5.db.transport.rest/stops/8010159/arrivals?duration=10' -s | jq

GET /journeys

Uses hafasClient.journeys() to find journeys from A (from) to B (to).

from (A), to (B), and the optional via must each have one of these formats:

Pagination

Given a response, you can also fetch more journeys matching the same criteria. Instead of from*, to* & departure/arrival, pass earlierRef from the first response as earlierThan to get journeys "before", or laterRef as laterThan to get journeys "after".

Check the hafasClient.journeys() docs for more details.

Query Parameters

parameterdescriptiontypedefault value
departureCompute journeys departing at this date/time. Mutually exclusive with arrival. See date/time parameters.date+timenow
arrivalCompute journeys arriving at this date/time. Mutually exclusive with departure. See date/time parameters.date+timenow
earlierThanCompute journeys "before" an ealierRef.stringย 
laterThanCompute journeys "after" an laterRef.stringย 
resultsMax. number of journeys.integer3
stopoversFetch & parse stopovers on the way?booleanfalse
transfersMaximum number of transfers.integerlet HAFAS decide
transferTimeMinimum time in minutes for a single transfer.integer0
accessibilitypartial or complete.stringnot accessible
bikeCompute only bike-friendly journeys?booleanfalse
startWithWalkingConsider walking to nearby stations at the beginning of a journey?booleantrue
walkingSpeedslow, normal or fast.stringnormal
ticketsReturn information about available tickets?booleanfalse
polylinesFetch & parse a shape for each journey leg?booleanfalse
remarksParse & return hints & warnings?booleantrue
scheduledDaysParse & return dates each journey is valid on?booleanfalse
languageLanguage of the results.stringen
loyaltyCardType of loyalty card in use.stringnone
firstClassSearch for first-class options?booleanfalse
nationalExpressInclude InterCityExpress (ICE)?booleantrue
nationalInclude InterCity & EuroCity (IC/EC)?booleantrue
regionalExpInclude RegionalExpress & InterRegio (RE/IR)?booleantrue
regionalInclude Regio (RB)?booleantrue
suburbanInclude S-Bahn (S)?booleantrue
busInclude Bus (B)?booleantrue
ferryInclude Ferry (F)?booleantrue
subwayInclude U-Bahn (U)?booleantrue
tramInclude Tram (T)?booleantrue
taxiInclude Group Taxi (Taxi)?booleantrue
prettyPretty-print JSON responses?booleantrue

Examples

# stop/station to POI
curl 'https://v5.db.transport.rest/journeys?from=8010159&to.id=991561765&to.latitude=51.483641&to.longitude=11.980841' -s | jq
# without buses, with ticket info
curl 'https://v5.db.transport.rest/journeys?from=โ€ฆ&to=โ€ฆ&bus=false&tickets=true' -s | jq

GET /journeys/:ref

Uses hafasClient.refreshJourney() to "refresh" a journey, using its refreshToken.

The journey will be the same (equal from, to, via, date/time & vehicles used), but you can get up-to-date realtime data, like delays & cancellations.

Query Parameters

parameterdescriptiontypedefault value
stopoversFetch & parse stopovers on the way?booleanfalse
ticketsReturn information about available tickets?booleanfalse
polylinesFetch & parse a shape for each journey leg?booleanfalse
remarksParse & return hints & warnings?booleantrue
languageLanguage of the results.stringen
prettyPretty-print JSON responses?booleantrue

Example

# get the refreshToken of a journey
journey=$(curl 'https://v5.db.transport.rest/journeys?from=โ€ฆ&to=โ€ฆ&results=1' -s | jq '.journeys[0]')
refresh_token=$(echo $journey | jq -r '.refreshToken')

# refresh the journey
curl "https://v5.db.transport.rest/journeys/$(echo $refresh_token | url-encode)" -s | jq

GET /trips/:id

Uses hafasClient.trip() to fetch a trip by ID.

A trip is a specific vehicle, stopping at a series of stops at specific points in time. Departures, arrivals & journey legs reference trips by their ID.

Query Parameters

parameterdescriptiontypedefault value
lineNameRequired. Line name of the part's mode of transport, e.g. RE7.stringโ€“
stopoversFetch & parse stopovers on the way?booleantrue
remarksParse & return hints & warnings?booleantrue
polylineFetch & parse the geographic shape of the trip?booleanfalse
languageLanguage of the results.stringen
prettyPretty-print JSON responses?booleantrue

Example

# get the trip ID of a journey leg
journey=$(curl 'https://v5.db.transport.rest/journeys?from=โ€ฆ&to=โ€ฆ&results=1' -s | jq '.journeys[0]')
journey_leg=$(echo $journey | jq -r '.legs[0]')
trip_id=$(echo $journey_leg | jq -r '.tripId')

# fetch the trip
curl "https://v5.db.transport.rest/trips/$(echo $trip_id | url-encode)" -s | jq

GET /stations

If the query parameter is used, it will use db-stations-autocomplete@2 to autocomplete Deutsche Bahn-operated stops/stations. Otherwise, it will filter the stops/stations in db-stations@3.

Instead of receiving a JSON response, you can request newline-delimited JSON by sending Accept: application/x-ndjson.

Query Parameters

parameterdescriptiontypedefault value
queryFind stations by name using db-stations-autocomplete@2.stringโ€“
limitIf query is used: Return at most n stations.number3
fuzzyIf query is used: Find stations despite typos.booleanfalse
completionIf query is used: Autocomplete stations.booleantrue

Examples

# autocomplete using db-stations-autocomplete
curl 'https://v5.db.transport.rest/stations?query=dammt' -s | jq
{
	"8002548": {
		"id": "8002548",
		"relevance": 0.8572361756428573,
		"score": 9.175313823998414,
		"weight": 1212,
		"type": "station",
		"ril100": "ADF",
		"name": "Hamburg Dammtor",
		"location": {
			"type": "location",
			"latitude": 53.560751,
			"longitude": 9.989566
		},
		"operator": {
			"type": "operator",
			"id": "hamburger-verkehrsverbund-gmbh",
			"name": "BWVI"
		},
		"address": {
			"city": "Hamburg",
			"zipcode": "20354",
			"street": "Dag-Hammarskjรถld-Platz 15"
		},
		// โ€ฆ
	},
	// โ€ฆ
}
# filter db-stations by `hasParking` property
curl 'https://v5.db.transport.rest/stations?hasParking=true' -s | jq
{
	"8000001": {
		"type": "station",
		"id": "8000001",
		"ril100": "KA",
		"name": "Aachen Hbf",
		"weight": 653.75,
		"location": { /* โ€ฆ */ },
		"operator": { /* โ€ฆ */ },
		"address": { /* โ€ฆ */ },
		// โ€ฆ
	},
	// โ€ฆ
}
# filter db-stations by `hasDBLounge` property, get newline-delimited JSON
curl 'https://v5.db.transport.rest/stations?hasDBLounge=true' -H 'accept: application/x-ndjson' -s | jq

GET /stations/:id

Returns a stop/station from db-stations.

Query Parameters

Example

# lookup Halle (Saale) Hbf
curl 'https://v5.db.transport.rest/stations/8010159' -s | jq
curl 'https://v5.db.transport.rest/stations/LH' -s | jq # RIL100/DS100
curl 'https://v5.db.transport.rest/stations/LHG' -s | jq # RIL100/DS100
{
	"type": "station",
	"id": "8010159",
	"additionalIds": ["8098159"],
	"ril100": "LH",
	"nr": 2498,
	"name": "Halle (Saale) Hbf",
	"weight": 815.6,
	"location": { /* โ€ฆ */ },
	"operator": { /* โ€ฆ */ },
	"address": { /* โ€ฆ */ },
	"ril100Identifiers": [
		{
			"rilIdentifier": "LH",
			// โ€ฆ
		},
		// โ€ฆ
	],
	// โ€ฆ
}

GET /radar

Uses hafasClient.radar() to find all vehicles currently in an area, as well as their movements.

Query Parameters

parameterdescriptiontypedefault value
northRequired. Northern latitude.numberโ€“
westRequired. Western longitude.numberโ€“
southRequired. Southern latitude.numberโ€“
eastRequired. Eastern longitude.numberโ€“
resultsMax. number of vehicles.integer256
durationCompute frames for the next n seconds.integer30
framesNumber of frames to compute.integer3
polylinesFetch & parse a geographic shape for the movement of each vehicle?booleantrue
languageLanguage of the results.stringen
prettyPretty-print JSON responses?booleantrue

Example

bbox='north=53.555&west=9.989&south=53.55&east=10.001'
curl "https://v5.db.transport.rest/radar?$bbox&results=10" -s | jq

Date/Time Parameters

Possible formats: