docs: update FPTF link, minor improvements

readme.md

@@ -1,9 +1,9 @@
 # hafas-client
 
-**A client for HAFAS public transport APIs**. Sort of like [public-transport-enable](https://github.com/schildbach/public-transport-enabler), but with a smaller scope. It also contains customisations for the following transport networks:
+**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 for the following transport networks:
 
-- [Deutsche Bahn](https://en.wikipedia.org/wiki/Deutsche_Bahn) – [src](p/db/index.js)
+- [Deutsche Bahn](https://en.wikipedia.org/wiki/Deutsche_Bahn) – [src at `p/db`](p/db/index.js)
-- [Berlin public transport](https://en.wikipedia.org/wiki/Verkehrsverbund_Berlin-Brandenburg) – [src](p/vbb/index.js)
+- [Berlin public transport](https://en.wikipedia.org/wiki/Verkehrsverbund_Berlin-Brandenburg) – [src at `p/vbb`](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)
@@ -15,7 +15,7 @@
 
 There's [a company called HaCon](http://hacon.de) that sells [a public transport management system called HAFAS](https://de.wikipedia.org/wiki/HAFAS). It is [used by companies all over Europe](https://gist.github.com/derhuerst/2b7ed83bfa5f115125a5) to serve routing and departure information for apps. All those endpoints are similar, with the same terms and API routes, but have slightly different options, filters and enable features.
 
-`hafas-client` contains all logic for communicating with these, as well as serialising from and parsing to [FPTF](https://github.com/public-transport/friendly-public-transport-format). Endpoint-specific customisations increase the quality of the returned data.
+`hafas-client` contains all logic for communicating with these, as well as serialising from and parsing to [*Friendly Public Transport Format (FPTF)* `1.0.1`](https://github.com/public-transport/friendly-public-transport-format/blob/1.0.1/spec/readme.md). Endpoint-specific customisations (called "profiles" here) increase the quality of the returned data.
 
 
 ## Installing
@@ -31,6 +31,7 @@ npm install hafas-client
 const createClient = require('hafas-client')
 const dbProfile = require('hafas-client/p/db')
 
+// create a client with Deutsche Bahn profile
 const client = createClient(dbProfile)
 
 // Berlin Jungfernheide to München Hbf
@@ -39,116 +40,126 @@ client.journeys('8011167', '8000261', {results: 1})
 .catch(console.error)
 ```
 
+The returned [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/promise) will resolved with an array of one `journey` in the [*FPTF* `1.0.1`](https://github.com/public-transport/friendly-public-transport-format/blob/1.0.1/spec/readme.md).
+
 ```js
 [ {
-	origin: {
-		type: 'station',
-		id: '8089100',
-		name: 'Berlin Jungfernheide (S)',
-		coordinates: {
-			latitude: 52.530291,
-			longitude: 13.299451
-		},
-		products: { /* … */ }
-	},
-	departure: '2017-11-13T01:00:00Z',
-
-	destination: {
-		type: 'station',
-		id: '8000261',
-		name: 'München Hbf',
-		coordinates: {
-			latitude: 48.140364,
-			longitude: 11.558735
-		},
-		products: { /* … */ }
-	},
-	arrival: '2017-11-13T09:39:00Z',
-
 	parts: [ {
-		id: '1|1436339|0|80|12112017',
+		id: '1|100067|48|81|17122017',
-
 		origin: {
 			type: 'station',
 			id: '8089100',
 			name: 'Berlin Jungfernheide (S)',
-			coordinates: {
+			location: {
+				type: 'location',
 				latitude: 52.530291,
 				longitude: 13.299451
 			},
-			products: {
+			products: { /* … */ }
-				nationalExp: false,
-				national: false,
-				regionalExp: false,
-				regional: true,
-				suburban: true,
-				bus: true,
-				ferry: false,
-				subway: true,
-				tram: false,
-				taxi: false
-			}
 		},
-		departure: '2017-11-13T00:50:00Z',
+		departure: '2017-12-17T17:05:00.000+01:00',
-		departurePlatform: '6',
+		departurePlatform: '5',
-
 		destination: {
 			type: 'station',
-			id: '8089047',
+			id: '8089118',
-			name: 'Berlin Westkreuz',
+			name: 'Berlin Beusselstraße',
-			coordinates: {
+			location: { /* … */ },
-				latitude: 52.500752,
+			products: { /* … */ }
-				longitude: 13.283854
-			},
-			products: {
-				nationalExp: false,
-				national: false,
-				regionalExp: false,
-				regional: true,
-				suburban: true,
-				bus: true,
-				ferry: false,
-				subway: false,
-				tram: false,
-				taxi: false
-			}
 		},
-		arrival: '2017-11-13T00:57:00Z',
+		arrival: '2017-12-17T17:08:00.000+01:00',
-		delay: 0,
+		arrivalPlatform: '1',
-
 		line: {
 			type: 'line',
-			name: 'S 42',
+			id: '41172',
+			name: 'S 41',
+			public: true,
 			mode: 'train',
 			product: 'suburban',
 			class: 16,
-			productCode: 4,
+			productCode: 4
-			productName: 's'
 		},
-		direction: 'Ringbahn <-',
+		direction: 'Ringbahn ->'
-		arrivalPlatform: '12'
+	}, /* … */ {
+		origin: {
+			type: 'station',
+			id: '730749',
+			name: 'Berlin Hauptbahnhof (S+U), Berlin',
+			location: {
+				type: 'location',
+				latitude: 52.526461,
+				longitude: 13.369378
+			},
+			products: { /* … */ }
+		},
+		departure: '2017-12-17T17:25:00.000+01:00',
+		destination: {
+			type: 'station',
+			id: '8098160',
+			name: 'Berlin Hbf (tief)',
+			location: { /* … */ },
+			products: { /* … */ }
+		},
+		arrival: '2017-12-17T17:33:00.000+01:00',
+		mode: 'walking',
+		public: true
 	}, {
-		id: '1|332491|0|80|12112017',
+		id: '1|70906|0|81|17122017',
-
+		origin: {
-		origin: { /* … */ },
+			type: 'station',
-		departure: '2017-11-13T01:05:00Z',
+			id: '8098160',
-		departurePlatform: '3',
+			name: 'Berlin Hbf (tief)',
-
+			location: { /* … */ },
-		destination: { /* … */ },
+			products: { /* … */ }
-		arrival: '2017-11-13T01:18:00Z',
+		},
-		delay: 0,
+		departure: '2017-12-17T17:37:00.000+01:00',
-
+		departurePlatform: '1',
+		destination: {
+			type: 'station',
+			id: '8000261',
+			name: 'München Hbf',
+			location: { /* … */ },
+			products: { /* … */ }
+		},
+		arrival: '2017-12-17T22:45:00.000+01:00',
+		arrivalPlatform: '13',
 		line: { /* … */ },
-		direction: 'Berlin Ostbahnhof'
+		direction: 'München Hbf'
-	}, {
+	} ],
-		origin: { /* … */ },
+	origin: {
-		departure: '2017-11-13T01:18:00Z',
+		type: 'station',
-		destination: { /* … */ },
+		id: '8089100',
-		arrival: '2017-11-13T01:26:00Z',
+		name: 'Berlin Jungfernheide (S)',
-		mode: 'walking'
+		location: {
-	}, {
+			type: 'location',
-		 /* … */
+			latitude: 52.530291,
-	} ]
+			longitude: 13.299451
+		},
+		products: {
+			nationalExp: false,
+			national: false,
+			regionalExp: false,
+			regional: true,
+			suburban: true,
+			bus: true,
+			ferry: false,
+			subway: true,
+			tram: false,
+			taxi: false
+		}
+	},
+	departure: '2017-12-17T17:05:00.000+01:00',
+	destination: {
+		type: 'station',
+		id: '8000261',
+		name: 'München Hbf',
+		location: { /* … */ },
+		products: { /* … */ }
+	},
+	arrival: '2017-12-17T22:45:00.000+01:00',
+	price: {
+		amount: null,
+		hint: 'No pricing information available.'
+	}
 } ]
 ```