v5.hvv.transport.rest API documentation

v5.hvv.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.hvv.transport.rest/locations?query=dammtor&results=1' -s | jq
[
	{
		"type": "stop",
		"id": "163",
		"name": "Dammtor (Messe/CCH)",
		"location": {
			"type": "location",
			"latitude": 53.560949,
			"longitude": 9.989721
		},
		"products": {
			"subway": false,
			"suburban": true,
			"akn": 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.hvv.transport.rest/stops/nearby?latitude=53.5711&longitude=10.0015' -s | jq
[
	{
		"type": "stop",
		"id": "118",
		"name": "Böttgerstraße",
		"location": {
			"type": "location",
			"latitude": 53.568356,
			"longitude": 9.995528
		},
		"products": { /* … */ },
		"distance": 498
	},
	// …
	{
		"type": "stop",
		"id": "4673",
		"name": "Gertigstraße",
		"location": { /* … */ },
		"products": { /* … */ },
		"distance": 1305
	},
	// …
]

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
subwayInclude U-Bahn (U)?booleantrue
suburbanInclude S-Bahn (S)?booleantrue
aknInclude AKN (A)?booleantrue
regional-express-trainInclude RegionalExpress (RE)?booleantrue
regional-trainInclude Regionalbahn (RB)?booleantrue
ferryInclude Fähre (F)?booleantrue
busInclude Bus?booleantrue
express-busInclude Schnellbus?booleantrue
anruf-sammel-taxiInclude Anruf-Sammel-Taxi (AST)?booleantrue
long-distance-trainInclude Fernzug (ICE/IC/EC/EN)?booleanfalse
long-distance-busInclude Fernbus?booleanfalse
prettyPretty-print JSON responses?booleantrue

Example

curl 'https://v5.hvv.transport.rest/stops/reachable-from?latitude=53.553766&longitude=9.977514&address=Hamburg,+Holstenwall+9' -s | jq
[
	{
		"duration": 1,
		"stations": [
			{
				"type": "stop",
				"id": "102",
				"name": "Handwerkskammer",
				"location": { /* … */ },
				"products": { /* … */ },
			},
			// …
		]
	},
	// …
	{
		"duration": 5,
		"stations": [
			{
				"type": "stop",
				"id": "108",
				"name": "Sievekingplatz",
				"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.hvv.transport.rest/stops/163' -s | jq
{
	"type": "stop",
	"id": "163",
	"name": "Dammtor (Messe/CCH)",
	"location": {
		"type": "location",
		"id": "163",
		"latitude": 53.560949,
		"longitude": 9.989721
	},
	"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
includeRelatedStationsFetch departures at related stops, e.g. those that belong together on the metro map?booleantrue
stopoversFetch & parse next stopovers of each departure?booleanfalse
subwayInclude U-Bahn (U)?booleantrue
suburbanInclude S-Bahn (S)?booleantrue
aknInclude AKN (A)?booleantrue
regional-express-trainInclude RegionalExpress (RE)?booleantrue
regional-trainInclude Regionalbahn (RB)?booleantrue
ferryInclude Fähre (F)?booleantrue
busInclude Bus?booleantrue
express-busInclude Schnellbus?booleantrue
anruf-sammel-taxiInclude Anruf-Sammel-Taxi (AST)?booleantrue
long-distance-trainInclude Fernzug (ICE/IC/EC/EN)?booleanfalse
long-distance-busInclude Fernbus?booleanfalse
prettyPretty-print JSON responses?booleantrue

Example

# at Dammtor (Messe/CCH), in direction Universität/Staatsbibliothek, 10 minutes
curl 'https://v5.hvv.transport.rest/stops/163/departures?direction=8868&duration=10' -s | jq
[
	{
		"tripId": "1|8729|0|80|26042020",
		"direction": "U Niendorf Markt",
		"line": {
			"type": "line",
			"id": "hha-b-5",
			"name": "5",
			"mode": "bus",
			"product": "bus",
			// …
		},

		"when": "2020-04-26T23:03:00+02:00",
		"plannedWhen": "2020-04-26T23:03:00+02:00",
		"delay": 0,
		"platform": null,
		"plannedPlatform": null,

		"stop": {
			"type": "stop",
			"id": "8862",
			"name": "Bf. Dammtor",
			"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
includeRelatedStationsFetch departures at related stops, e.g. those that belong together on the metro map?booleantrue
stopoversFetch & parse next stopovers of each departure?booleanfalse
subwayInclude U-Bahn (U)?booleantrue
suburbanInclude S-Bahn (S)?booleantrue
aknInclude AKN (A)?booleantrue
regional-express-trainInclude RegionalExpress (RE)?booleantrue
regional-trainInclude Regionalbahn (RB)?booleantrue
ferryInclude Fähre (F)?booleantrue
busInclude Bus?booleantrue
express-busInclude Schnellbus?booleantrue
anruf-sammel-taxiInclude Anruf-Sammel-Taxi (AST)?booleantrue
long-distance-trainInclude Fernzug (ICE/IC/EC/EN)?booleanfalse
long-distance-busInclude Fernbus?booleanfalse
prettyPretty-print JSON responses?booleantrue

Example

# at Dammtor (Messe/CCH), 10 minutes
curl 'https://v5.hvv.transport.rest/stops/163/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
subwayInclude U-Bahn (U)?booleantrue
suburbanInclude S-Bahn (S)?booleantrue
aknInclude AKN (A)?booleantrue
regional-express-trainInclude RegionalExpress (RE)?booleantrue
regional-trainInclude Regionalbahn (RB)?booleantrue
ferryInclude Fähre (F)?booleantrue
busInclude Bus?booleantrue
express-busInclude Schnellbus?booleantrue
anruf-sammel-taxiInclude Anruf-Sammel-Taxi (AST)?booleantrue
long-distance-trainInclude Fernzug (ICE/IC/EC/EN)?booleanfalse
long-distance-busInclude Fernbus?booleanfalse
prettyPretty-print JSON responses?booleantrue

Examples

# stop/station to POI
curl 'https://v5.hvv.transport.rest/journeys?from=163&to.id=980001822&to.latitude=53.55525&to.longitude=10.00305' -s | jq
# without buses, with ticket info
curl 'https://v5.hvv.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.hvv.transport.rest/journeys?from=…&to=…&results=1' -s | jq '.journeys[0]')
refresh_token=$(echo $journey | jq -r '.refreshToken')

# refresh the journey
curl "https://v5.hvv.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.hvv.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.hvv.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=53.555&west=9.989&south=53.55&east=10.001'
curl "https://v5.hvv.transport.rest/radar?$bbox&results=10" -s | jq

Date/Time Parameters

Possible formats: