diff --git a/docs/journey-leg.md b/docs/journey-leg.md
index f54b0e6e..e21293c7 100644
--- a/docs/journey-leg.md
+++ b/docs/journey-leg.md
@@ -118,4 +118,66 @@ The response looked like this:
 }
 ```
 
-If you pass `polyline: true`, the leg will have a `polyline` field, containing an encoded shape. You can use e.g. [`@mapbox/polyline`](https://www.npmjs.com/package/@mapbox/polyline) to decode it.
+### `polyline` option
+
+If you pass `polyline: true`, the leg will have a `polyline` field, containing a [GeoJSON](http://geojson.org) [`FeatureCollection`](https://tools.ietf.org/html/rfc7946#section-3.3) of [`Point`s](https://tools.ietf.org/html/rfc7946#appendix-A.1). Every `Point` next to a station will have `properties` containing the station's metadata.
+
+We'll look at an example for *U6* from *Alt-Mariendorf* to *Alt-Tegel*, taken from the [VBB profile](../p/vbb):
+
+```js
+{
+	type: 'FeatureCollection',
+	features: [
+		{
+			type: 'Feature',
+			properties: {
+				type: 'station',
+				id: '900000070301',
+				name: 'U Alt-Mariendorf',
+				/* … */
+			},
+			geometry: {
+				type: 'Point',
+				coordinates: [13.3875, 52.43993] // longitude, latitude
+			}
+		},
+		/* … */
+		{
+			type: 'Feature',
+			properties: {
+				type: 'station',
+				id: '900000017101',
+				name: 'U Mehringdamm',
+				/* … */
+			},
+			geometry: {
+				type: 'Point',
+				coordinates: [13.38892, 52.49448] // longitude, latitude
+			}
+		},
+		/* … */
+		{
+			// intermediate point, without associated station
+			type: 'Feature',
+			properties: {},
+			geometry: {
+				type: 'Point',
+				coordinates: [13.28599, 52.58742] // longitude, latitude
+			}
+		},
+		{
+			type: 'Feature',
+			properties: {
+				type: 'station',
+				id: '900000089301',
+				name: 'U Alt-Tegel',
+				/* … */
+			},
+			geometry: {
+				type: 'Point',
+				coordinates: [13.28406, 52.58915] // longitude, latitude
+			}
+		}
+	]
+}
+```
diff --git a/docs/journeys.md b/docs/journeys.md
index 1b6d0051..016f052c 100644
--- a/docs/journeys.md
+++ b/docs/journeys.md
@@ -262,4 +262,4 @@ departure of last journey 2017-12-17T19:07:00.000+01:00
 departure of first (later) journey 2017-12-17T19:19:00.000+01:00
 ```
 
-If you pass `polylines: true`, each journey leg will have a `polyline` field, containing an encoded shape. You can use e.g. [`@mapbox/polyline`](https://www.npmjs.com/package/@mapbox/polyline) to decode it.
+If you pass `polylines: true`, each journey leg will have a `polyline` field. Refer to [the section in the `journeyLeg()` docs](journey-leg.md#polyline-option) for details.
diff --git a/docs/radar.md b/docs/radar.md
index ab00b767..e42155c0 100644
--- a/docs/radar.md
+++ b/docs/radar.md
@@ -163,4 +163,4 @@ The response may look like this:
 }, /* … */ ]
 ```
 
-If you pass `polylines: true`, each result will have a `polyline` field, containing an encoded shape. You can use e.g. [`@mapbox/polyline`](https://www.npmjs.com/package/@mapbox/polyline) to decode it.
+If you pass `polylines: true`, each journey leg will have a `polyline` field, as documented in [the corresponding section in the `journeyLeg()` docs](journey-leg.md#polyline-option), with the exception that station info is missing.