plan Query
Plans an itinerary from point A to point B based on the given arguments
Arguments
#
allowKeepingRentedBicycleAtDestination
Whether arriving at the destination with a rented (station) bicycle is allowed without dropping it off. Default: false.
allowedBikeRentalNetworks
Which vehicle rental networks can be used. By default, all networks are allowed.
allowedTicketTypes
List of ticket types that are allowed to be used in itineraries.
See ticketTypes query for list of possible ticket types.
allowedVehicleRentalNetworks
Which vehicle rental networks can be used. By default, all networks are allowed.
arriveBy
Whether the itinerary should depart at the specified time (false), or arrive to the destination at the specified time (true). Default value: false.
bannedVehicleRentalNetworks
Which vehicle rental networks cannot be used. By default, all networks are allowed.
batch
This argument has no use for itinerary planning and will be removed later. When true, do not use goal direction or stop at the target, build a full SPT. Default value: false.
bikeBoardCost
Separate cost for boarding a vehicle with a bicycle, which is more difficult than on foot. Unit: seconds. Default value: 600
bikeReluctance
A multiplier for how bad biking is, compared to being in transit for equal lengths of time. Default value: 2.0
bikeWalkingReluctance
A multiplier for how bad walking with a bike is, compared to being in transit for equal lengths of time. Default value: 5.0
carParkCarLegWeight
How expensive it is to drive a car when car&parking, increase this value to make car driving legs shorter. Default value: 1.
carReluctance
A multiplier for how bad driving is, compared to being in transit for equal lengths of time. Default value: 3.0
claimInitialWait
No effect on itinerary planning, adjust argument time instead to get later departures.
The maximum wait time in seconds the user is willing to delay trip start. Only effective in Analyst.
compactLegsByReversedSearch
Whether legs should be compacted by performing a reversed search.
debugItineraryFilter
Debug the itinerary-filter-chain. The filters will mark itineraries as deleted, but does NOT delete them when this is enabled.
disableRemainingWeightHeuristic
If true, the remaining weight heuristic is disabled. Currently only implemented for the long distance path service.
from
The geographical location where the itinerary begins.
Use either this argument or fromPlace , but not both.
fromPlace
The place where the itinerary begins in format name::place , where place
is either a lat,lng pair (e.g. Pasila::60.199041,24.932928 ) or a stop id
(e.g. Pasila::HSL:1000202 ).
Use either this argument or from , but not both.
heuristicStepsPerMainStep
Tuning parameter for the search algorithm, mainly useful for testing.
ignoreRealtimeUpdates
When true, real-time updates are ignored during this search. Default value: false
intermediatePlaces
An ordered list of intermediate locations to be visited.
itineraryFiltering
How easily bad itineraries are filtered from results. Value 0 (default)
disables filtering. Itineraries are filtered if they are worse than another
one in some respect (e.g. more walking) by more than the percentage of
filtering level, which is calculated by dividing 100% by the value of this
argument (e.g. itineraryFiltering = 0.5 → 200% worse itineraries are filtered).
keepingRentedBicycleAtDestinationCost
The cost of arriving at the destination with the rented vehicle, to discourage doing so. Default value: 0.
locale
Two-letter language code (ISO 639-1) used for returned text. Note: only part of the data has translations available and names of stops and POIs are returned in their default language. Due to missing translations, it is sometimes possible that returned text uses a mixture of two languages.
maxPreTransitTime
The maximum time (in seconds) of pre-transit travel when using drive-to-transit (park and ride or kiss and ride). Default value: 1800.
maxWalkDistance
The maximum distance (in meters) the user is willing to walk per walking
section. If the only transport mode allowed is WALK , then the value of
this argument is ignored.
Default: 2000m
Maximum value: 15000m
Note: If this argument has a relatively small value and only some
transport modes are allowed (e.g. WALK and RAIL ), it is possible to get
an itinerary which has (useless) back and forth public transport legs to
avoid walking too long distances.
minTransferTime
A global minimum transfer time (in seconds) that specifies the minimum amount of time that must pass between exiting one transit vehicle and boarding another. This time is in addition to time it might take to walk between transit stops. Default value: 120
modeWeight
The weight multipliers for transit modes. WALK, BICYCLE, CAR, TRANSIT and LEG_SWITCH are not included.
nonpreferredTransferPenalty
Penalty (in seconds) for using a non-preferred transfer. Default value: 180
omitCanceled = true
When false, return itineraries using canceled trips. Default value: true.
optimize
Optimization type for bicycling legs, e.g. prefer flat terrain. Default value: QUICK
pageCursor
Use the cursor to get the next or previous page of results. The next page is a set of itineraries departing after the last itinerary in this result and the previous page is a set of itineraries departing before the first itinerary. This is only usable when public transportation mode(s) are included in the query.
preferred
List of routes and agencies which are given higher preference when planning the itinerary
reverseOptimizeOnTheFly
Consider this argument experimental – setting this argument to true causes timeouts and unoptimal routes in many cases. When true, reverse optimize (find alternative transportation mode, which still arrives to the destination in time) this search on the fly after processing each transit leg, rather than reverse-optimizing the entire path when it's done. Default value: false.
searchWindow
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.
startTransitStopId
This argument has currently no effect on which itineraries are returned. Use
argument fromPlace to start the itinerary from a specific stop.
A transit stop that this trip must start from
startTransitTripId
ID of the trip on which the itinerary starts. This argument can be used to
plan itineraries when the user is already onboard a vehicle. When using this
argument, arguments time and from should be set based on a vehicle
position message received from the vehicle running the specified trip.
Note: this argument only takes into account the route and estimated
travel time of the trip (and therefore arguments time and from must be
used correctly to get meaningful itineraries).
to
The geographical location where the itinerary ends.
Use either this argument or toPlace , but not both.
toPlace
The place where the itinerary ends in format name::place , where place is
either a lat,lng pair (e.g. Pasila::60.199041,24.932928 ) or a stop id
(e.g. Pasila::HSL:1000202 ).
Use either this argument or to , but not both.
transferPenalty
An extra penalty added on transfers (i.e. all boardings except the first one). Not to be confused with bikeBoardCost and walkBoardCost, which are the cost of boarding a vehicle with and without a bicycle. The boardCosts are used to model the 'usual' perceived cost of using a transit vehicle, and the transferPenalty is used when a user requests even less transfers. In the latter case, we don't actually optimize for fewest transfers, as this can lead to absurd results. Consider a trip in New York from Grand Army Plaza (the one in Brooklyn) to Kalustyan's at noon. The true lowest transfers route is to wait until midnight, when the 4 train runs local the whole way. The actual fastest route is the 2/3 to the 4/5 at Nevins to the 6 at Union Square, which takes half an hour. Even someone optimizing for fewest transfers doesn't want to wait until midnight. Maybe they would be willing to walk to 7th Ave and take the Q to Union Square, then transfer to the 6. If this takes less than optimize_transfer_penalty seconds, then that's what we'll return. Default value: 0.
transportModes
List of transportation modes that the user is willing to use. Default: ["WALK","TRANSIT"]
triangle
Triangle optimization parameters for bicycling legs. Only effective when optimize is set to TRIANGLE.
unpreferred
List of routes and agencies which are given lower preference when planning the itinerary
via
The list of points the itinerary required to pass through. All locations are visited in the order they are listed.
waitAtBeginningFactor
How much less bad is waiting at the beginning of the trip (replaces
waitReluctance on the first boarding). Default value: 0.4
waitReluctance
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. Default value: 1.0.
walkBoardCost
This prevents unnecessary transfers by adding a cost for boarding a vehicle. Unit: seconds. Default value: 600
walkOnStreetReluctance
How much more reluctant is the user to walk on streets with car traffic allowed. Default value: 1.0
walkReluctance
A multiplier for how bad walking is, compared to being in transit for equal lengths of time. Empirically, values between 2 and 4 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. See https://github.com/opentripplanner/OpenTripPlanner/issues/4090 for impact on performance with high values. Default value: 2.0
walkSafetyFactor
Factor for how much the walk safety is considered in routing. Value should be between 0 and 1. If the value is set to be 0, safety is ignored. Default is 1.0.
Response
#
Returns Plan .
Example
#
patterns
planConnection