diff --git a/docs/changelog.md b/docs/changelog.md
index 7b44fcf6..a8782357 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -1,5 +1,38 @@
 # Changelog
 
+## `4.0.0`
+
+This version is not fully backwords-compatible. Check out [the migration guide](migrating-to-4.md).
+
+### breaking changes 💥
+
+- 1e13cf1/b99ceb2 `parseLocation`: strip leading zeros from IDs
+- a9fd9ff `parseDateTime`: return ISO string/timestamp
+- ca1105f `parseDateTime`: parse timezone offset if given
+- bf3c4c5 require Node `>=8.3.0`
+- bbff1f4 `movement.nextStops` -> `movement.nextStopovers`
+- bad0af8/8b87868/2e12206 rename `station(id)` -> `stop(id)`
+- 96ff59d/0daa1c5/88c78c2 `leg.id` -> `leg.tripId`
+- 3bc2eff `locations()`: default `opt.results` to `5`
+- a1ffad3/cb535cd `parseLine`: remove `line.class` & `line.productCode`
+- fcc53b5/b2b2d11/a1c40ad `journeys()`: return object with `journeys`, `earlierRef`, `laterRef`
+- 61e7d14 `journeys()`: default `opt.transfers` to `-1`
+- d7e439b debugging: `NODE_DEBUG` -> `DEBUG`
+- 8f9b22e `locations()`, `nearby()`: `opt.stations` -> `opt.stops`
+- a972dad `departures()`/`arrivals()`, `locations()`, `nearby()`, `stop()`: `opt.stationLines` -> `opt.linesOfStops`
+- 0e1fcb0/0e1fcb0 `leg.mode: 'walking'` -> `leg.walking: true`
+- 567cc98 DB, INSA, Nah.SH, ÖBB: `nationalExp` -> `nationalExpress`
+- 9c44995 remove `arrival.trip`/`departure.trip` & `movement.trip`
+- eb3ffba/eab850e mark POIs objects with `poi: true`
+- 748f8ce `createThrottledClient` -> `withThrottling`
+- fbde6a1 `createClientWithRetry` -> `withRetrying`
+- 1646173 throw `Error`s -> `TypeError`s
+- 7e39a2f/3b0740d `formerScheduled…` -> `scheduled…`
+
+### bugfixes 🐛
+
+- fcc2a23 ÖBB `journeys()`: fix `opt.results`
+
 ## `3.10.1`
 
 - dafc96a update CMTA credentials
diff --git a/docs/migrating-to-4.md b/docs/migrating-to-4.md
new file mode 100644
index 00000000..6e7bcd3a
--- /dev/null
+++ b/docs/migrating-to-4.md
@@ -0,0 +1,117 @@
+# Migrating to `hafas-client@4`
+
+## If you use Node `6`…
+
+…migrate to Node `8`, sorry. bf3c4c5
+
+## If you use the `journeys()` method…
+
+…use the `journeys` entry from the returned object. fcc53b5
+…rename `leg.id` to `leg.tripId`. 96ff59d
+…use `leg.walking === true` to check for walking legs. 0e1fcb0
+…explicitly pass a value for `opt.transfers` if you want to limit the nr of transfers. 61e7d14
+
+## If you use the `departures()`/`arrivals()` method…
+
+…rename `opt.stationLines` to `opt.linesOfStops`. a972dad
+
+## If you use the `station()` method…
+
+…change the `station(id)` call to `stop(id)`. bad0af8
+
+## If you use the `locations()` method…
+
+…pass `opt.results` if you want more than 5 results. 3bc2eff
+…rename `opt.stationLines` to `opt.linesOfStops`. a972dad
+
+## If you use the `trip()` method…
+
+…rename `leg.nextStops` to `leg.nextStopovers`. bbff1f4
+
+## If you use the `nearby()` method…
+
+…rename `opt.stations` to `opt.stops`. 8f9b22e
+…rename `opt.stationLines` to `opt.linesOfStops`. a972dad
+
+## If you use the `radar()` method…
+
+…rename `movement.nextStops` to `movement.nextStopovers`. bbff1f4
+
+## If you use the DB/INSA/Nah.SH/ÖBB profile…
+
+…rename the product identifier `nationalExp` to `nationalExpress`. 567cc98
+
+## If you use POIs…
+
+…use the `poi: true` flag to check if a location is a POI. eb3ffba
+…add `poi: true` to a location to make it a POI. eb3ffba
+
+## If you use `arrival.trip`/`departure.trip` or `movement.trip`…
+
+…[let us know](https://github.com/public-transport/hafas-client/issues) why you need it. We removed it because it is not reliable. 9c44995
+
+## If you use `hafas-client/throttle`…
+
+…check out the [new and slightly different throttling API](readme.md#throttling-requests). 748f8ce
+
+## If you use `hafas-client/retry`…
+
+…check out the [new and slightly different retrying API](readme.md#retrying-failed-requests). fbde6a1
+
+## If you use `arrival.formerScheduledPlatform`/`departure.formerScheduledPlatform`…
+
+…rename to `arrival.scheduledPlatform`/`departure.scheduledPlatform`. 7e39a2f
+
+## If you use `arrival.formerScheduledWhen`/`departure.formerScheduledWhen`…
+
+…rename to `arrival.scheduledWhen`/`departure.scheduledWhen`. 7e39a2f
+
+## If you use `leg.formerScheduledArrival`/`leg.formerScheduledDeparture`…
+
+…rename to `leg.scheduledArrival`/`leg.scheduledDeparture`. 7e39a2f
+
+## If you use `stopover.formerScheduledArrival`/`stopover.formerScheduledDeparture`…
+
+…rename to `stopover.scheduledArrival`/`stopover.scheduledDeparture`. 7e39a2f
+
+## If you use `stopover.formerScheduledArrivalPlatform`/`stopover.formerScheduledDeparturePlatform`…
+
+…rename to `stopover.scheduledArrivalPlatform`/`stopover.scheduledDeparturePlatform`. 7e39a2f
+
+## If you use `line.class` or `line.productCode`…
+
+…write a custom `parseLine` implementation that exposes them. a1ffad3
+
+An example with the VBB profile:
+
+```js
+const createOrigParseLine = require('hafas-client/parse/line')
+
+const createParseLine = (profile, opt, data) => {
+	const origParseLine = createOrigParseLine(profile, opt, data)
+
+	const parseLine = (p) => {
+		const res = origParseLine(p)
+		res.class = p.cls
+		return res
+	}
+}
+
+const customVbbProfile = Object.assign({}, vbbProfile)
+customVbbProfile.parseLine = createParseLine
+
+const hafas = createHafas(customVbbProfile, 'my-awesome-program')
+```
+
+## If you use `hafas-client` with custom parse functions…
+
+…change the `parseDateTime` to
+
+- return an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string. a9fd9ff
+- have accept an optional `tzOffset`. ca1105f
+
+…change the `parseLocation` to strip leading zeros from stop/station IDs. 1e13cf1
+
+## If you inspect errors thrown by `hafas-client`…
+
+…adapt your code to 1646173.
diff --git a/docs/readme.md b/docs/readme.md
index e1708e9f..77b3ba51 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -11,6 +11,11 @@
 - [`radar(north, west, south, east, [opt])`](radar.md) – find all vehicles currently in a certain area
 - [`reachableFrom(address, [opt])`](reachable-from.md) – get all stations reachable from an address within `n` minutes
 
+## Migrating from an old `hafas-client` version
+
+- [`2` → `3` migration guide](migrating-to-3.md)
+- [`3` → `4` migration guide](migrating-to-4.md)
+
 ## Throttling requests
 
 There's opt-in support for throttling requests to the endpoint.
diff --git a/package.json b/package.json
index da128062..0394c06c 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
 	"name": "hafas-client",
 	"description": "Client for HAFAS public transport APIs.",
-	"version": "3.10.1",
+	"version": "4.0.0",
 	"main": "index.js",
 	"files": [
 		"index.js",
diff --git a/readme.md b/readme.md
index a02ec9fe..1e7272d1 100644
--- a/readme.md
+++ b/readme.md
@@ -24,7 +24,7 @@ HAFAS endpoint | wrapper library | docs | example code | source code
 
 ## Background
 
-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 sets of enabled features.
+There's [a company called HaCon](https://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 sets of enabled features.
 
 `hafas-client` contains all logic for communicating with these, as well as serialising from and parsing to [*Friendly Public Transport Format (FPTF)* `1.2.0`](https://github.com/public-transport/friendly-public-transport-format/blob/1.2.0/spec/readme.md). Endpoint-specific customisations (called *profiles* here) increase the quality of the returned data.