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.
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
GET /locations
🔗Uses hafasClient.locations()
to find stops/stations, POIs and addresses matching query
.
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 |
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.
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 |
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.
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 |
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.
parameter | description | type | default value |
---|---|---|---|
linesOfStops | Parse & expose lines at each stop/station? | boolean | false |
language | Language of the results. | string | en |
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.
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 |
# 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.
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 |
# 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:
from=163
for Dammtor (Messe/CCH))from.id=980001141&from.latitude=53.5415&from.longitude=9.98576
for Elbphilharmonie Besucherzentrum)from.latitude=53.57422&from.longitude=10.01248&from.address=Hamburg,+Karlstraße+26
for Karlstr. 26)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.
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 |
# 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.
parameter | description | type | default value |
---|---|---|---|
stopovers | Fetch & parse stopovers on the way? | boolean | false |
tickets | Fetch & parse a shape for each journey leg? | boolean | false |
polylines | Return information about available tickets? | boolean | false |
remarks | Parse & return hints & warnings? | boolean | true |
language | Language of the results. | string | en |
# 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.
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 |
# 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.
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 |
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
Possible formats:
parse-human-relative-time
can parse (e.g. tomorrow 2pm
)2020-04-26T22:43+02:00
)1587933780
)