v5.bvg.transport.rest API documentation

v5.bvg.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.

Note: For URL-encoding, this documentation uses the url-encode tool of the url-decode-encode-cli package.

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

Example

curl 'https://v5.bvg.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

Uses vbb-stations-autocomplete to find stops/stations matching query. If you don't pass query, it will just return all stops from vbb-stations.

Query Parameters

parameterdescriptiontypedefault value
queryFilter by name, e.g. mehringd with completion=true, or mehringdamm with completion=false.stringโ€“
resultsHow many stops/stations?number5
fuzzyFind other than exact matches?booleanfalse
completionSearch by prefix?booleantrue

todo

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

Example

curl 'https://v5.bvg.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

Example

curl 'https://v5.bvg.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

Example

curl 'https://v5.bvg.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

Example

# at U Kottbusser Tor, in direction U Gรถrlitzer Bahnhof
curl 'https://v5.bvg.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

Example

# at U Kottbusser Tor, 10 minutes
curl 'https://v5.bvg.transport.rest/stops/900000013102/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
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

Examples

# stop/station to POI
curl 'https://v5.bvg.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.bvg.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
ticketsFetch & parse a shape for each journey leg?booleanfalse
polylinesReturn information about available tickets?booleanfalse
remarksParse & return hints & warnings?booleantrue
languageLanguage of the results.stringen

Example

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

# refresh the journey
curl "https://v5.bvg.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

Example

# get the trip ID of a journey leg
journey=$(curl 'https://v5.bvg.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.bvg.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

Example

bbox='north=52.52411&west=13.41002&south=52.51942&east=13.41709'
curl "https://v5.bvg.transport.rest/radar?$bbox&results=10" -s | jq

Date/Time Parameters

Possible formats: