From f6040de6fbb97c0e6f90ae181eef1da403ba91c0 Mon Sep 17 00:00:00 2001
From: Jannis R <mail@jannisr.de>
Date: Sun, 26 Aug 2018 18:36:15 +0200
Subject: [PATCH] docs for readableFrom :memo:

---
 docs/reachable-from.md | 92 ++++++++++++++++++++++++++++++++++++++++++
 docs/readme.md         |  1 +
 2 files changed, 93 insertions(+)
 create mode 100644 docs/reachable-from.md

diff --git a/docs/reachable-from.md b/docs/reachable-from.md
new file mode 100644
index 00000000..bea5fd56
--- /dev/null
+++ b/docs/reachable-from.md
@@ -0,0 +1,92 @@
+# `reachableFrom(location, [opt])`
+
+This method can be used to compute the area around a location that is reachable within a certain time. This concept is called [isochrone diagram](https://en.wikipedia.org/wiki/Isochrone_map#Transportation_planning).
+
+*Note*: It appears that HAFAS cannot generate actual isochrones, but a list of reachable stations, which you can estimate the isochrone(s) from.
+
+`location` must be an [*FPTF* `location` object](https://github.com/public-transport/friendly-public-transport-format/blob/1.1.1/spec/readme.md#location-objects).
+
+With `opt`, you can override the default options, which look like this:
+
+```js
+{
+	when: new Date(),
+	maxTransfers: 5, // maximum of 5 transfers
+	maxDuration: 20, // maximum travel duration in minutes
+	products: {
+		// These entries may vary from profile to profile!
+		suburban: true,
+		subway: true
+		// …
+	}
+}
+```
+
+## Response
+
+`reachableFrom(loc, [opt])` returns an array, in which each item has a `duration` and an array of [*Friendly Public Transport Format* `1.1.1`](https://github.com/public-transport/friendly-public-transport-format/tree/1.1.1) stations.
+
+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, 'my-awesome-program')
+
+client.reachableFrom({
+	type: 'location',
+	address: '13353 Berlin-Wedding, Torfstr. 17',
+	latitude: 52.541797,
+	longitude: 13.350042
+}, {
+	maxDuration: 10 // minutes
+})
+.then(console.log)
+.catch(console.error)
+```
+
+The response may look like this:
+
+```js
+[
+	{
+		duration: 2,
+		stations: [
+			{
+				type: 'stop',
+				id: '900000009101',
+				name: 'U Amrumer Str.',
+				location: {type: 'location', latitude: 52.542201, longitude: 13.34953},
+				products: { /* … */ }
+			}
+		]
+	}, {
+		duration: 3,
+		stations: [
+			{
+				type: 'stop',
+				id: '900000001201',
+				name: 'S+U Westhafen',
+				location: {type: 'location', latitude: 52.536179, longitude: 13.343839},
+				products: { /* … */ }
+			}
+			// …
+		]
+	},
+	// …
+	{
+		duration: 10,
+		stations: [
+			{
+				type: 'stop',
+				id: '900000001203',
+				name: 'Döberitzer Str.',
+				location: {type: 'location', latitude: 52.530668, longitude: 13.36811},
+				products: { /* … */ }
+			}
+			// …
+		]
+	}
+]
+```
diff --git a/docs/readme.md b/docs/readme.md
index 9c85bce2..032e20a3 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -9,6 +9,7 @@
 - [`station(id, [opt])`](station.md) – get details about a station
 - [`nearby(location, [opt])`](nearby.md) – show stations & POIs around
 - [`radar(north, west, south, east, [opt])`](radar.md) – find all vehicles currently in a certain area
+- [`reachableFrom(location, [opt])`](reachable-from.md) – get all stations reachable from a location within `n` minutes
 
 ## Writing a profile