simono41/db-rest
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
db-rest/docs/api.md
Jannis R ab9f1af672
generate API docs 📝
2020-05-01 20:13:45 +02:00

20 KiB
Raw Blame History

v5.db.transport.rest API documentation

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

parameter description type default value
query Required. string –
fuzzy Find more than exact matches? boolean true
results How many stations shall be shown? number 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

Example

curl 'https://v5.db.transport.rest/locations?query=halle&results=1' -s | jq

[
	{
		"type": "stop",
		"id": "8010159",
		"name": "Halle (Saale) Hbf",
		"location": {
			"type": "location",
			"id": "8010159",
			"latitude": 51.477079,
			"longitude": 11.98699
		},
		"products": {
			"nationalExpress": true,
			"national": true,
			// …
		}
	}
]

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 number 8
distance maximum walking distance in meters number –
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

Example

curl 'https://v5.db.transport.rest/stops/nearby?latitude=53.5711&longitude=10.0015' -s | jq

[
	{
		"type": "stop",
		"id": "694800",
		"name": "Böttgerstraße, Hamburg",
		"location": {
			"type": "location",
			"id": "694800",
			"latitude": 53.568356,
			"longitude": 9.995528
		},
		"products": { /* … */ },
		"distance": 498,
	},
	// …
	{
		"type": "stop",
		"id": "694802",
		"name": "Bahnhof Dammtor, Hamburg",
		"location": {
			"type": "location",
			"id": "694802",
			"latitude": 53.561048,
			"longitude": 9.990315
		},
		"products": { /* … */ },
		"distance": 1340,
	},
	// …
]

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. number 5
maxDuration Maximum travel duration, in minutes. number infinite
language Language of the results. string en
nationalExpress Include InterCityExpress (ICE)? boolean true
national Include InterCity & EuroCity (IC/EC)? boolean true
regionalExp Include RegionalExpress & InterRegio (RE/IR)? boolean true
regional Include Regio (RB)? boolean true
suburban Include S-Bahn (S)? boolean true
bus Include Bus (B)? boolean true
ferry Include Ferry (F)? boolean true
subway Include U-Bahn (U)? boolean true
tram Include Tram (T)? boolean true
taxi Include Group Taxi (Taxi)? boolean true

Example

curl 'https://v5.db.transport.rest/stops/reachable-from?latitude=53.553766&longitude=9.977514&address=Hamburg,+Holstenwall+9' -s | jq

[
	{
		"duration": 1,
		"stations": [
			{
				"type": "stop",
				"id": "694815",
				"name": "Handwerkskammer, Hamburg",
				"location": { /* … */ },
				"products": { /* … */ },
			},
		]
	},
	// …
	{
		"duration": 5,
		"stations": [
			{
				"type": "stop",
				"id": "694807",
				"name": "Feldstraße (U), Hamburg",
				"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

Example

curl 'https://v5.db.transport.rest/stops/8010159' -s | jq

{
	"type": "stop",
	"id": "8010159",
	"ids": {
		"dhid": "de:15002:8010159",
		"MDV": "8010159",
		"NASA": "8010159"
	},
	"name": "Halle (Saale) Hbf",
	"location": {
		"type": "location",
		"id": "8010159",
		"latitude": 51.477079,
		"longitude": 11.98699
	},
	"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? number 10
results Max. number of departures. number *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
nationalExpress Include InterCityExpress (ICE)? boolean true
national Include InterCity & EuroCity (IC/EC)? boolean true
regionalExp Include RegionalExpress & InterRegio (RE/IR)? boolean true
regional Include Regio (RB)? boolean true
suburban Include S-Bahn (S)? boolean true
bus Include Bus (B)? boolean true
ferry Include Ferry (F)? boolean true
subway Include U-Bahn (U)? boolean true
tram Include Tram (T)? boolean true
taxi Include Group Taxi (Taxi)? boolean true

Example

# at Halle (Saale) Hbf, in direction Berlin Südkreuz
curl 'https://v5.db.transport.rest/stops/8010159/departures?direction=8011113&duration=120' -s | jq

[
	{
		"tripId": "1|317591|0|80|1052020",
		"direction": "Berlin Hbf (tief)",
		"line": {
			"type": "line",
			"id": "ice-702",
			"name": "ICE 702",
			"mode": "train",
			"product": "nationalExpress",
			// …
		},

		"when": "2020-05-01T21:06:00+02:00",
		"plannedWhen": "2020-05-01T21:06:00+02:00",
		"delay": 0,
		"platform": "8",
		"plannedPlatform": "8",

		"stop": {
			"type": "stop",
			"id": "8010159",
			"name": "Halle (Saale) Hbf",
			"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? number 10
results Max. number of departures. number 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
nationalExpress Include InterCityExpress (ICE)? boolean true
national Include InterCity & EuroCity (IC/EC)? boolean true
regionalExp Include RegionalExpress & InterRegio (RE/IR)? boolean true
regional Include Regio (RB)? boolean true
suburban Include S-Bahn (S)? boolean true
bus Include Bus (B)? boolean true
ferry Include Ferry (F)? boolean true
subway Include U-Bahn (U)? boolean true
tram Include Tram (T)? boolean true
taxi Include Group Taxi (Taxi)? boolean true

Example

# at Halle (Saale) Hbf, 10 minutes
curl 'https://v5.db.transport.rest/stops/8010159/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=8010159 for Halle (Saale) Hbf)
  • as a POI (e.g. from.id=991561765&from.latitude=51.48364&from.longitude=11.98084 for Halle+(Saale),+Stadtpark+Halle+(Grünanlagen))
  • as an address (e.g. from.latitude=51.25639&from.longitude=7.46685&from.address=Hansestadt+Breckerfeld,+Hansering+3 for Hansestadt Breckerfeld, Hansering 3)

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. number 3
stopovers Fetch & parse stopovers on the way? boolean false
transfers Maximum number of transfers. number let HAFAS decide
transferTime Minimum time in minutes for a single transfer. number 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
nationalExpress Include InterCityExpress (ICE)? boolean true
national Include InterCity & EuroCity (IC/EC)? boolean true
regionalExp Include RegionalExpress & InterRegio (RE/IR)? boolean true
regional Include Regio (RB)? boolean true
suburban Include S-Bahn (S)? boolean true
bus Include Bus (B)? boolean true
ferry Include Ferry (F)? boolean true
subway Include U-Bahn (U)? boolean true
tram Include Tram (T)? boolean true
taxi Include Group Taxi (Taxi)? boolean true

Examples

# stop/station to POI
curl 'https://v5.db.transport.rest/journeys?from=8010159&to.id=991561765&to.latitude=51.483641&to.longitude=11.980841' -s | jq
# without buses, with ticket info
curl 'https://v5.db.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 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

Example

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

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

Example

# get the trip ID of a journey leg
journey=$(curl 'https://v5.db.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.db.transport.rest/trips/$(echo $trip_id | url-encode)" -s | jq

GET /stations

If the query parameter is used, it will use db-stations-autocomplete to autocomplete Deutsche Bahn-operated stops/stations. Otherwise, it will filter the stops/stations in db-stations.

Instead of receiving a JSON response, you can request newline-delimited JSON by sending Accept: application/x-ndjson.

Query Parameters

parameter description type default value
query Find stations by name using db-stations-autocomplete. string –
limit If query is used: Return at most n stations. number 3
fuzzy If query is used: Find stations despite typos. boolean false
completion If query is used: Autocomplete stations. boolean true

Examples

# autocomplete using db-stations-autocomplete
curl 'https://v5.db.transport.rest/stations?query=dammt' -s | jq

{
	"8002548": {
		"id": "8002548",
		"relevance": 0.8572361756428573,
		"score": 9.175313823998414,
		"weight": 1212,
		"type": "station",
		"ril100": "ADF",
		"name": "Hamburg Dammtor",
		"location": {
			"type": "location",
			"latitude": 53.560751,
			"longitude": 9.989566
		},
		"operator": {
			"type": "operator",
			"id": "hamburger-verkehrsverbund-gmbh",
			"name": "BWVI"
		},
		"address": {
			"city": "Hamburg",
			"zipcode": "20354",
			"street": "Dag-Hammarskjöld-Platz 15"
		},
		// …
	},
	// …
}

# filter db-stations by `hasParking` property
curl 'https://v5.db.transport.rest/stations?hasParking=true' -s | jq

{
	"8000001": {
		"type": "station",
		"id": "8000001",
		"ril100": "KA",
		"name": "Aachen Hbf",
		"weight": 653.75,
		"location": { /* … */ },
		"operator": { /* … */ },
		"address": { /* … */ },
		// …
	},
	// …
}

# filter db-stations by `hasDBLounge` property, get newline-delimited JSON
curl 'https://v5.db.transport.rest/stations?hasDBLounge=true' -H 'accept: application/x-ndjson' -s | jq

GET /stations/:id

Returns a stop/station from db-stations.

Query Parameters

Example

# lookup Halle (Saale) Hbf
curl 'https://v5.db.transport.rest/stations/8010159' -s | jq
curl 'https://v5.db.transport.rest/stations/LH' -s | jq # RIL100/DS100
curl 'https://v5.db.transport.rest/stations/LHG' -s | jq # RIL100/DS100

{
	"type": "station",
	"id": "8010159",
	"additionalIds": ["8098159"],
	"ril100": "LH",
	"nr": 2498,
	"name": "Halle (Saale) Hbf",
	"weight": 815.6,
	"location": { /* … */ },
	"operator": { /* … */ },
	"address": { /* … */ },
	"ril100Identifiers": [
		{
			"rilIdentifier": "LH",
			// …
		},
		// …
	],
	// …
}

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. number 256
duration Compute frames for the next n seconds. number 30
frames Number of frames to compute. number 3
polylines Fetch & parse a geographic shape for the movement of each vehicle? boolean true
language Language of the results. string en

Example

bbox='north=53.555&west=9.989&south=53.55&east=10.001'
curl "https://v5.db.transport.rest/radar?$bbox&results=10" -s | jq

Date/Time Parameters

Possible formats: