PlannerResource Resource

This is the primary entry point for the trip planning web service. All parameters are passed in the query string. These parameters are defined as fields in the abstract RoutingResource superclass, which also has methods for building routing requests from query parameters. This allows multiple web services to have the same set of query parameters. In order for inheritance to work, the REST resources are request-scoped (constructed at each request) rather than singleton-scoped (a single instance existing for the lifetime of the OTP server).

GET /otp/routers/{ignoreRouterId}/plan

Request Parameters
name type description constraints multivalued
ignoreRouterId path   no
alightSlack query The number of seconds to add after alighting a transit leg. It is recommended to use the alightTimes in the router-config.json to set this for each mode.

Unit is seconds. Default value is 0.

 int no
allowKeepingRentedBicycleAtDestination query boolean no
allowedVehicleRentalNetworks query The vehicle rental networks which may be used. If empty all networks may be used.   yes
arriveBy query Whether the trip should depart or arrive at the specified date and time. boolean no
bannedAgencies query The comma-separated list of banned agencies.   no
bannedRoutes query The comma-separated list of banned routes. The format is agency_[routename][_routeid], so TriMet_100 (100 is route short name) or Trimet__42 (two underscores, 42 is the route internal ID).   no
bannedStops query A comma-separated list of banned stops. A stop is banned by ignoring its pre-board and pre-alight edges. This means the stop will be reachable via the street network. Also, it is still possible to travel through the stop. Just boarding and alighting is prohibited. The format is agencyId_stopId, so: TriMet_2107   no
bannedStopsHard query A comma-separated list of banned stops. A stop is banned by ignoring its pre-board and pre-alight edges. This means the stop will be reachable via the street network. It is not possible to travel through the stop. For example, this parameter can be used when a train station is destroyed, such that no trains can drive through the station anymore. The format is agencyId_stopId, so: TriMet_2107   no
bannedTrips query The comma-separated list of banned trips. The format is agency_trip[:stop*], so: TriMet_24601 or TriMet_24601:0:1:2:17:18:19   no
bannedVehicleParkingTags query Tags with which a vehicle parking will not be used. If empty, no tags are banned.   yes
bannedVehicleRentalNetworks query The vehicle rental networks which may not be used. If empty, no networks are banned.   yes
batch query If true, goal direction is turned off and a full path tree is built (specify only once) boolean no
bikeBoardCost query Prevents unnecessary transfers by adding a cost for boarding a vehicle. This is the cost that is used when boarding while cycling. This is usually higher that walkBoardCost. int no
bikeParkCost query Cost of parking a bike. int no
bikeParkTime query Time to park a bike int no
bikeReluctance query double no
bikeSpeed query The user's biking speed in meters/second. Defaults to approximately 11 MPH, or 9.5 for bikeshare. double no
bikeSwitchCost query The cost of the user fetching their bike and parking it again. Defaults to 0. int no
bikeSwitchTime query The time it takes the user to fetch their bike and park it again in seconds. Defaults to 0. int no
bikeWalkingReluctance query A multiplier for how bad walking with a bike is, compared to being in transit for equal lengths of time. Defaults to 3. double no
bikeWalkingSpeed query The user's bike walking speed in meters/second. Defaults to approximately 3 MPH. double no
boardSlack query The number of seconds to add before boarding a transit leg. It is recommended to use the boardTimes in the router-config.json to set this for each mode.

Unit is seconds. Default value is 0.

 int no
carParkCost query Cost of parking a car. int no
carParkTime query Time to park a car int no
carReluctance query double no
clampInitialWait query When subtracting initial wait time, do not subtract more than this value, to prevent overly optimistic trips. Reasoning is that it is reasonable to delay a trip start 15 minutes to make a better trip, but that it is not reasonable to delay a trip start 15 hours; if that is to be done, the time needs to be included in the trip time. This number depends on the transit system; for transit systems where trips are planned around the vehicles, this number can be much higher. For instance, it's perfectly reasonable to delay one's trip 12 hours if one is taking a cross-country Amtrak train from Emeryville to Chicago. Has no effect in stock OTP, only in Analyst. A value of 0 means that initial wait time will not be subtracted out (will be clamped to 0). A value of -1 (the default) means that clamping is disabled, so any amount of initial wait time will be subtracted out. long no
date query The date that the trip should depart (or arrive, for requests where arriveBy is true).   no
debugItineraryFilter query boolean no
debugRaptorPath query   no
debugRaptorStops query   no
disableAlertFiltering query boolean no
disableRemainingWeightHeuristic query If true, the remaining weight heuristic is disabled. Currently only implemented for the long distance path service. boolean no
fromPlace query The start location -- either latitude, longitude pair in degrees or a Vertex label. For example, 40.714476,-74.005966 or mtanyctsubway_A27_S.   no
geoidElevation query If true, the Graph's ellipsoidToGeoidDifference is applied to all elevations returned by this query. boolean no
ignoreRealtimeUpdates query If true, realtime updates are ignored during this search. boolean no
intermediatePlaces query An ordered list of intermediate locations to be visited (see the fromPlace for format). Parameter can be specified multiple times.   yes
keepingRentedBicycleAtDestinationCost query double no
locale query   no
maxHours query double no
maxPreTransitTime query The maximum time (in seconds) of pre-transit travel when using drive-to-transit (park and ride or kiss and ride). Defaults to unlimited. int no
maxTransfers query The maximum number of transfers (that is, one plus the maximum number of boardings) that a trip will be allowed. Consider using the #transferPenalty instead of this parameter. int no
maxWalkDistance query The maximum distance (in meters) the user is willing to walk. Defaults to unlimited. double no
minTransferTime query The minimum time, in seconds, between successive trips on different vehicles. This is designed to allow for imperfect schedule adherence. This is a minimum; transfers over longer distances might use a longer time. int no
mode query The set of modes that a user is willing to use, with qualifiers stating whether vehicles should be parked, rented, etc.

The possible values of the comma-separated list are:

  • WALK
  • TRANSIT
  • BICYCLE
  • BICYCLE_RENT
  • BICYCLE_PARK
  • CAR
  • CAR_PARK
  • TRAM
  • SUBWAY
  • RAIL
  • BUS
  • CABLE_CAR
  • FERRY
  • GONDOLA
  • FUNICULAR
  • AIRPLANE
For a more complete discussion of this parameter see Routing modes.		   no
nonpreferredTransferPenalty query An additional penalty added to boardings after the first when the transfer is not preferred. Preferred transfers also include timed transfers. The value is in OTP's internal weight units, which are roughly equivalent to seconds. Set this to a high value to discourage transfers that are not preferred. Of course, transfers that save significant time or walking will still be taken. When no preferred or timed transfer is defined, this value is ignored. TODO OTP2 This JavaDoc needs clarification. What is a "preferred" Transfer, the GTFS specification do not have "preferred Transfers". The GTFS spec transfer type 0 is _Recommended transfer point_ - is this what is meant? int no
numItineraries query The maximum number of possible itineraries to return. int no
optimize query The set of characteristics that the user wants to optimize for. @See OptimizeType. "FLAT" or "GREENWAYS" or "QUICK" or "SAFE" or "TRANSFERS" or "TRIANGLE" no
otherThanPreferredRoutesPenalty query Penalty added for using every route that is not preferred if user set any route as preferred, i.e. number of seconds that we are willing to wait for preferred route. int no
pageCursor query Use the cursor to go to the next "page" of itineraries. Copy the cursor from the last response and keep the original request as is. This will enable you to search for itineraries in the next or previous time-window.

This is an optional parameter.

   no
pathComparator query Set the method of sorting itineraries in the response. Right now, the only supported value is "duration"; otherwise it uses default sorting. More sorting methods may be added in the future.   no
preferredAgencies query The comma-separated list of preferred agencies.   no
preferredRoutes query The list of preferred routes. The format is agency_[routename][_routeid], so TriMet_100 (100 is route short name) or Trimet__42 (two underscores, 42 is the route internal ID).   no
requiredVehicleParkingTags query Tags which are required to use a vehicle parking. If empty, no tags are required.   yes
reverseOptimizeOnTheFly query THIS PARAMETER IS NO LONGER IN USE. If true, this trip will be reverse-optimized on the fly. Otherwise, reverse-optimization will occur once a trip has been chosen (in Analyst, it will not be done at all). boolean no
searchWindow query The length of the search-window in seconds. This parameter is optional.

The search-window is defined as the duration between the earliest-departure-time(EDT) and the latest-departure-time(LDT). OTP will search for all itineraries in this departure window. If arriveBy=true the dateTime parameter is the latest-arrival-time, so OTP will dynamically calculate the EDT. Using a short search-window is faster than using a longer one, but the search duration is not linear. Using a \"too\" short search-window will waste resources server side, while using a search-window that is too long will be slow.

OTP will dynamically calculate a reasonable value for the search-window, if not provided. The calculation comes with a significant overhead (10-20% extra). Whether you should use the dynamic calculated value or pass in a value depends on your use-case. For a travel planner in a small geographical area, with a dense network of public transportation, a fixed value between 40 minutes and 2 hours makes sense. To find the appropriate search-window, adjust it so that the number of itineraries on average is around the wanted numItineraries. Make sure you set the numItineraries to a high number while testing. For a country wide area like Norway, using the dynamic search-window is the best.

When paginating, the search-window is calculated using the numItineraries in the original search together with statistics from the search for the last page. This behaviour is configured server side, and can not be overridden from the client.

The search-window used is returned to the response metadata as searchWindowUsed for debugging purposes.

 int no
showIntermediateStops query Whether intermediate stops -- those that the itinerary passes in a vehicle, but does not board or alight at -- should be returned in the response. For example, on a Q train trip from Prospect Park to DeKalb Avenue, whether 7th Avenue and Atlantic Avenue should be included. boolean no
startTransitStopId query A transit stop required to be the first stop in the search (AgencyId_StopId)   no
startTransitTripId query A transit trip acting as a starting "state" for depart-onboard routing (AgencyId_TripId)   no
time query The time that the trip should depart (or arrive, for requests where arriveBy is true).   no
timetableView query Search for the best trip options within a time window. If true two itineraries are considered optimal if one is better on arrival time(earliest wins) and the other is better on departure time(latest wins).

In combination with arriveBy this parameter cover the following 3 use cases:

  • Traveler want to find thee best alternative within a time window. Set timetableView=true and arriveBy=false. This is the default, and if the intention of the traveler is unknown it gives the best result, because it includes the two next use-cases. Setting the arriveBy=false, covers the same use-case, but the input time is interpreted as latest-arrival-time, and not earliest-departure-time. This works great with paging, request next/previous time-window.
  • Traveler want to find the best alternative with departure after a specific time. For example: I am at the station now and want to get home as quickly as possible. Set timetableView=false and arriveBy=false. Do not support paging.
  • Traveler want to find the best alternative with arrival before specific time. For example going to a meeting. Do not support paging. Set timetableView=false and arriveBy=true.
Default: true		 boolean no
toPlace query The end location (see fromPlace for format).   no
transferPenalty query An additional penalty added to boardings after the first. The value is in OTP's internal weight units, which are roughly equivalent to seconds. Set this to a high value to discourage transfers. Of course, transfers that save significant time or walking will still be taken. int no
triangleSafetyFactor query For bike triangle routing, how much safety matters (range 0-1). double no
triangleSlopeFactor query For bike triangle routing, how much slope matters (range 0-1). double no
triangleTimeFactor query For bike triangle routing, how much time matters (range 0-1). double no
unpreferredAgencies query The comma-separated list of unpreferred agencies.   no
unpreferredRoutes query The list of unpreferred routes. The format is agency_[routename][_routeid], so TriMet_100 (100 is route short name) or Trimet__42 (two underscores, 42 is the route internal ID).   no
useRequestedDateTimeInMaxHours query boolean no
useVehicleParkingAvailabilityInformation query boolean no
waitAtBeginningFactor query How much less bad is waiting at the beginning of the trip (replaces waitReluctance) double no
waitReluctance query How much worse is waiting for a transit vehicle than being on a transit vehicle, as a multiplier. The default value treats wait and on-vehicle time as the same. It may be tempting to set this higher than walkReluctance (as studies often find this kind of preferences among riders) but the planner will take this literally and walk down a transit line to avoid waiting at a stop. This used to be set less than 1 (0.95) which would make waiting offboard preferable to waiting onboard in an interlined trip. That is also undesirable. If we only tried the shortest possible transfer at each stop to neighboring stop patterns, this problem could disappear. double no
walkBoardCost query Prevents unnecessary transfers by adding a cost for boarding a vehicle. This is the cost that is used when boarding while walking. int no
walkReluctance query A multiplier for how bad walking is, compared to being in transit for equal lengths of time. Defaults to 2. Empirically, values between 10 and 20 seem to correspond well to the concept of not wanting to walk too much without asking for totally ridiculous itineraries, but this observation should in no way be taken as scientific or definitive. Your mileage may vary. double no
walkSpeed query The user's walking speed in meters/second. Defaults to approximately 3 MPH. double no
wheelchair query Whether the trip must be wheelchair accessible. boolean no
whiteListedAgencies query Functions the same as banned agencies, except only the listed agencies are allowed.   no
whiteListedRoutes query Functions the same as bannnedRoutes, except only the listed routes are allowed.   no
Response Body
media type data type description
application/json TripPlannerResponse (JSON)

Example

Request
GET /routers/{ignoreRouterId}/plan
Content-Type: */*
Accept: application/json

                
...
Response
HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "requestParameters" : {
    "property1" : "...",
    "property2" : "..."
  },
  "debugOutput" : {
    "precalculationTime" : 12345,
    "directStreetRouterTime" : 12345,
    "transitRouterTime" : 12345,
    "filteringTime" : 12345,
    "renderingTime" : 12345,
    "totalTime" : 12345,
    "transitRouterTimes" : {
      "tripPatternFilterTime" : 12345,
      "accessEgressTime" : 12345,
      "raptorSearchTime" : 12345,
      "itineraryCreationTime" : 12345
    }
  },
  "elevationMetadata" : {
    "ellipsoidToGeoidDifference" : 12345.0,
    "geoidElevation" : true
  },
  "plan" : {
    "date" : 12345,
    "from" : {
      "name" : "...",
      "stopId" : "...",
      "stopCode" : "...",
      "platformCode" : "...",
      "lon" : 12345.0,
      "lat" : 12345.0,
      "arrival" : 12345,
      "departure" : 12345,
      "zoneId" : "...",
      "stopIndex" : 12345,
      "stopSequence" : 12345,
      "vertexType" : "TRANSIT",
      "bikeShareId" : "...",
      "vehicleParking" : { }
    },
    "to" : {
      "name" : "...",
      "stopId" : "...",
      "stopCode" : "...",
      "platformCode" : "...",
      "lon" : 12345.0,
      "lat" : 12345.0,
      "arrival" : 12345,
      "departure" : 12345,
      "zoneId" : "...",
      "stopIndex" : 12345,
      "stopSequence" : 12345,
      "vertexType" : "BIKESHARE",
      "bikeShareId" : "...",
      "vehicleParking" : { }
    },
    "itineraries" : [ {
      "duration" : 12345,
      "startTime" : 12345,
      "endTime" : 12345,
      "walkTime" : 12345,
      "transitTime" : 12345,
      "waitingTime" : 12345,
      "walkDistance" : 12345.0,
      "walkLimitExceeded" : true,
      "generalizedCost" : 12345,
      "elevationLost" : 12345.0,
      "elevationGained" : 12345.0,
      "transfers" : 12345,
      "fare" : { },
      "legs" : [ { }, { } ],
      "systemNotices" : [ { }, { } ],
      "tooSloped" : true,
      "arrivedAtDestinationWithRentedBicycle" : true
    }, {
      "duration" : 12345,
      "startTime" : 12345,
      "endTime" : 12345,
      "walkTime" : 12345,
      "transitTime" : 12345,
      "waitingTime" : 12345,
      "walkDistance" : 12345.0,
      "walkLimitExceeded" : true,
      "generalizedCost" : 12345,
      "elevationLost" : 12345.0,
      "elevationGained" : 12345.0,
      "transfers" : 12345,
      "fare" : { },
      "legs" : [ { }, { } ],
      "systemNotices" : [ { }, { } ],
      "tooSloped" : true,
      "arrivedAtDestinationWithRentedBicycle" : true
    } ]
  },
  "previousPageCursor" : "...",
  "nextPageCursor" : "...",
  "error" : {
    "id" : 12345,
    "msg" : "...",
    "message" : "TOO_CLOSE",
    "missing" : [ "...", "..." ]
  },
  "metadata" : {
    "searchWindowUsed" : 12345
  }
}