`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 /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

parameter	description	type	default value
`query`	Required.	string	–
`fuzzy`	Find more than exact matches?	boolean	`true`
`results`	How many stations shall be shown?	integer	`10`
`stops`	Show stops/stations?	boolean	`true`
`addresses`	Show points of interest?	boolean	`true`
`poi`	Show addresses?	boolean	`true`
`linesOfStops`	Parse & return lines of each stop/station?	boolean	`false`
`language`	Language of the results.	string	`en`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`latitude`	Required.	number	–
`longitude`	Required.	number	–
`results`	maximum number of results	integer	`8`
`distance`	maximum walking distance in meters	integer	–
`stops`	Return stops/stations?	boolean	`true`
`poi`	Return points of interest?	boolean	`false`
`linesOfStops`	Parse & expose lines at each stop/station?	boolean	`false`
`language`	Language of the results.	string	`en`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`latitude`	Required.	number	–
`longitude`	Required.	number	–
`address`	Required.	string	–
`when`	Date & time to compute the reachability for. See date/time parameters.	date+time	now
`maxTransfers`	Maximum number of transfers.	integer	`5`
`maxDuration`	Maximum travel duration, in minutes.	integer	infinite
`language`	Language of the results.	string	`en`
`subway`	Include U-Bahn (U)?	boolean	`true`
`suburban`	Include S-Bahn (S)?	boolean	`true`
`akn`	Include AKN (A)?	boolean	`true`
`regional-express-train`	Include RegionalExpress (RE)?	boolean	`true`
`regional-train`	Include Regionalbahn (RB)?	boolean	`true`
`ferry`	Include Fähre (F)?	boolean	`true`
`bus`	Include Bus?	boolean	`true`
`express-bus`	Include Schnellbus?	boolean	`true`
`anruf-sammel-taxi`	Include Anruf-Sammel-Taxi (AST)?	boolean	`true`
`long-distance-train`	Include Fernzug (ICE/IC/EC/EN)?	boolean	`false`
`long-distance-bus`	Include Fernbus?	boolean	`false`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`linesOfStops`	Parse & expose lines at each stop/station?	boolean	`false`
`language`	Language of the results.	string	`en`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`when`	Date & time to get departures for. See date/time parameters.	date+time	now
`direction`	Filter departures by direction.	string
`duration`	Show departures for how many minutes?	integer	`10`
`results`	Max. number of departures.	integer	*whatever HAFAS wants
`linesOfStops`	Parse & return lines of each stop/station?	boolean	`false`
`remarks`	Parse & return hints & warnings?	boolean	`true`
`language`	Language of the results.	string	`en`
`includeRelatedStations`	Fetch departures at related stops, e.g. those that belong together on the metro map?	boolean	`true`
`stopovers`	Fetch & parse next stopovers of each departure?	boolean	`false`
`subway`	Include U-Bahn (U)?	boolean	`true`
`suburban`	Include S-Bahn (S)?	boolean	`true`
`akn`	Include AKN (A)?	boolean	`true`
`regional-express-train`	Include RegionalExpress (RE)?	boolean	`true`
`regional-train`	Include Regionalbahn (RB)?	boolean	`true`
`ferry`	Include Fähre (F)?	boolean	`true`
`bus`	Include Bus?	boolean	`true`
`express-bus`	Include Schnellbus?	boolean	`true`
`anruf-sammel-taxi`	Include Anruf-Sammel-Taxi (AST)?	boolean	`true`
`long-distance-train`	Include Fernzug (ICE/IC/EC/EN)?	boolean	`false`
`long-distance-bus`	Include Fernbus?	boolean	`false`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`when`	Date & time to get departures for. See date/time parameters.	date+time	now
`direction`	Filter departures by direction.	string
`duration`	Show departures for how many minutes?	integer	`10`
`results`	Max. number of departures.	integer	whatever HAFAS wants
`linesOfStops`	Parse & return lines of each stop/station?	boolean	`false`
`remarks`	Parse & return hints & warnings?	boolean	`true`
`language`	Language of the results.	string	`en`
`includeRelatedStations`	Fetch departures at related stops, e.g. those that belong together on the metro map?	boolean	`true`
`stopovers`	Fetch & parse next stopovers of each departure?	boolean	`false`
`subway`	Include U-Bahn (U)?	boolean	`true`
`suburban`	Include S-Bahn (S)?	boolean	`true`
`akn`	Include AKN (A)?	boolean	`true`
`regional-express-train`	Include RegionalExpress (RE)?	boolean	`true`
`regional-train`	Include Regionalbahn (RB)?	boolean	`true`
`ferry`	Include Fähre (F)?	boolean	`true`
`bus`	Include Bus?	boolean	`true`
`express-bus`	Include Schnellbus?	boolean	`true`
`anruf-sammel-taxi`	Include Anruf-Sammel-Taxi (AST)?	boolean	`true`
`long-distance-train`	Include Fernzug (ICE/IC/EC/EN)?	boolean	`false`
`long-distance-bus`	Include Fernbus?	boolean	`false`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`departure`	Compute journeys departing at this date/time. Mutually exclusive with `arrival`. See date/time parameters.	date+time	now
`arrival`	Compute journeys arriving at this date/time. Mutually exclusive with `departure`. See date/time parameters.	date+time	now
`earlierThan`	Compute journeys "before" an `ealierRef`.	string
`laterThan`	Compute journeys "after" an `laterRef`.	string
`results`	Max. number of journeys.	integer	`3`
`stopovers`	Fetch & parse stopovers on the way?	boolean	`false`
`transfers`	Maximum number of transfers.	integer	let HAFAS decide
`transferTime`	Minimum time in minutes for a single transfer.	integer	`0`
`accessibility`	`partial` or `complete`.	string	not accessible
`bike`	Compute only bike-friendly journeys?	boolean	`false`
`startWithWalking`	Consider walking to nearby stations at the beginning of a journey?	boolean	`true`
`walkingSpeed`	`slow`, `normal` or `fast`.	string	`normal`
`tickets`	Return information about available tickets?	boolean	`false`
`polylines`	Fetch & parse a shape for each journey leg?	boolean	`false`
`remarks`	Parse & return hints & warnings?	boolean	`true`
`scheduledDays`	Parse & return dates each journey is valid on?	boolean	`false`
`language`	Language of the results.	string	`en`
`subway`	Include U-Bahn (U)?	boolean	`true`
`suburban`	Include S-Bahn (S)?	boolean	`true`
`akn`	Include AKN (A)?	boolean	`true`
`regional-express-train`	Include RegionalExpress (RE)?	boolean	`true`
`regional-train`	Include Regionalbahn (RB)?	boolean	`true`
`ferry`	Include Fähre (F)?	boolean	`true`
`bus`	Include Bus?	boolean	`true`
`express-bus`	Include Schnellbus?	boolean	`true`
`anruf-sammel-taxi`	Include Anruf-Sammel-Taxi (AST)?	boolean	`true`
`long-distance-train`	Include Fernzug (ICE/IC/EC/EN)?	boolean	`false`
`long-distance-bus`	Include Fernbus?	boolean	`false`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`stopovers`	Fetch & parse stopovers on the way?	boolean	`false`
`tickets`	Return information about available tickets?	boolean	`false`
`polylines`	Fetch & parse a shape for each journey leg?	boolean	`false`
`remarks`	Parse & return hints & warnings?	boolean	`true`
`language`	Language of the results.	string	`en`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`lineName`	Required. Line name of the part's mode of transport, e.g. `RE7`.	string	–
`stopovers`	Fetch & parse stopovers on the way?	boolean	`true`
`remarks`	Parse & return hints & warnings?	boolean	`true`
`polyline`	Fetch & parse the geographic shape of the trip?	boolean	`false`
`language`	Language of the results.	string	`en`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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

parameter	description	type	default value
`north`	Required. Northern latitude.	number	–
`west`	Required. Western longitude.	number	–
`south`	Required. Southern latitude.	number	–
`east`	Required. Eastern longitude.	number	–
`results`	Max. number of vehicles.	integer	`256`
`duration`	Compute frames for the next `n` seconds.	integer	`30`
`frames`	Number of frames to compute.	integer	`3`
`polylines`	Fetch & parse a geographic shape for the movement of each vehicle?	boolean	`true`
`language`	Language of the results.	string	`en`
`pretty`	Pretty-print JSON responses?	boolean	`true`

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)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

api.md

api.md

`v5.hvv.transport.rest` API documentation

Routes

`GET /locations`

Query Parameters

Example

`GET /stops/nearby`

Query Parameters

Example

`GET /stops/reachable-from`

Query Parameters

Example

`GET /stops/:id`

Query Parameters

Example

`GET /stops/:id/departures`

Query Parameters

Example

`GET /stops/:id/arrivals`

Query Parameters

Example

`GET /journeys`

Pagination

Query Parameters

Examples

`GET /journeys/:ref`

Query Parameters

Example

`GET /trips/:id`

Query Parameters

Example

`GET /radar`

Query Parameters

Example

Date/Time Parameters

Files

api.md

Latest commit

History

api.md

File metadata and controls

v5.hvv.transport.rest API documentation

Routes

GET /locations

Query Parameters

Example

GET /stops/nearby

Query Parameters

Example

GET /stops/reachable-from

Query Parameters

Example

GET /stops/:id

Query Parameters

Example

GET /stops/:id/departures

Query Parameters

Example

GET /stops/:id/arrivals

Query Parameters

Example

GET /journeys

Pagination

Query Parameters

Examples

GET /journeys/:ref

Query Parameters

Example

GET /trips/:id

Query Parameters

Example

GET /radar

Query Parameters

Example

Date/Time Parameters

`v5.hvv.transport.rest` API documentation

`GET /locations`

`GET /stops/nearby`

`GET /stops/reachable-from`

`GET /stops/:id`

`GET /stops/:id/departures`

`GET /stops/:id/arrivals`

`GET /journeys`

`GET /journeys/:ref`

`GET /trips/:id`

`GET /radar`