From c0db5828e58e96d6841760aaf0c45dded044d1c0 Mon Sep 17 00:00:00 2001 From: Jannis R Date: Sat, 16 Dec 2017 11:47:03 +0100 Subject: [PATCH] API documentation :memo: --- docs/index.md | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++ readme.md | 4 +- 2 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 docs/index.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5edc2fe --- /dev/null +++ b/docs/index.md @@ -0,0 +1,165 @@ +# [*Deutsche Bahn*](https://en.wikipedia.org/wiki/Deutsche_Bahn) Public Transport API + +**The public endpoint is [`1.db.transport.rest`](`https://1.db.transport.rest`).** This API returns data in the [*Friendly Public Transport Format* `1.0.1`](https://github.com/public-transport/friendly-public-transport-format/blob/1.0.1/spec/readme.md). + +*Note:* In order to improve this API, I would to know which software projects use it. Please send an **`X-Identifier` header (e.g. `my-awesome-tool`) to let me know who you are**. I you don't provide it, a hash of the client IP will be logged. + +## all routes + +- [`GET /stations?query=…`](#get-stationsquery) +- [`GET /stations`](#get-stations) +- [`GET /stations/:id/departures`](#get-stationsiddepartures) +- [`GET /journeys`](#get-journeys) +- [`GET /locations`](#get-locations) + +## `GET /stations?query=…` + +Passes all parameters into [`db-stations-autocomplete`](https://github.com/derhuerst/db-stations-autocomplete). + +- `query`: **Required.** +- `completion`: `true`/`false` – Default is `true` +- `fuzzy`: `true`/`false` – Default is `false` + +`Content-Type`: `application/json` + +### examples + +```shell +curl 'https://1.db.transport.rest/stations?query=jungfernheide' +# note the typo +curl 'https://1.db.transport.rest/stations?query=jungfernhiede&fuzzy=true' +``` + + +## `GET /stations` + +Passes all parameters into [`db-stations`](https://github.com/derhuerst/db-stations). + +- `id`: Filter by ID. +- `name`: Filter by name. +- `coordinates.latitude`: Filter by latitude. +- `coordinates.longitude`: Filter by longitude. +- `weight`: Filter by weight. + +`Content-Type`: `application/json` + +### examples + +```shell +curl 'https://1.db.transport.rest/stations?name=hannover&coordinates.latitude=52.3765387' +``` + + +## `GET /stations/all` + +Dumps `full.json` from [`vbb-stations`](https://github.com/derhuerst/vbb-stations). + +`Content-Type`: `application/json` + +### examples + +```shell +curl 'https://1.db.transport.rest/stations/all' +``` + + +## `GET /stations/:id/departures` + +Returns departures at a station. + +*Note:* As stated in the [*Friendly Public Transport Format* `1.0.1`](https://github.com/public-transport/friendly-public-transport-format/tree/1.0.1), the returned `departure` and `arrival` times include the current delay. + +Passes all parameters into [`departures(…)` from `db-hafas`](https://github.com/derhuerst/db-hafas/blob/master/docs/departures.md). + +- `when`: A [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) or anything parsable by [`parse-messy-time`](https://github.com/substack/parse-messy-time#example). Default: now. +- `duration`: Show departures for the next `n` minutes. Default: `10`. + +`Content-Type`: `application/json` + +### examples + +```shell +curl 'https://1.db.transport.rest/stations/008011160/departures?when=tomorrow%206pm' +``` + + +## `GET /journeys` + +Output from [`require('db-hafas').journeys(…)`](https://github.com/derhuerst/db-hafas#getting-started). Start location and end location must be either in [station format](#station-format) or in [POI/address format](#poiaddress-format) (you can mix them). + +*Note:* As stated in the [*Friendly Public Transport Format* `1.0.1`](https://github.com/public-transport/friendly-public-transport-format/tree/1.0.1), the returned `departure` and `arrival` times include the current delay. + +## station format + +- `from`: **Required.** Station ID (e.g. `008011162`). +- `to`: **Required.** Station ID (e.g. `008011162`). + +## POI/address format + +- `from.latitude`/`to.latitude`: **Required.** Latitude (e.g. `52.543333`). +- `from.longitude`/`to.longitude`: **Required.** Longitude (e.g. `13.351686`). +- `from.name`/`to.name`: Name of the locality (e.g. `Atze Musiktheater`). +- `from.id`/`to.id`: POI ID (e.g. `991598902`). + +## other parameters + +- `when`: A [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) or anything parsable by [`parse-messy-time`](https://github.com/substack/parse-messy-time#example). Default: now. +- `results`: Maximum number of results. Default: `5`. +- `via`: Station ID. Default: `null`. +- `passedStations`: Return stations on the way? Default: `false`. +- `transfers`: Maximum number of transfers. Default: `5`. +- `transferTime`: Minimum time in minutes for a single transfer. Default: `0`. +- `accessibility`: Possible values: `partial`, `complete`. Default: `none`. +- `bike`: Return only bike-friendly journeys. Default: `false`. +- `tickets`: Return information about available tickets. Default: `false`. + +taxi +tram +bus +ferry +subway +suburban +regional +regionalExp +national +nationalExp +- `taxi`: Include taxis? Default: `false`. +- `tram`: Include [trams](https://en.wikipedia.org/wiki/Tram)? Default: `true`. +- `ferry`: Include [ferries](https://en.wikipedia.org/wiki/Ferry)? Default: `true`. +- `bus`: Include [buses](https://en.wikipedia.org/wiki/Bus)? Default: `true`. +- `subway`: Include [U-Bahn trains](https://en.wikipedia.org/wiki/Rapid_transit)? Default: `true`. +- `suburban`: Include [S-Bahn trains](https://en.wikipedia.org/wiki/S-train)? Default: `true`. +- `regional`: Include RB/ODEG trains? Default: `true`. +- `regionalExp`: Include RE/ODEG trains? Default: `true`. +- `national`: Include [IC/EC trains](https://en.wikipedia.org/wiki/Intercity_(Deutsche_Bahn)? Default: `true`. +- `nationalExp`: Include [ICE trains](https://en.wikipedia.org/wiki/Intercity-Express)? Default: `true`. + +`Content-Type`: `application/json` + +### examples + +```shell +curl 'https://1.db.transport.rest/journeys?from=008011162&to=008000281' +curl 'https://1.db.transport.rest/journeys?from=008004158&to.name=Atze%20Musiktheater&to.latitude=52.543333&to.longitude=13.351686' +curl 'https://1.db.transport.rest/journeys?from=…&to=…&results=3&bus=false&tickets=true' +``` + + +## `GET /locations` + +Output from [`require('db-hafas').locations(…)`](https://github.com/derhuerst/db-hafas/blob/master/docs/locations.md) + +- `query`: **Required.** (e.g. `Alexanderplatz`) +- `results`: How many stations shall be shown? Default: `10`. +- `stations`: Show stations? Default: `true`. +- `poi`: Show points of interest? Default: `true`. +- `addresses`: Show addresses? Default: `true`. + +`Content-Type`: `application/json` + +### examples + +```shell +curl 'https://1.db.transport.rest/locations?query=Alexanderplatz' +curl 'https://1.db.transport.rest/locations?query=Pestalozzistra%C3%9Fe%2082%2C%20Berlin&poi=false&stations=false' +``` diff --git a/readme.md b/readme.md index 30a0085..31be487 100644 --- a/readme.md +++ b/readme.md @@ -1,6 +1,8 @@ # db-rest -**A clean REST API wrapping around the [Deutsche Bahn](https://en.wikipedia.org/wiki/Deutsche_Bahn) API.** +**A clean REST API wrapping around the [Deutsche Bahn](https://en.wikipedia.org/wiki/Deutsche_Bahn) [API](https://github.com/derhuerst/db-hafas#db-hafas).** + +[API Documentation](docs/index.md) [![dependency status](https://img.shields.io/david/derhuerst/db-rest.svg)](https://david-dm.org/derhuerst/db-rest) ![ISC-licensed](https://img.shields.io/github/license/derhuerst/db-rest.svg)