In this guide, we explain the step by step procedure to setup 'SmartPlannerEngine' engine.

OpenTripPlanner (OTP) is an open source multi-modal trip planner which runs on Linux, Mac, Windows, or potentially any platform with a Java virtual machine.

In order to build OTP locally from its source code, it is required to install the following software/tools/framework.

• Git, a version control system
• Java Development Kit (>=7)
• Maven, a build and dependency management system

Create a 'smartplanner-engine' directory and set environment variable OTP_HOME

..\..\> mkdir smartplanner-engine
(WINDOWS) set OTP_HOME  = <path to smartplanner-engine directory>
(LINUX) export OTP_HOME = <path to smartplanner-engine directory>

In the later part of tutorial, $OTP_HOME is used as reference. One requires a reliable internet connection so that Maven can fetch all of OTP's dependencies (the libraries it uses):

cd $OTP_HOME
git clone -b sco-0.15.0 https://github.com/smartcommunitylab/OpenTripPlanner.git

Then switch to the cloned 'OpenTripPlanner' repository directory and start build procedure. Please confirm that you are on the 'sco-0.15.0' branch:

cd OpenTripPlanner 
git status
On branch sco-0.15.0
Your branch is up-to-date with 'origin/sco-0.15.0'. 
nothing to commit, working directory clean
mvn clean package

Maven should then be able to download all the libraries and other dependencies necessary to compile OTP. If all goes well you should see a success message like the following:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 42.164s
[INFO] Finished at: Tue Jun 18 19:35:48 CET 2017
[INFO] Final Memory: 88M/695M
[INFO] ------------------------------------------------------------------------

This build process should produce a JAR file 'otp-1.1.0-SNAPSHOT' in the target/ directory which contains all the compiled OTP classes and their dependencies (the external libraries they use).

One can skip step 1.1 and directly download the binary otp.jar file from here:

https://github.com/smartcommunitylab/OpenTripPlanner/releases/download/otp-0.15.0/otp.zip

Create directory inside to the ${OTP_HOME}. Create 'lib' directory inside to the ${OTP_HOME}. The directory structure should become like the following:

${OTP_HOME}
 |- trentino
 `- lib

In case of source build, copy from 'target' directory 'otp-1.1.0-SNAPSHOT' file inside to the '${OTP_HOME}/lib' folder and rename it as otp.jar. In case one has downloaded the pre-build jars, simply unzip the distribution file(otp.zip) and copy the extracted 'otp.jar' file inside to the '${OTP_HOME}/lib' folder.

Routing graph is a graphical representation of network of paths and given the input constraints invoke routing algorithm to find the best path. The OTP uses data from many sources:

• Transit data from GTFS

• Street data from OpenStreetMap (For more information about how to download/edit osm data for your region and use it during routing graph build phase see here.

• (Optional) Elevation data from the National Elevation Dataset or Geographical model (For more information about how to generate elevation data for your region and use it during routing graph build phase see here

Each data source has its own configuration options.

For each router, it is required to have the routing graph (Graph.obj) file inside router folder for e.g. ${OTP_HOME}/ as shown below

smartplanner-engine
 |- trentino
 |  `-Graph.obj
 `- lib

In the next section(Build Graph) you will see how the routing graph(Graph.obj) will get generated inside to the {router} directory.

First you'll need GTFS data to build a transit network. Transport agencies throughout the world provide GTFS schedules to the public. Copy the GTFS files of your region inside to the $OTP_HOME/{router} directory. The file's name must end in .zip for OTP to detect it. It is required to save the file with the following name convention {agencyId}.zip.

smartplanner-engine
 |- trentino
 |  |-12.zip
 |  |-16.zip
 |  |-17.zip
 |  |-32.zip
 |  `-16.zip
 |- lib
 |  `-otp.jar

(Important)

• Please make sure that GTFS file must specify a unique agency identifier 'AgencyId' in the agency.txt file, which must not conflict with other gtfs 'agencyId' in the same routing context.
• As stated before the name of gtfs file must obey the name convention {agencyid}.zip, where agencyId is the one specified in agency.txt file.
• Please make sure that routes.txt file must have 'agencyId' field.
• Please validate the GTFS file to make sure it meets all the requirements of GTFS specification using the feed validator tool.

https://github.com/google/transitfeed/wiki/FeedValidator

You'll also need OpenStreetMap data to build a road network for walking, cycling, and driving. Download OSM PBF data for the same geographic region as your GTFS feed and put it inside the folder along with GTFS. The data can be in .osm or .pbf format.

Each router within that instance is configured using two other JSON files placed alongside the input files (OSM, GTFS etc.) in the router's directory. These router-level config files are named build-config.json and router-config.json. Each configuration option within each of these files is optional. If any option or an entire file is missing, reasonable defaults will be applied.

Create build.config file inside to the ${OTP_HOME}/{router} folder. The OTP during the graph building phase reads this configuration file to ovveride default router build configuration.

{
 transit:true,
 parentStopLinking:true,
 stationTransfers:true,
 subwayAccessTime:2.0,
 streets:true,
 embedRouterConfig:true,
 areaVisibility:true,
 matchBusRoutesToStreets:false,
 fetchElevationUS:false
}

subwayAccessTime: the boarding locations for some modes of transport such as subways can be slow to reach from the street. When planning a trip, we need to allow additional time to reach these locations to properly inform the passenger. For example, this helps avoid suggesting short bus rides between two subway rides as a way to improve travel time. You can specify how long it takes to reach a subway platform. One such property is configured using 'subwayAccessTime' as shown in above snippet.

stationTransfers: allows tranferring within stations. During the graph build, OTP create preferential connections between each pair of stops in the same station to favor in-station transfers:

This section covers all options that can be set for each router using the router-config.json file. These options can be applied by the OTP server without rebuilding the graph. Create router.config file inside to the ${OTP_HOME}/{router} folder. The OTP during the launch phase read this configuration file to override default routing configuration.

{
 routingDefaults: {
  transitIndex: true
 }
}

transitIndex: enables 'Transit Index' RESTful API that provides information derived from the input GTFS feed(s). Examples include routes serving a particular stop, upcoming vehicles at a particular stop, upcoming stops on a given trip, etc. This API is complemented with additional operations at the level of smartplanner engine.

Start the graph build process by running from ${OTP_HOME} directory:

java -Xmx2G -Duser.timezone=Europe/Rome -jar lib/otp.jar --basePath . --build <router>

Note: replace with the one in your routing context for e.g. trentino, bilbao etc. GTFS and OSM data sets are often very large, and OTP is relatively memory-hungry. You will need at least 1GB of memory, and several gigabytes for larger inputs. One can tune the -Xmx parameter as per the context. In case of large data extracts it can be set to 4G.

Note: It will take sometime to build the routing graph (Graph.obj).

Copy the following command and create script files for LINUX(start-otp.sh) and WINDOWS(start-otp.bat) respectively inside to '$OTP_HOME/bin' directory.

java -Duser.timezone=Europe/Rome -jar lib/otp.jar --basePath . --graphs . --port 7575 --securePort 8585 --server --router <router>

Note: replace with the one in your routing context.

Start the OTP instance by running from root of ${OTP_HOME} directory:

..\smartplaner-engine>sh start-otp.sh (LINUX)
..\smartplaner-engine>start-otp.bat (WINDOWS)

you'll see a Grizzly server running message. At this point you can open in a web browser

http://localhost:7575/

You should be presented with a web client that will interact with your local OpenTripPlanner instance. Select OSM layer as can be seen in image below.

• Java Development Kit (>=7)
• Mongodb (version v3.5.6)

Switch to ${OTP_HOME} directory created in the earlier section and clone the project sources:

https://github.com/smartcommunitylab/smartplanner.git

Then switch to the newly cloned SmartPlanner engine repository which consist of two sub projects

05/07/2017  11:28    <DIR>          smartplanner
04/05/2017  10:33    <DIR>          smartplanner-beans

Build smartplanner-beans project:

cd smartplanner-beans
mvn clean package

Build smartplanner project:

cd smartplanner
mvn clean package

Maven should then be able to download all the libraries and other dependencies necessary to compile smartplanner engine. If all goes well you should see a success message like the following:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 42.164s
[INFO] Finished at: Tue Jun 18 19:35:48 CET 2017
[INFO] Final Memory: 88M/695M
[INFO] ------------------------------------------------------------------------

This build process should produce a JAR file 'smart-planner.jar' in the 'target/' directory.

One can skip step 2.1 and download the binary smartplanner engine jar files from here:

https://github.com/smartcommunitylab/smartplanner/releases/download/binary/smart-planner.jar
https://github.com/smartcommunitylab/smartplanner/releases/download/binary/dependency-jars.zip

Copy the smart-planner.jar file inside to '${OTP_HOME}/lib' folder. Unzip the dependenpy-jars.zip inside to the '${OTP_HOME}/lib' folder. In case of source build, copy from 'target' directory 'smart-planner.jar' file and the 'dependency-jars' directory inside to the '${OTP_HOME}/lib'.

Now the folder structure should look like the following

smartplanner-engine
 |- trentino
 |	|- Graph.obj
 |	|- *osmfiles*
 |      |- gtfs.zip
 |      |- router-config.json
 |      `- build-config.json
 `- lib
	|-otp.jar
	|-dependency-jars\
	`-smart-planner.jar

Create a config folder inside $OTP_HOME/router and then create a YAML configuration file inside it as show below:

otpEndpoint: http://127.0.0.1:7575/otp/routers/

router: trentino

googleAPINearBySearch: https://maps.googleapis.com/maps/api/place/nearbysearch/json

googleAPIKey: <YOUR_GOOGLE_API_KEY>

publicTransport:
  trentoUrban:
     agencyId: 12
     type: bus
  roveretoUrban:
    agencyId: 16
    type: bus
  extraUrban:
    agencyId: 17
    type: bus
  bilbobus:
    agencyId: 27BB
    type: bus
  bizkaibus:
    agencyId: 200
    type: bus

Save the file as {router}.yml for e.g. trentino.yml, basque.yml as per ones routing context.

agencyId: make sure that the agencyId matches with the one in the gtfs zip file (agency.txt).

type: type can be (bus,train etc) depending upon the route type value inside the gtfs zip file (routes.txt).

otpEndpoint: check that router configuration is aligned with already started instance of otp.

otpEndpoint: http://127.0.0.1:7575/otp/routers/

router: make sure router name matches with the started instance $OTP_HOME/.

GoogleAPIKey: create google API Key for Google Map API, following the instructions provided here

https://maps.googleapis.com/maps/api/place/nearbysearch/json

replace the value of property key 'googleAPIKey'.

PublicTransport: list all the transport agenices used in the creation of routing graph(Graph.obj). Read the 'agencyId' from the agency.txt file for each transit feed(.zip). Create an entry per gtfs zip file specifying agencyName as key (trentoUrban) and agencyId and type of transit as properties.

GTFS configuration is distributed at agency level. For each agency it is required to provide following files. The gtfs zip files must also be present inside $OTP_HOME//gtfs folder. At run time the smartplanner engine reads the gtfs files from this folder and extract them inside 'schedule' folder for further manipulations.

smartplanner-engine
 |- basque
 |  |-12.zip
 |  |-16.zip
 |  |-17.zip
 |  |-32.zip
 |  |-16.zip
 |  |- Graph.obj
 |  |- *osmfiles*
 |  |- router-config.json
 |  `- build-config.json
 |  |
 |  |-gtfs
 |  | |-12.zip
 |  | |-16.zip
 |  | |-17.zip
 |  | |-32.zip
 |  | `-16.zip
 |  |
 |  `-config
 |    `-basque.yml
 |  
 |- lib
 |  |-otp.jar
 |  |-dependency-jars\
 |  `-smart-planner.jar

• Start MongoDB (if not started already)
• Start OTP instance for the routing context(if not started already) following the guidelines of section 1.4
• Copy the following set of commands and create script files for LINUX(start-smartplanner.sh) and WINDOWS(start-smartplanner.bat) for your operating system respectively inside to '$OTP_HOME/bin' directory. Please make sure that 'ROUTERS' variable is updated as per one's routing context.

WINDOWS
-------
@echo OFF
set OTP_HOME=%CD%
set ROUTERS=trentino
echo OTP_HOME is %OTP_HOME%
echo "Starting Smart Planner distributed instance."
cd %OTP_HOME%
java -Dinitialize=true -Dserver.port=7676 -Dserver.contextPath=/smart-planner -jar lib/smart-planner.jar

LINUX
-----
#!/usr/bin/env bash
export OTP_HOME=$PWD
export ROUTERS=trentino
echo OTP_HOME is $OTP_HOME
echo "Starting Smart Planner distributed instance."
cd $OTP_HOME
screen -d -m -SL smartplanner-dist java -Xmx1G -Dinitialize=true -Dserver.port=5055 -Dserver.contextPath=/smart-planner -jar lib/smart-planner.jar

Launch the script for your operating system from $OTP_HOME folder:

..\smartplaner-engine>sh bin\start-smartplanner.sh (LINUX)
..\smartplaner-engine>sh bin\start-smartplanner.bat (WINDOWS)

Important

• Please make sure that mongodb is up and OTP instance is running for the same routing context before launching the smartplanner engine.

The SmartPlannerEngine exposes Swagger API interface which is accessible from here:

http://localhost:7676/smart-planner/swagger-ui.html

The swagger api console list APIs for different areas/apects of mobility. The instructions to configure different aspects of mobility are provided in the corresponding sections. In the context of this tutorial, you can invoke APIs for planning and transit aspects only as shown above.