opentripplanner: getting started
Marcus Young, modified by Malcolm Morgan and Robin Lovelace
This vignette is an introduction to OpenTripPlanner (OTP) - an open-source and cross-platform multi-modal route planner written in Java. It uses imported OpenStreetMap (OSM) data for routing on the street and path network and supports multi-agency public transport routing through imported General Transit Feed Specification (GTFS) feeds. It can also apply a digital elevation model to the OSM street network, allowing, for example, cycle-friendly routes to be requested. OTP has a web front-end that can be used by end-users and a sophisticated routing API.
OTP works worldwide as long as there is OSM map coverage in the area. Support for transit timetables and elevation calculations are dependant on the available data. For more information on getting data see the getting data for OTP section.
A significant advantage of running your own multi-modal route planner is the ability to carry out analysis using amended transport data. Services such as Google Maps or TransportAPI are based on current public transport schedules and the existing road network. OTP enables you to modify transit schedules and/or make changes to the underlying street network. By editing a local copy of OSM, you can model the effects of opening new roads, closing roads or imposing other restrictions. You can also look back in time. For example, you might want to examine the effect of reductions in rural bus services on the accessibility of health facilities. To do this, you would need a network with bus schedules as they were in previous years.
You will need to have installed R, RStudio, and Java 8. For more details on the required software, see the prerequisites vignette included with this package.
Install the stable version of the package from CRAN as follows:
install.packages("opentripplanner") # Install Package library(opentripplanner) # Load Package
Or you can install the development version from GitHub using the remotes package:
remotes::install_github("ropensci/opentripplanner") # Install Package library(opentripplanner) # Load Package
Downloading OTP and the demonstration data
We will build an example graph for the Isle of Wight using some example data provided for the package. A graph is what OTP uses to find routes, and must be built out of the raw data provided. Please note the demo data has been modified for teaching purposes and should not be used for analysis.
Creating a folder to store OTP and its data
OTP expects its data to be stored in a specific structure, see building your own otp graph for more details. We will make a folder called OTP in the temporary directory.
path_data <- file.path(tempdir(), "OTP") dir.create(path_data)
You may wish to change this to keep your files after closing R. Otherwise you will need to download your files and build your graph every time. For example:
path_data <- file.path("C:/Users/Public", "OTP") dir.create(path_data)
As of version 0.3 the
otp_dl_jar function will download and cache the OTP jar file. So you can simply get the path to the OTP JAR file like this:
path_otp <- otp_dl_jar()
otp_dl_jar will first check its internal cache for the JAR file and only download it if it is unavailable.
If you wish to specify the location the JAR file is saved (as in version 0.2) use:
path_otp <- otp_dl_jar(path_data, cache = FALSE)
Downloading Example Data
otp_dl_demo function downloads the demonstration data and puts it in the correct structure.
Building an OTP Graph
Now we can build the graph. This code will create a new file
Graph.obj that will be saved in the location defined by
log1 <- otp_build_graph(otp = path_otp, dir = path_data)
By default, R will assign OTP 2GB of memory to build the graph. For larger areas, you may need more memory. You can use the
memory argument to set the memory allocation in MB. For example, to allocate 10GB, you would use:
log1 <- otp_build_graph(otp = path_otp, dir = path_data, memory = 10240)
Note that you cannot allocate more memory than you have RAM, and if you use 32 Bit Java you cannot allocate more than 3GB. It is possible to run OTP in just 1GB of memory for very small areas (including the demo dataset).
Launch OTP and load the graph
The next step is to start up your OTP server, running the router called ‘default’. OTP will load the graph you created into memory, and you will then be able to plan multi-modal routes using the web interface. Run the following command:
log2 <- otp_setup(otp = path_otp, dir = path_data)
OTP has a built-in web server called Grizzly which runs on port 8080 (http) and 8081 (https). If you have another application running on your computer that uses these ports then you will need to specify alternative ports using the
securePort options, for example:
log2 <- otp_setup(otp = path_otp, dir = path_data, port = 8801, securePort = 8802)
It should only take a minute or two for OTP to load the graph and start the Grizzly server. If it has worked, you should see the message:
OTP is ready to use, and R will open your web browser at the OTP.
You can also access the web interface using the URL:
http://localhost:8080. You can now zoom into the Isle of Wight area and request a route by setting an origin and a destination directly on the map (by right-clicking your mouse). You can specify travel dates, times and modes using the ‘Trip Options’ window (see Figure). You can change the background map from the layer stack icon at the top right.
Note: The web interface does not work correctly in Internet Explorer - use Firefox or Chrome.
Connecting to the OTP from R
Now you have the OTP running on your computer you can let R connect to the OTP.
otp_connect() creates an OTP connection object which will allow R to connect to the OTP. By default, your local timezone is used, but if you are not in the UK, you need to specify the UK timezone to get the correct results with the demo data.
otpcon <- otp_connect(timezone = "Europe/London")
The connection is created and tested, and a message will be returned, saying if the connection exists or not. If you have not used the default settings, such as a different
port you can specify those settings in
otpcon <- otp_connect(hostname = "localhost", router = "default", port = 8801)
You can also use the
otp_connect() function to make a connection to OTP on a remote server. If the server uses a non-standard structure for the API, you can provide the full URL directly to
otp_connect(). See the
otp_connect() help for more details.
otpcon <- otp_connect(url = "https://api.digitransit.fi/routing/v1/routers/hsl")
Getting a route from the OTP
Now we can use R to get a route from the OTP. OTP accepts pairs of longitude/latitude coordinates for a
fromPlace (start of the journey) and
toPlace (end of the journey).
If you have the
tmap package installed, you can view the route using.
Stopping the OTP
As the OTP is running in Java, it will continue to run after you close R.
You can stop the OTP running using the command. NOTE: This will stop all running JAVA applications!
Congratulations, you now have your own multi-modal router planner!
Building your own OTP Graph
If you want to build your own graph for a different location, follow these steps, and change your
path_data variable to the folder with your data.
An OTP graph specifies every location in the region covered and how to travel between them, and is compiled by OTP using OSM data for the street and path network (used for walking, bicycle, and drive modes) and GTFS data for transit scheduling.
Our first task is to create the folder and file structure expected by OTP. This is a base directory called
otp which contains a sub-directory called
graphs. Directories created under
graphs are known as OTP routers and contain all the files required to build a graph. A single OTP instance can host several routers, for example, covering different regions.
The basic file structure is shown below.
/ otp # Your top folder for storing all OTP data /graphs /default # Subfolder with the name of the router osm.pbf # Required OSM road map router-config.json # Optional config file build-config.json # Optional config file gtfs.zip # Optional GTFS data dem.tif # Optional Elevation data
router-config.json is read when the OTP server is started, while
build-config.json is read during the graph building stage. For more information on the config files, see the advanced features vignette.
OTP supports multiple routes by having them in separate folders. For example:
/ otp # Your top folder for storing all OTP data /graphs /london # router called london osm.pbf # map of London /manchester # router called manchester osm.pbf # map of Manchester
Having multiple routers may be useful to support different regions, or different scenarios, e.g. past, present, future.
Each router requires its own graph via
otp_build_graph() but only one version of the OTP jar files is needed (i.e.
otp_dl_jar()) Each route must be started via
otp_setup() before use. While it is technically possible to run multiple routers simultaneously, it is not recommended for performance reasons.
Getting Data for OTP
To use OTP on your local computer, you will need data about your location of interest, such as where the roads are, what is the public transport timetable etc.
Road Map Data
OTP uses road maps from the Open Street Map (OSM) in the .osm or .pbf format. OSM is a free map that anybody can edit. You can download all or part of the OSM from Geofabrik.
Note that OTP only really needs the road network from the OSM, but the Geofabrik downloads include non-road data such as buildings, parks, water etc. So for large areas, you may wish to remove unneeded data from the file before building the graph. You can do this using osmconvert and osmfilter. These are command-line utilities for editing large OSM files and are documented on the OSM Wiki. For small areas (e.g. city scale) this is not necessary.
Public Transport Timetables
OTP can use public transport timetable data in the GTFS format. You can find GTFS data for many regions at transitland. For users in the UK see UK2GTFS
You can add terrain information to your routes, especially useful for walking and cycling, using GeoTIFF images. You can find worldwide elevation data from NASA.
Warning It is common for GeoTIFF to have a no data value often the maximum possible value. OTP can misinterpret this as an elevation value. So set your no data values in your elevation data to something more plausible like 0.
Note that OTP does not support all types of GeoTIFF compression so you may have to change the compression type of the image if you are experiencing problems.