v5.vbb.transport.rest API documentation

v5.vbb.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.vbb.transport.rest/locations?query=alexanderplatz&results=1' -s | jq
[
	{
		"type": "stop",
		"id": "900000100003",
		"name": "S+U Alexanderplatz",
		"location": {
			"type": "location",
			"id": "900100003",
			"latitude": 52.521508,
			"longitude": 13.411267
		},
		"products": {
			"suburban": true,
			"subway": false,
			"tram": false,
			// …
		}
	}
]

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.vbb.transport.rest/stops/nearby?latitude=52.52725&longitude=13.4123' -s | jq
[
	{
		"type": "stop",
		"id": "900000100016",
		"name": "U Rosa-Luxemburg-Platz",
		"location": {
			"type": "location",
			"id": "900100016",
			"latitude": 52.528187,
			"longitude": 13.410405
		},
		"products": { /* … */ },
		"distance": 165
	},
	// …
	{
		"type": "stop",
		"id": "900000110005",
		"name": "U Senefelderplatz",
		"location": { /* … */ },
		"products": { /* … */ },
		"distance": 597
	},
	// …
]

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
suburbanInclude S-Bahn (S)?booleantrue
subwayInclude U-Bahn (U)?booleantrue
tramInclude Tram (T)?booleantrue
busInclude Bus (B)?booleantrue
ferryInclude FΓ€hre (F)?booleantrue
expressInclude IC/ICE (E)?booleantrue
regionalInclude RB/RE (R)?booleantrue
prettyPretty-print JSON responses?booleantrue

Example

curl 'https://v5.vbb.transport.rest/stops/reachable-from?latitude=52.52446&longitude=13.40812&address=10178+Berlin-Mitte,+MΓΌnzstr.+12' -s | jq
[
	{
		"duration": 4,
		"stations": [
			{
				"type": "stop",
				"id": "900000100051",
				"name": "U Weinmeisterstr.",
				"location": { /* … */ },
				"products": { /* … */ },
			}
		]
	},
	// …
	{
		"duration": 7,
		"stations": [
			{
				"type": "stop",
				"id": "900000007110",
				"name": "U Bernauer Str.",
				"location": { /* … */ },
				"products": { /* … */ }
			},
			{
				"type": "stop",
				"id": "900000100004",
				"name": "S+U JannowitzbrΓΌcke",
				"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.vbb.transport.rest/stops/900000017101' -s | jq
{
	"type": "stop",
	"id": "900000017101",
	"name": "U Mehringdamm",
	"location": {
		"type": "location",
		"id": "900017101",
		"latitude": 52.49357,
		"longitude": 13.388138
	},
	"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
suburbanInclude S-Bahn (S)?booleantrue
subwayInclude U-Bahn (U)?booleantrue
tramInclude Tram (T)?booleantrue
busInclude Bus (B)?booleantrue
ferryInclude FΓ€hre (F)?booleantrue
expressInclude IC/ICE (E)?booleantrue
regionalInclude RB/RE (R)?booleantrue
prettyPretty-print JSON responses?booleantrue

Example

# at U Kottbusser Tor, in direction U GΓΆrlitzer Bahnhof
curl 'https://v5.vbb.transport.rest/stops/900000013102/departures?direction=900000014101&duration=10' -s | jq
[
	{
		"tripId": "1|61154|54|86|29042020",
		"direction": "Ersatz S+U Warschauer Str.",
		"line": {
			"type": "line",
			"id": "u1",
			"name": "U1",
			"mode": "bus",
			"product": "bus",
			// …
		},

		"when": "2020-04-29T19:31:00+02:00",
		"plannedWhen": "2020-04-29T19:30:00+02:00",
		"delay": 60,
		"platform": null,
		"plannedPlatform": null,

		"stop": {
			"type": "stop",
			"id": "900000013102",
			"name": "U Kottbusser Tor",
			"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
suburbanInclude S-Bahn (S)?booleantrue
subwayInclude U-Bahn (U)?booleantrue
tramInclude Tram (T)?booleantrue
busInclude Bus (B)?booleantrue
ferryInclude FΓ€hre (F)?booleantrue
expressInclude IC/ICE (E)?booleantrue
regionalInclude RB/RE (R)?booleantrue
prettyPretty-print JSON responses?booleantrue

Example

# at U Kottbusser Tor, 10 minutes
curl 'https://v5.vbb.transport.rest/stops/900000013102/arrivals?duration=10' -s | jq

GET /stations

If the query parameter is used, it will use vbb-stations-autocomplete@4 to autocomplete stops/stations by name. Otherwise, it will filter the stops/stations in vbb-stations@7.

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 vbb-stations-autocomplete@4.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 vbb-stations-autocomplete
curl 'https://v5.vbb.transport.rest/stations?query=mehringd' -s | jq
{
	"type": "station",
	"id": "900000017101",
	"name": "U Mehringdamm (Berlin)",
	"weight": 12994,
	"location": { /* … */ },
	"stops": [
		{
			"type": "stop",
			"id": "070101001002",
			"name": "U Mehringdamm (Berlin)",
			"station": "900000017101",
			"location": { /* … */ },
		},
		// …
	],
	"lines": [
		{
			"type": "line",
			"id": "17521_400",
			"name": "U6",
			"mode": "train",
			"product": "subway",
		},
		// …
	]
}
# filter vbb-stations
curl 'https://v5.vbb.transport.rest/stations?location.latitude=52.493567' -s | jq
{
	"900000017101": {
		"type": "station",
		"id": "900000017101",
		"name": "U Mehringdamm (Berlin)",
		"weight": 12994,
		"location": { /* … */ },
		"stops": [ /* … */ ],
	},
	// …
}
# filter vbb-stations, get newline-delimited JSON
curl 'https://v5.vbb.transport.rest/stations?location.latitude=52.493567' -H 'accept: application/x-ndjson' -s | jq

GET /stations/:id

Returns a stop/station from vbb-stations@7.

Example

# lookup U Mehringdamm
curl 'https://v5.vbb.transport.rest/stations/900000017101' -s | jq
{
	"type": "station",
	"id": "8010159",
	"additionalIds": ["8098159"],
	"ril100": "LH",
	"nr": 2498,
	"name": "Halle (Saale) Hbf",
	"weight": 815.6,
	"location": { /* … */ },
	"operator": { /* … */ },
	"address": { /* … */ },
	"ril100Identifiers": [
		{
			"rilIdentifier": "LH",
			// …
		},
		// …
	],
	// …
}

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
suburbanInclude S-Bahn (S)?booleantrue
subwayInclude U-Bahn (U)?booleantrue
tramInclude Tram (T)?booleantrue
busInclude Bus (B)?booleantrue
ferryInclude FΓ€hre (F)?booleantrue
expressInclude IC/ICE (E)?booleantrue
regionalInclude RB/RE (R)?booleantrue
prettyPretty-print JSON responses?booleantrue

Examples

# stop/station to POI
curl 'https://v5.vbb.transport.rest/journeys?from=900000023201&to.id=900980720&to.name=ATZE+Musiktheater&to.latitude=52.54333&to.longitude=13.35167' -s | jq
# without buses, with ticket info
curl 'https://v5.vbb.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.vbb.transport.rest/journeys?from=…&to=…&results=1' -s | jq '.journeys[0]')
refresh_token=$(echo $journey | jq -r '.refreshToken')

# refresh the journey
curl "https://v5.vbb.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.vbb.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.vbb.transport.rest/trips/$(echo $trip_id | url-encode)" -s | jq

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=52.52411&west=13.41002&south=52.51942&east=13.41709'
curl "https://v5.vbb.transport.rest/radar?$bbox&results=10" -s | jq

GET /lines

Filters the lines in vbb-lines.

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

Query Parameters

parameterdescriptiontypedefault value
idFilter by ID.string–
nameFilter by name.string–
operatorFilter by operator id. See agency.txt.string–
variantsReturn stops/stations along the line?booleantrue
modeFilter by mode of transport as in Friendly Public Transport Format 1.2.1.string–
productFilter by product.string–

Example

curl 'https://v5.vbb.transport.rest/lines?operator=796&variants=false' -s | jq

GET /lines/:id

Returns a line from vbb-lines.

Example

curl 'https://v5.vbb.transport.rest/lines/17442_900' -s | jq

GET /shapes/:id

Output from require('vbb-shapes')(id).

GET /maps/:type

Redirects to PDF public transport maps. type may be one of these:

typeDescription
bvgDay, Berlin ABC, S-Bahn & U-Bahn
bvg-tramDay & Night, Berlin ABC, Trams
bvg-nightNight, Berlin ABC, S-Bahn & U-Bahn
bvg-refugeesDay, Berlin-ABC, S-Bahn & U-Bahn, Translations
vbbDay, Berlin & Brandenburg, RE & RB trains
brbDay, Brandenburg an der Havel
cbDay & Night, Cottbus
cb-nightNight, Cottbus
ffDay, Frankfurt Oder
pDay, Potsdam
p-nightNight, Potsdam

Example

curl -L -o bvg-tram-map.pdf 'https://3.vbb.transport.rest/maps/bvg-tram'

Date/Time Parameters

Possible formats: