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.

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 /stops/nearby
• GET /stops/reachable-from
• GET /stops/:id
• GET /stops/:id/departures
• GET /stops/:id/arrivals
• GET /journeys
• GET /trips/:id
• GET /locations
• GET /radar
• GET /journeys/:ref
• date/time parameters

GET /locations🔗

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

Query Parameters🔗

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🔗

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🔗

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🔗

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🔗

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🔗

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:

• as stop/station ID (e.g. from=163 for Dammtor (Messe/CCH))
• as a POI (e.g. from.id=980001141&from.latitude=53.5415&from.longitude=9.98576 for Elbphilharmonie Besucherzentrum)
• as an address (e.g. from.latitude=53.57422&from.longitude=10.01248&from.address=Hamburg,+Karlstraße+26 for Karlstr. 26)

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🔗

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🔗

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🔗

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🔗

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:

• anything that parse-human-relative-time can parse (e.g. tomorrow 2pm)
• ISO 8601 date/time string (e.g. 2020-04-26T22:43+02:00)
• UNIX timestamp (e.g. 1587933780)