How to migrate from OTP1 to OTP2

Command Line

The OTP2 command line parameters are different than in OTP1. Use the --help option to get the current documentation, and look at Basic Tutorial - Starting OTP for examples. The possibility to build the graph in 2 steps (streets then transit) is new in OTP2. OTP2 does not support routing on more than one separate transportation network with a single server (referred to as multiple "routers" in OTP1).

File Loading

OTP1 reads and writes all files on the local filesystem, and no other data-source is supported. In OTP2 we support accessing cloud storage. So far support for Google Cloud Storage has been added and we plan to add support for AWS S3 as well. Config files (otp-config.json, build-config.json, router-config.json) must be read from the local file system, while other files can be read/written from either the local filesystem or cloud storage. OTP2 supports mixing any supported data sources.

OTP1 loads input data files (DEM, OSM, GTFS, NeTEx) based on the suffix (file extension). But for GTFS files OTP1 also opens the zip-file and looks for stops.txt. OTP2 identifies GTFS files by the name only: it will detect any zip-file or directory that contains "gtfs" as part of the name. All file types in OTP2 are resolved by matching the name with a regexp pattern. You can configure the patterns in the build-config.json if the defaults do not suit you.

OTP2 does not support multiple routers (separate named networks to route on), but you can load as many GTFS and/or NeTEx feeds as you want into a single routable network in a single instance of OTP2.

Build Config

OTP will log all unrecognized parameters when starting up. Make sure to investigate all log events of this type:

16:18:46.911 WARN ( Unexpected config parameter: 'fetchElevationUS:false' in 'build-config.json'. Is the spelling correct?

New parameters

Parameters whose names were changed

These parameters are no longer supported

Since v2.2, data feeds can be configured individually by using the transitFeeds, osm and dem nodes.

Since v2.2, osmWayPropertySet was renamed osmTagMapping and is part of the individual osm source. The driving direction and intersection cost model were decoupled for the tag mapping and can be configured using drivingDirection and intersectionTraversalModel inside routingDefaults.

OTP2 records the "parentStation" relationship between stops and stations in its internal transit model, based on the GTFS and/or NeTEx input. This enables OTP to search from all stop in a station without walking/waiting when the request from/to input field is a station id. There is no way to automatically infer this parent station relationship based on geographic proximity in OTP2.

Transfers in OTP2 are generated based on the stop location and the OSM data or GTFS Pathways. In future versions of OTP2 we also want to support generating simple transfers based on "line-of-sight" if no pathways or OSM data exist. See issue #3204.

Cleaning and patching input data is NOT a core feature of OTP, but anyone is welcome to implement a sandbox plugin to patch data. So, if any of the features above are needed they can be ported from OTP1 into an OTP2 sandbox feature.

Router Config

See the Router Configuration for a description of the new and existing routing parameters.

New parameters

These parameters are no longer supported


Trip Planning

Support for XML as a request/response format is removed. The only supported format is JSON. Some of these parameters may only be available as defaultRequest configuration parameters.

Query parameter changes

A lot of the query parameters in the REST API are ignored/deprecated, see the RoutingRequest and the RoutingResource class for the documentation on what is now supported in OTP2.

Parameters missing in OTP2 but intended to be reintroduced

Some features in OTP1 will not be present upon launch in OTP2, and they are proposed to be removed permanently from OTP2, but may require some development to support valid important cases:

Parameters that have changed

New parameters in OTP2

These parameters are no longer supported


In OTP1 most clients provided a way to break results into pages by looking at the trips returned and issuing another request, supplying something like the last-depature-time + 1 minute to the next request. This yields another batch of trips to show to the user. In OTP2 the recommended way to do this is to use the new TripPlan metadata returned by the router call.

In OTP 2.0 the server returned a set of parameters(searchWindowUsed, nextDateTime, and prevDateTime), but in OTP 2.1 we have switched to a token-based approach to paging. In the response there is a next/previous cursor. Duplicate the request and set the new pageCursor to go the next/previous page.

Response changes

Changes to the Index API


The returned data structure is changed and more info is available.


The AlertPatcher, which was under the /patch path, is removed. In order to update alerts, please use a GTFS-RT Service Alert updater instead. An example of a simple service for producing static GTFS-RT Service Alert feed from JSON is manual-gtfsrt.

Querying for alerts has been moved under the index API, where /alerts can be appended to stop, route, trip and pattern.


The analyst API endpoints have been removed.


The scripting API endpoint has been removed.