From 3e0bb8e0c33dc5327de2d782d6025a615dec9316 Mon Sep 17 00:00:00 2001
From: Jannis R <mail@jannisr.de>
Date: Fri, 26 Jan 2018 17:23:45 +0100
Subject: [PATCH] location method: docs :memo:

---
 docs/location.md  | 86 +++++++++++++++++++++++++++++++++++++++++++++++
 p/db/example.js   |  1 +
 p/oebb/example.js |  1 +
 p/vbb/example.js  |  1 +
 readme.md         |  1 +
 5 files changed, 90 insertions(+)
 create mode 100644 docs/location.md

diff --git a/docs/location.md b/docs/location.md
new file mode 100644
index 00000000..72cf9a40
--- /dev/null
+++ b/docs/location.md
@@ -0,0 +1,86 @@
+# `location(station)`
+
+`station` must be in one of these formats:
+
+```js
+// a station ID, in a format compatible to the profile you use
+'900000123456'
+
+// an FPTF `station` object
+{
+	type: 'station',
+	id: '900000123456',
+	name: 'foo station',
+	location: {
+		type: 'location',
+		latitude: 1.23,
+		longitude: 3.21
+	}
+}
+```
+
+## Response
+
+As an example, we're going to use the [VBB profile](../p/vbb):
+
+```js
+const createClient = require('hafas-client')
+const vbbProfile = require('hafas-client/p/vbb')
+
+const client = createClient(vbbProfile)
+
+client.location('900000042101') // U Spichernstr.
+.then(console.log)
+.catch(console.error)
+```
+
+The response may look like this:
+
+```js
+{
+	type: 'station',
+	id: '900000042101',
+	name: 'U Spichernstr.',
+	location: {
+		type: 'location',
+		latitude: 52.496581,
+		longitude: 13.330616
+	},
+	products: {
+		suburban: false,
+		subway: true,
+		tram: false,
+		bus: true,
+		ferry: false,
+		express: false,
+		regional: false
+	},
+	lines: [ {
+		type: 'line',
+		id: 'u1',
+		name: 'U1',
+		public: true,
+		class: 2,
+		product: 'subway',
+		mode: 'train',
+		symbol: 'U',
+		nr: 1,
+		metro: false,
+		express: false,
+		night: false },
+		// …
+		{ type: 'line',
+		id: 'n9',
+		name: 'N9',
+		public: true,
+		class: 8,
+		product: 'bus',
+		mode: 'bus',
+		symbol: 'N',
+		nr: 9,
+		metro: false,
+		express: false,
+		night: true
+	} ]
+}
+```
diff --git a/p/db/example.js b/p/db/example.js
index 72742f8c..f740bea9 100644
--- a/p/db/example.js
+++ b/p/db/example.js
@@ -10,6 +10,7 @@ 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.location('8000309') // Regensburg Hbf
 // client.nearby(52.4751309, 13.3656537, {results: 1})
 
 .then((data) => {
diff --git a/p/oebb/example.js b/p/oebb/example.js
index 9c656063..6a04412c 100644
--- a/p/oebb/example.js
+++ b/p/oebb/example.js
@@ -9,6 +9,7 @@ const client = createClient(oebbProfile)
 client.journeys('1291501', '8100002', {results: 1})
 // client.departures('8100002', {duration: 1})
 // client.locations('Salzburg', {results: 2})
+// client.location('8100173') // Graz Hbf
 // client.nearby(47.812851, 13.045604, {distance: 60})
 // client.radar(47.827203, 13.001261, 47.773278, 13.07562, {results: 10})
 
diff --git a/p/vbb/example.js b/p/vbb/example.js
index 089e5af2..079f85c3 100644
--- a/p/vbb/example.js
+++ b/p/vbb/example.js
@@ -9,6 +9,7 @@ const client = createClient(vbbProfile)
 client.journeys('900000003201', '900000024101', {results: 1})
 // client.departures('900000013102', {duration: 1})
 // client.locations('Alexanderplatz', {results: 2})
+// client.location('900000042101') // Spichernstr
 // client.nearby(52.5137344, 13.4744798, {distance: 60})
 // client.radar(52.52411, 13.41002, 52.51942, 13.41709, {results: 10})
 
diff --git a/readme.md b/readme.md
index e27e8d71..91aa8a52 100644
--- a/readme.md
+++ b/readme.md
@@ -34,6 +34,7 @@ npm install hafas-client
 - [`journeyLeg(ref, lineName, [opt])`](docs/journey-leg.md) – get details for a leg 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
+- [`location(id)`](docs/location.md) – get details about a location
 - [`nearby(location, [opt])`](docs/nearby.md) – show stations & POIs around
 - [`radar(query, [opt])`](docs/radar.md) – find all vehicles currently in a certain area