kbruen/db-vendo-client
1
0
Fork 0
mirror of https://github.com/public-transport/db-vendo-client.git synced 2025-02-23 07:09:35 +02:00
Code Issues Projects Releases Packages 1 Wiki Activity Actions

docs: methods, usage examples, more related projects

Browse source
This commit is contained in:
Jannis R 2017-12-17 18:16:04 +01:00
parent bcddc49049
commit 374fd6120a
No known key found for this signature in database
GPG key ID: 0FE83946296A88A5
12 changed files with 824 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

155
docs/departures.md Normal file
View file

@ -0,0 +1,155 @@
# `departures(station, [opt])`
`station` must be in one of these formats:
```js
// a station ID, in a format compatible to the profile you use
'900000013102'
// an FPTF `station` object
{
type: 'station',
id: '900000013102',
name: 'foo station',
location: {
type: 'location',
latitude: 1.23,
longitude: 3.21
}
}
```
With `opt`, you can override the default options, which look like this:
```js
{
when: new Date(),
direction: null, // only show departures heading to this station
duration: 10 // show departures for the next n minutes
}
```
## Response
*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 `when` include the current delay. The `delay` field, if present, expresses how much the former differs from the schedule.
You may pass the `journeyId` field into [`journeyPart(ref, lineName, [opt])`](journey-part.md) to get details on the vehicle's journey.
As an example, we're going to use the VBB profile:
```js
const createClient = require('hafas-client')
const vbbProfile = require('hafas-client/p/vbb')
const client = createClient(vbbProfile)
// S Charlottenburg
client.journeys('900000024101', {duration: 3})
.then(console.log)
.catch(console.error)
```
The response may look like this:
```js
[ {
journeyId: '1|31431|28|86|17122017',
trip: 31431,
station: {
type: 'station',
id: '900000024101',
name: 'S Charlottenburg',
location: {
type: 'location',
latitude: 52.504806,
longitude: 13.303846
},
products: {
suburban: true,
subway: false,
tram: false,
bus: true,
ferry: false,
express: false,
regional: true
}
},
when: '2017-12-17T19:32:00.000+01:00',
delay: null
line: {
type: 'line',
id: '18299',
name: 'S9',
public: true,
mode: 'train',
product: 'suburban',
symbol: 'S',
nr: 9,
metro: false,
express: false,
night: false,
productCode: 0
},
direction: 'S Spandau'
}, {
journeyId: '1|30977|8|86|17122017',
trip: 30977,
station: { /* … */ },
when: '2017-12-17T19:35:00.000+01:00',
delay: 0,
line: {
type: 'line',
id: '16441',
name: 'S5',
public: true,
mode: 'train',
product: 'suburban',
symbol: 'S',
nr: 5,
metro: false,
express: false,
night: false,
productCode: 0
},
direction: 'S Westkreuz'
}, {
journeyId: '1|28671|4|86|17122017',
trip: 28671,
station: {
type: 'station',
id: '900000024202',
name: 'U Wilmersdorfer Str.',
location: {
type: 'location',
latitude: 52.506415,
longitude: 13.306777
},
products: {
suburban: false,
subway: true,
tram: false,
bus: false,
ferry: false,
express: false,
regional: false
}
},
when: '2017-12-17T19:35:00.000+01:00',
delay: 0,
line: {
type: 'line',
id: '19494',
name: 'U7',
public: true,
mode: 'train',
product: 'subway',
symbol: 'U',
nr: 7,
metro: false,
express: false,
night: false,
productCode: 1
},
direction: 'U Rudow'
} ]
```

112
docs/journey-part.md Normal file
View file

@ -0,0 +1,112 @@
# `journeyPart(ref, lineName, [opt])`
This method can be used to refetch information about a leg of a journey. Note that it is not supported by every profile/endpoint.
Let's say you used [`journeys`](journeys.md) and now want to get more up-to-date data about the arrival/departure of a leg. You'd pass in a journey leg `id` like `'1|24983|22|86|18062017'`. `lineName` must be the name of the journey leg's `line.name`. You can get them like this:
```js
const createClient = require('hafas-client')
const vbbProfile = require('hafas-client/p/vbb')
const client = createClient(vbbProfile)
// Hauptbahnhof to Heinrich-Heine-Str.
client.journeys('900000003201', '900000100008', {results: 1})
.then(([journey]) => {
const part = journey.parts[0]
return client.journeyPart(part.id, part.line.name)
})
.then(console.log)
.catch(console.error)
```
With `opt`, you can override the default options, which look like this:
```js
{
when: new Date()
}
```
## Response
*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. The `departureDelay`/`arrivalDelay` fields express how much they differ from the schedule.
As an example, we're going to use the VBB profile:
```js
const createClient = require('hafas-client')
const vbbProfile = require('hafas-client/p/vbb')
const client = createClient(vbbProfile)
client.journeyPart('1|31431|28|86|17122017', 'S9', {when: 1513534689273})
.then(console.log)
.catch(console.error)
```
The response looked like this:
```js
{
id: '1|31431|28|86|17122017',
origin: {
type: 'station',
id: '900000260005',
name: 'S Flughafen Berlin-Schönefeld',
location: {
type: 'location',
latitude: 52.390796,
longitude: 13.51352
},
products: {
suburban: true,
subway: false,
tram: false,
bus: true,
ferry: false,
express: false,
regional: true
}
},
departure: '2017-12-17T18:37:00.000+01:00',
departurePlatform: '13',
destination: {
type: 'station',
id: '900000029101',
name: 'S Spandau',
location: {
type: 'location',
latitude: 52.534794,
longitude: 13.197477
},
products: {
suburban: true,
subway: false,
tram: false,
bus: true,
ferry: false,
express: true,
regional: true
}
},
arrival: '2017-12-17T19:49:00.000+01:00',
line: {
type: 'line',
id: '18299',
name: 'S9',
public: true,
mode: 'train',
product: 'suburban',
symbol: 'S',
nr: 9,
metro: false,
express: false,
night: false,
productCode: 0
},
arrivalPlatform: '2',
direction: 'S Spandau',
passed: [ /* … */ ]
}
```

236
docs/journeys.md Normal file
View file

@ -0,0 +1,236 @@
# `journeys(from, to, [opt])`
`from` and `to` each must be in one of these formats:
```js
// a station ID, in a format compatible to the profile you use
'900000013102'
// an FPTF `station` object
{
type: 'station',
id: '900000013102',
name: 'foo station',
location: {
type: 'location',
latitude: 1.23,
longitude: 3.21
}
}
// a point of interest, which is an FPTF `location` object
{
type: 'location',
id: '123',
name: 'foo restaurant',
latitude: 1.23,
longitude: 3.21
}
// an address, which is an FTPF `location` object
{
type: 'location',
address: 'foo street 1',
latitude: 1.23,
longitude: 3.21
}
```
With `opt`, you can override the default options, which look like this:
```js
{
when: new Date(),
results: 5, // how many journeys?
via: null, // let journeys pass this station
passedStations: false, // return stations on the way?
transfers: 5, // maximum of 5 transfers
transferTime: 0, // minimum time for a single transfer in minutes
accessibility: 'none', // 'none', 'partial' or 'complete'
bike: false, // only bike-friendly journeys
products: {
suburban: true,
subway: true,
tram: true,
bus: true,
ferry: true,
express: true,
regional: true
},
tickets: false // return tickets? only available with some profiles
}
```
## Response
*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. The `departureDelay`/`arrivalDelay` fields express how much they differ from the schedule.
As an example, we're going to use the VBB profile:
```js
const createClient = require('hafas-client')
const vbbProfile = require('hafas-client/p/vbb')
const client = createClient(vbbProfile)
// Hauptbahnhof to Heinrich-Heine-Str.
client.journeys('900000003201', '900000100008', {
results: 1,
passedStations: true
})
.then(console.log)
.catch(console.error)
```
The response may look like this:
```js
[ {
parts: [ {
id: '1|31041|35|86|17122017',
origin: {
type: 'station',
id: '900000003201',
name: 'S+U Berlin Hauptbahnhof',
location: {
type: 'location',
latitude: 52.52585,
longitude: 13.368928
},
products: {
suburban: true,
subway: true,
tram: true,
bus: true,
ferry: false,
express: true,
regional: true
}
},
departure: '2017-12-17T19:07:00.000+01:00',
departurePlatform: '16',
destination: {
type: 'station',
id: '900000024101',
name: 'S Charlottenburg',
location: {
type: 'location',
latitude: 52.504806,
longitude: 13.303846
},
products: {
suburban: true,
subway: false,
tram: false,
bus: true,
ferry: false,
express: false,
regional: true
}
},
arrival: '2017-12-17T19:47:00.000+01:00',
arrivalPlatform: '8',
arrivalDelay: 30,
line: {
type: 'line',
id: '16845',
name: 'S7',
public: true,
mode: 'train',
product: 'suburban',
symbol: 'S',
nr: 7,
metro: false,
express: false,
night: false,
productCode: 0
},
direction: 'S Potsdam Hauptbahnhof',
passed: [ {
station: {
type: 'station',
id: '900000003201',
name: 'S+U Berlin Hauptbahnhof',
location: { /* … */ },
products: { /* … */ }
},
arrival: '2017-12-17T19:06:00.000+01:00',
departure: '2017-12-17T19:07:00.000+01:00'
}, {
station: {
type: 'station',
id: '900000003102',
name: 'S Bellevue',
location: { /* … */ },
products: { /* … */ }
},
arrival: '2017-12-17T19:09:00.000+01:00',
departure: '2017-12-17T19:09:00.000+01:00'
}, /* … */ {
station: {
type: 'station',
id: '900000024101',
name: 'S Charlottenburg',
location: { /* … */ },
products: { /* … */ }
},
arrival: '2017-12-17T19:17:00.000+01:00',
departure: '2017-12-17T19:17:00.000+01:00'
} ]
} ],
origin: {
type: 'station',
id: '900000003201',
name: 'S+U Berlin Hauptbahnhof',
location: { /* … */ },
products: { /* … */ }
},
departure: '2017-12-17T19:07:00.000+01:00',
destination: {
type: 'station',
id: '900000024101',
name: 'S Charlottenburg',
location: { /* … */ },
products: { /* … */ }
},
arrival: '2017-12-17T19:47:00.000+01:00',
arrivalDelay: 30
} ]
```
If you pass `tickets: true`, each `journey` will have a tickets array that looks like this:
```js
[ {
name: 'Berlin Tarifgebiet A-B: Einzelfahrausweis – Regeltarif',
price: 2.8,
tariff: 'Berlin',
coverage: 'AB',
variant: 'adult',
amount: 1
}, {
name: 'Berlin Tarifgebiet A-B: Einzelfahrausweis – Ermäßigungstarif',
price: 1.7,
tariff: 'Berlin',
coverage: 'AB',
variant: 'reduced',
amount: 1,
reduced: true
}, /* … */ {
name: 'Berlin Tarifgebiet A-B: Tageskarte – Ermäßigungstarif',
price: 4.7,
tariff: 'Berlin',
coverage: 'AB',
variant: '1 day, reduced',
amount: 1,
reduced: true,
fullDay: true
}, /* … */ {
name: 'Berlin Tarifgebiet A-B: 4-Fahrten-Karte – Regeltarif',
price: 9,
tariff: 'Berlin',
coverage: 'AB',
variant: '4x adult',
amount: 4
} ]
```

66
docs/locations.md Normal file
View file

@ -0,0 +1,66 @@
# `locations(query, [opt])`
`query` must be an string (e.g. `'Alexanderplatz'`).
With `opt`, you can override the default options, which look like this:
```js
{
fuzzy: true // find only exact matches?
, results: 10 // how many search results?
, stations: true
, addresses: true
, poi: true // points of interest
}
```
## Response
As an example, we're going to use the VBB profile:
```js
const createClient = require('hafas-client')
const vbbProfile = require('hafas-client/p/vbb')
const client = createClient(vbbProfile)
client.locations('Alexanderplatz', {results: 3})
.then(console.log)
.catch(console.error)
```
The response may look like this:
```js
[ {
type: 'station',
id: '900000100003',
name: 'S+U Alexanderplatz',
location: {
type: 'location',
latitude: 52.521508,
longitude: 13.411267
},
products: {
suburban: true,
subway: true,
tram: true,
bus: true,
ferry: false,
express: false,
regional: true
}
}, { // point of interest
type: 'location',
name: 'Berlin, Holiday Inn Centre Alexanderplatz****',
id: '900980709',
latitude: 52.523549,
longitude: 13.418441
}, { // point of interest
type: 'location',
name: 'Berlin, Hotel Agon am Alexanderplatz',
id: '900980176',
latitude: 52.524556,
longitude: 13.420266
} ]
```

77
docs/nearby.md Normal file
View file

@ -0,0 +1,77 @@
# `nearby(latitude, longitude, [opt])`
This method can be used to find stations close to a location. Note that it is not supported by every profile/endpoint.
`latitude` and `longitude` must be GPS coordinates like `52.5137344` and `13.4744798`.
With `opt`, you can override the default options, which look like this:
```js
{
distance: null, // maximum walking distance in meters
poi: false, // return points of interest?
stations: true, // return stations?
}
```
## Response
As an example, we're going to use the VBB profile:
```js
const createClient = require('hafas-client')
const vbbProfile = require('hafas-client/p/vbb')
const client = createClient(vbbProfile)
client.nearby(52.5137344, 13.4744798, {distance: 400})
.then(console.log)
.catch(console.error)
```
The response may look like this:
```js
[ {
type: 'station',
id: '900000120001',
name: 'S+U Frankfurter Allee',
location: {
type: 'location',
latitude: 52.513616,
longitude: 13.475298
},
products: {
suburban: true,
subway: true,
tram: true,
bus: true,
ferry: false,
express: false,
regional: false
},
distance: 56
}, {
type: 'station',
id: '900000120540',
name: 'Scharnweberstr./Weichselstr.',
location: {
type: 'location',
latitude: 52.512339,
longitude: 13.470174
},
products: { /* … */ },
distance: 330
}, {
type: 'station',
id: '900000160544',
name: 'Rathaus Lichtenberg',
location: {
type: 'location',
latitude: 52.515908,
longitude: 13.479073
},
products: { /* … */ },
distance: 394
} ]
```

142
docs/radar.md Normal file
View file

@ -0,0 +1,142 @@
# `radar(north, west, south, east, [opt])`
Use this method to find all vehicles currently in an area. Note that it is not supported by every profile/endpoint.
`north`, `west`, `south` and `eath` must be numbers (e.g. `52.52411`). Together, they form a [bounding box](https://en.wikipedia.org/wiki/Minimum_bounding_box).
With `opt`, you can override the default options, which look like this:
```js
{
results: 256, // maximum number of vehicles
duration: 30, // compute frames for the next n seconds
frames: 3, // nr of frames to compute
}
```
## Response
*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. The `departureDelay`/`arrivalDelay` fields express how much they differ from the schedule.
As an example, we're going to use the VBB profile:
```js
const createClient = require('hafas-client')
const vbbProfile = require('hafas-client/p/vbb')
const client = createClient(vbbProfile)
client.radar(52.52411, 13.41002, 52.51942, 13.41709, {results: 5})
.then(console.log)
.catch(console.error)
```
The response may look like this:
```js
[ {
location: {
type: 'location',
latitude: 52.521508,
longitude: 13.411267
},
line: {
type: 'line',
id: 's9',
name: 'S9',
public: true,
mode: 'train',
product: 'suburban',
symbol: 'S',
nr: 9,
metro: false,
express: false,
night: false
},
direction: 'S Flughafen Berlin-Schönefeld',
trip: 31463,
nextStops: [ {
station: {
type: 'station',
id: '900000029101',
name: 'S Spandau',
location: {
type: 'location',
latitude: 52.534794,
longitude: 13.197477
},
products: {
suburban: true,
subway: false,
tram: false,
bus: true,
ferry: false,
express: true,
regional: true
}
},
arrival: null,
departure: '2017-12-17T19:16:00.000+01:00'
} /* … */ ],
frames: [ {
origin: {
type: 'station',
id: '900000100003',
name: 'S+U Alexanderplatz',
location: { /* … */ },
products: { /* … */ }
},
destination: {
type: 'station',
id: '900000100004',
name: 'S+U Jannowitzbrücke',
location: { /* … */ },
products: { /* … */ }
},
t: 0
}, /* … */ {
origin: { /* Alexanderplatz */ },
destination: { /* Jannowitzbrücke */ },
t: 30000
} ]
}, {
location: {
type: 'location',
latitude: 52.523297,
longitude: 13.411151
},
line: {
type: 'line',
id: 'm2',
name: 'M2',
public: true,
mode: 'train',
product: 'tram',
symbol: 'M',
nr: 2,
metro: true,
express: false,
night: false
},
direction: 'Heinersdorf',
trip: 26321,
nextStops: [ {
station: { /* S+U Alexanderplatz/Dircksenstr. */ },
arrival: null,
departure: '2017-12-17T19:52:00.000+01:00'
}, {
station: { /* Memhardstr. */ },
arrival: '2017-12-17T19:54:00.000+01:00',
departure: '2017-12-17T19:54:00.000+01:00'
}, /* … */ ],
frames: [ {
origin: { /* S+U Alexanderplatz/Dircksenstr. */ },
destination: { /* Memhardstr. */ },
t: 0
}, /* … */ {
origin: { /* Memhardstr. */ },
destination: { /* Mollstr./Prenzlauer Allee */ },
t: 30000
} ]
}, /* … */ ]
```

7
example.js → p/db/example.js
View file

@ -1,7 +1,7 @@
'use strict'
const createClient = require('.')
const dbProfile = require('./p/db')
const createClient = require('../../')
const dbProfile = require('.')
const client = createClient(dbProfile)
@ -9,8 +9,9 @@ const client = createClient(dbProfile)
client.journeys('8011167', '8000261', {results: 1, tickets: true})
// client.departures('8011167', {duration: 1})
// client.locations('Berlin Jungfernheide')
// client.locations('ATZE Musiktheater', {poi: true, addressses: false, fuzzy: false})
// client.locations('Atze Musiktheater', {poi: true, addressses: false, fuzzy: false})
// client.nearby(52.4751309, 13.3656537, {results: 1})
.then((data) => {
console.log(require('util').inspect(data, {depth: null}))
}, console.error)

2
p/db/readme.md
View file

@ -1,6 +1,6 @@
# DB profile for `hafas-client`
[*Deutsche Bahn (DB)*](https://en.wikipedia.org/wiki/Deutsche_Bahn) is the largest German long-distance public transport company. This profile adds *DB*-specific customizations to `hafas-client`.
[*Deutsche Bahn (DB)*](https://en.wikipedia.org/wiki/Deutsche_Bahn) is the largest German long-distance public transport company. This profile adds *DB*-specific customizations to `hafas-client`. Consider using [`db-hafas`](https://github.com/derhuerst/db-hafas#db-hafas), to always get the customized client right away.
## Usage

8
p/vbb/example.js
View file

@ -5,12 +5,14 @@ const vbbProfile = require('.')
const client = createClient(vbbProfile)
// Hauptbahnhof to Charlottenburg
client.journeys('900000003201', '900000024101', {results: 1})
// client.departures('900000013102', {duration: 1})
// client.locations('Alexanderplatz', {results: 2})
// client.nearby(52.5137344, 13.4744798, {distance: 60})
// client.radar(52.52411, 13.41002, 52.51942, 13.41709, {results: 10})
.then((data) => {
console.log(data)
// console.log(require('util').inspect(data, {depth: null}))
}, console.error)
console.log(require('util').inspect(data, {depth: null}))
})
.catch(console.error)

2
p/vbb/readme.md
View file

@ -1,6 +1,6 @@
# VBB profile for `hafas-client`
[*Verkehrsverbund Berlin-Brandenburg (VBB)*](https://en.wikipedia.org/wiki/Verkehrsverbund_Berlin-Brandenburg) is a group of public transport companies, running the public transport network in [Berlin](https://en.wikipedia.org/wiki/Berlin). This profile adds *VBB*-specific customizations to `hafas-client`.
[*Verkehrsverbund Berlin-Brandenburg (VBB)*](https://en.wikipedia.org/wiki/Verkehrsverbund_Berlin-Brandenburg) is a group of public transport companies, running the public transport network in [Berlin](https://en.wikipedia.org/wiki/Berlin). This profile adds *VBB*-specific customizations to `hafas-client`. Consider using [`vbb-hafas`](https://github.com/derhuerst/vbb-hafas#vbb-hafas), to always get the customized client right away.
## Usage

3
package.json
View file

@ -8,7 +8,8 @@
"lib",
"parse",
"format",
"p"
"p",
"docs"
],
"author": "Jannis R <mail@jannisr.de>",
"homepage": "https://github.com/derhuerst/hafas-client",

25
readme.md
View file

@ -2,8 +2,8 @@
**A client for HAFAS public transport APIs**. Sort of like [public-transport-enabler](https://github.com/schildbach/public-transport-enabler), but with a smaller scope. It also [contains customisations](p) for the following transport networks:
- [Deutsche Bahn](https://en.wikipedia.org/wiki/Deutsche_Bahn) - [docs](p/db/readme.md) – [src](p/db/index.js)
- [Berlin public transport](https://en.wikipedia.org/wiki/Verkehrsverbund_Berlin-Brandenburg) - [docs](p/vbb/readme.md) – [src](p/vbb/index.js)
- [Deutsche Bahn](https://en.wikipedia.org/wiki/Deutsche_Bahn) - [docs](p/db/readme.md) – [usage example](p/db/example.js) – [src](p/db/index.js)
- [Berlin public transport](https://en.wikipedia.org/wiki/Verkehrsverbund_Berlin-Brandenburg) - [docs](p/vbb/readme.md) – [usage example](p/vbb/example.js) – [src](p/vbb/index.js)
[![npm version](https://img.shields.io/npm/v/hafas-client.svg)](https://www.npmjs.com/package/hafas-client)
[![build status](https://img.shields.io/travis/derhuerst/hafas-client.svg)](https://travis-ci.org/derhuerst/hafas-client)
@ -163,6 +163,27 @@ The returned [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript
} ]
```
## API
- [`journeys(from, to, [opt])`](docs/journeys.md) – get journeys between locations
- [`journeyPart(ref, name, [opt])`](docs/journey-part.md) – get details for a part of a journey
- [`departures(station, [opt])`](docs/departures.md) – query the next departures at a station
- [`locations(query, [opt])`](docs/locations.md) – find stations, POIs and addresses
- [`nearby(latitude, longitude, [opt])`](docs/nearby.md) – show stations & POIs around
- [`radar(query, [opt])`](docs/radar.md) – find all vehicles currently in a certain area
## Related
- [*Friendly Public Transport Format*](https://github.com/public-transport/friendly-public-transport-format#friendly-public-transport-format-fptf) – A format for APIs, libraries and datasets containing and working with public transport data.
- [`db-hafas`](https://github.com/derhuerst/db-hafas#db-hafas) – JavaScript client for the DB HAFAS API.
- [`vbb-hafas`](https://github.com/derhuerst/vbb-hafas#vbb-hafas) – JavaScript client for Berlin & Brandenburg public transport HAFAS API.
- [`hafas-departures-in-direction`](https://github.com/derhuerst/hafas-departures-in-direction#hafas-departures-in-direction) – Pass in a HAFAS client, get departures in a certain direction.
- [`hafas-collect-departures-at`](https://github.com/derhuerst/hafas-collect-departures-at#hafas-collect-departures-at) – Utility to collect departures, using any HAFAS client.
- [`hafas-rest-api`](https://github.com/derhuerst/hafas-rest-api#hafas-rest-api) – Expose a HAFAS client via an HTTP REST API.
- [List of european long-distance transport operators, available API endpoints, GTFS feeds and client modules.](https://github.com/public-transport/european-transport-operators)
- [Collection of european transport JavaScript modules.](https://github.com/public-transport/european-transport-modules)
## Contributing