319 lines
7.3 KiB
Markdown
319 lines
7.3 KiB
Markdown
# Getting Started with `v6.db.transport.rest`
|
||
|
||
Let's walk through the **requests that are necessary to implement a typical basic transit app**.
|
||
|
||
*Note:* To properly & securely handle user input containing URL-unsafe characters, always [URL-encode](https://en.wikipedia.org/wiki/Percent-encoding) your query parameters!
|
||
|
||
The following code snippets use [`curl`](https://curl.haxx.se) (a versatile command line HTTP tool) and [`jq`](https://stedolan.github.io/jq/) (the command line swiss army knife for processing JSON).
|
||
|
||
### 1. search for stops
|
||
|
||
The `/locations?query=…` route allows you to query stops, points of interest (POIs) & addresses. We're only interested in stops though, so we filter using `poi=false&addresses=false`:
|
||
|
||
```shell
|
||
curl 'https://v6.db.transport.rest/locations?poi=false&addresses=false&query=südkreuz' -s | jq
|
||
```
|
||
|
||
```js
|
||
[
|
||
{
|
||
"type": "stop",
|
||
"id": "8011113",
|
||
"name": "Berlin Südkreuz",
|
||
"location": {
|
||
"type": "location",
|
||
"id": "8011113",
|
||
"latitude": 52.47623,
|
||
"longitude": 13.365863
|
||
},
|
||
"products": {
|
||
"nationalExpress": true,
|
||
"national": true,
|
||
// …
|
||
}
|
||
},
|
||
{
|
||
"type": "stop",
|
||
"id": "731654",
|
||
"name": "Südkreuz Bahnhof (S), Berlin",
|
||
"location": {
|
||
"type": "location",
|
||
"id": "731654",
|
||
"latitude": 52.476265,
|
||
"longitude": 13.3642
|
||
},
|
||
"products": {
|
||
"nationalExpress": true,
|
||
"national": true,
|
||
"regionalExp": true,
|
||
"regional": true,
|
||
"suburban": true,
|
||
"bus": true,
|
||
"ferry": false,
|
||
"subway": false,
|
||
"tram": false,
|
||
"taxi": false
|
||
}
|
||
},
|
||
{
|
||
"type": "stop",
|
||
"id": "727256",
|
||
"name": "Südkreuz Bahnhof (S)/Ostseite, Berlin",
|
||
"location": {
|
||
"type": "location",
|
||
"id": "727256",
|
||
"latitude": 52.47436,
|
||
"longitude": 13.366843
|
||
},
|
||
"products": {
|
||
// …
|
||
}
|
||
},
|
||
// …
|
||
]
|
||
```
|
||
|
||
### 2. fetch departures at a stop
|
||
|
||
Let's fetch 5 of the next departures at *Berlin Südkreuz* (which has the ID `8011113`):
|
||
|
||
```shell
|
||
curl 'https://v6.db.transport.rest/stops/8011113/departures?results=5' -s | jq
|
||
```
|
||
|
||
```js
|
||
[
|
||
{
|
||
"tripId": "1|1168945|24|80|1052020",
|
||
"direction": "Schöneberg, Reichartstr.",
|
||
"line": {
|
||
"type": "line",
|
||
"id": "5-vbbbvb-248",
|
||
"name": "Bus 248",
|
||
"mode": "bus",
|
||
"product": "bus",
|
||
// …
|
||
},
|
||
|
||
"when": "2020-05-01T18:39:00+02:00",
|
||
"plannedWhen": "2020-05-01T18:38:00+02:00",
|
||
"delay": 60,
|
||
"platform": null,
|
||
"plannedPlatform": null,
|
||
|
||
"stop": {
|
||
"type": "stop",
|
||
"id": "727256",
|
||
"name": "Südkreuz Bahnhof (S)/Ostseite, Berlin",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
"station": {
|
||
"type": "station",
|
||
"id": "8011113",
|
||
"name": "Berlin Südkreuz",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
}
|
||
},
|
||
|
||
"remarks": [],
|
||
},
|
||
// …
|
||
{
|
||
"tripId": "1|322308|0|80|1052020",
|
||
"direction": "Lutherstadt Wittenberg Hbf",
|
||
"line": {
|
||
"type": "line",
|
||
"id": "re-3",
|
||
"name": "RE 3",
|
||
"mode": "train",
|
||
"product": "regional",
|
||
// …
|
||
},
|
||
|
||
"when": "2020-05-01T18:40:00+02:00",
|
||
"plannedWhen": "2020-05-01T18:41:00+02:00",
|
||
"delay": -60,
|
||
"platform": "6",
|
||
"plannedPlatform": "6",
|
||
|
||
"stop": {
|
||
"type": "stop",
|
||
"id": "8011113",
|
||
"name": "Berlin Südkreuz",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
},
|
||
|
||
"remarks": [ /* … */ ],
|
||
},
|
||
// …
|
||
]
|
||
```
|
||
|
||
Note that `when` includes the `delay`, and `plannedWhen` does not.
|
||
|
||
### 3. fetch journeys from A to B
|
||
|
||
We call a connection from A to B – at a specific date & time, made up of sections on specific *trips* – `journey`.
|
||
|
||
Let's fetch 2 journeys from `8011113` (*Berlin Südkreuz*) to `8010159` (*Halle (Saale)Hbf*), departing tomorrow at 2pm (at the time of writing this).
|
||
|
||
```shell
|
||
curl 'https://v6.db.transport.rest/journeys?from=8011113&to=8010159&departure=tomorrow+2pm&results=2' -s | jq
|
||
```
|
||
|
||
```js
|
||
{
|
||
"journeys": [{
|
||
// 1st journey
|
||
"type": "journey",
|
||
"legs": [{
|
||
// 1st leg
|
||
"tripId": "1|310315|0|80|2052020",
|
||
"direction": "München Hbf",
|
||
"line": {
|
||
"type": "line",
|
||
"id": "ice-1601",
|
||
"name": "ICE 1601",
|
||
"mode": "train",
|
||
"product": "nationalExpress",
|
||
// …
|
||
},
|
||
|
||
"origin": {
|
||
"type": "stop",
|
||
"id": "8011113",
|
||
"name": "Berlin Südkreuz",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
},
|
||
"departure": "2020-05-02T14:37:00+02:00",
|
||
"plannedDeparture": "2020-05-02T14:37:00+02:00",
|
||
"departureDelay": null,
|
||
"departurePlatform": "3",
|
||
"plannedDeparturePlatform": "3"
|
||
|
||
"destination": {
|
||
"type": "stop",
|
||
"id": "8010205",
|
||
"name": "Leipzig Hbf",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
},
|
||
"arrival": "2020-05-02T15:42:00+02:00",
|
||
"plannedArrival": "2020-05-02T15:42:00+02:00",
|
||
"arrivalDelay": null,
|
||
"arrivalPlatform": "11",
|
||
"plannedArrivalPlatform": "11",
|
||
// …
|
||
}, {
|
||
// 2nd leg
|
||
"walking": true,
|
||
"distance": 116,
|
||
|
||
"origin": {
|
||
"type": "stop",
|
||
"id": "8010205",
|
||
"name": "Leipzig Hbf",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
},
|
||
"departure": "2020-05-02T15:42:00+02:00",
|
||
"plannedDeparture": "2020-05-02T15:42:00+02:00",
|
||
"departureDelay": null,
|
||
|
||
"destination": {
|
||
"type": "stop",
|
||
"id": "8098205",
|
||
"name": "Leipzig Hbf (tief)",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },,
|
||
"station": {
|
||
"type": "station",
|
||
"id": "8010205",
|
||
"name": "Leipzig Hbf",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
}
|
||
},
|
||
"arrival": "2020-05-02T15:51:00+02:00",
|
||
"plannedArrival": "2020-05-02T15:51:00+02:00",
|
||
"arrivalDelay": null,
|
||
// …
|
||
}, {
|
||
// 3rd leg
|
||
"tripId": "1|334376|4|80|2052020",
|
||
"direction": "Halle(Saale)Hbf",
|
||
"line": {
|
||
"type": "line",
|
||
"id": "4-800486-5",
|
||
"name": "S 5",
|
||
"mode": "train",
|
||
"product": "suburban",
|
||
// …
|
||
},
|
||
|
||
"origin": {
|
||
"type": "stop",
|
||
"id": "8098205",
|
||
"name": "Leipzig Hbf (tief)",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },,
|
||
"station": {
|
||
"type": "station",
|
||
"id": "8010205",
|
||
"name": "Leipzig Hbf",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
}
|
||
},
|
||
"departure": "2020-05-02T15:53:00+02:00",
|
||
"plannedDeparture": "2020-05-02T15:53:00+02:00",
|
||
"departureDelay": null,
|
||
"departurePlatform": "2",
|
||
"plannedDeparturePlatform": "2",
|
||
|
||
"destination": {
|
||
"type": "stop",
|
||
"id": "8010159",
|
||
"name": "Halle(Saale)Hbf",
|
||
"location": { /* … */ },
|
||
"products": { /* … */ },
|
||
},
|
||
"arrival": "2020-05-02T16:19:00+02:00",
|
||
"plannedArrival": "2020-05-02T16:19:00+02:00",
|
||
"arrivalDelay": null,
|
||
"arrivalPlatform": "13",
|
||
"plannedArrivalPlatform": "13",
|
||
|
||
"cycle": {"min": 600, "max": 1800, "nr": 7},
|
||
"alternatives": [
|
||
{
|
||
"tripId": "1|333647|0|80|2052020",
|
||
"direction": "Halle(Saale)Hbf",
|
||
"line": { /* … */ },
|
||
"when": "2020-05-02T16:03:00+02:00",
|
||
"plannedWhen": "2020-05-02T16:03:00+02:00",
|
||
"delay": null,
|
||
},
|
||
// …
|
||
],
|
||
// …
|
||
}],
|
||
}, {
|
||
// 2nd journey
|
||
"type": "journey",
|
||
"legs": [ /* … */ ],
|
||
// …
|
||
}],
|
||
|
||
// …
|
||
}
|
||
```
|
||
|
||
Note that `departure` includes the `departureDelay`, and `arrival` includes the `arrivalDelay`. `plannedDeparture` and `plannedArrival` do not.
|
||
|
||
### 4. more features
|
||
|
||
These are the basics. Check the full [API docs](api.md) for all features or use the [OpenAPI playground](https://petstore.swagger.io/?url=https%3A%2F%2Fv6.db.transport.rest%2F.well-known%2Fservice-desc%0A) or explore the API!
|