docs: methods, usage examples, more related projects

public-transport · Dec 17, 2017 · 374fd61 · 374fd61
1 parent bcddc49
commit 374fd61
Show file tree

Hide file tree

Showing 12 changed files with 824 additions and 11 deletions.
diff --git a/docs/departures.md b/docs/departures.md
@@ -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'
+} ]
+```
diff --git a/docs/journey-part.md b/docs/journey-part.md
@@ -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: [ /* … */ ]
+}
+```