OpenTripPlanner: PlannerResource

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		int	no
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
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
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
boardSlack	query		int	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
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
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
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
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	This is the time/duration in seconds from the earliest-departure-time(EDT) to latest-departure-time(LDT). In case of a reverse search it will be the time from earliest to latest arrival time (LAT minus EAT). All optimal travels that depart within the search window is guarantied to be found. This is sometimes referred to as the Range Raptor Search Window - but should apply to all scheduled/time dependent travels. Optional - it is NOT recommended to set this value, unless you use the value returned by the previous search. Then it can be used to get the next/previous "page". The value is dynamically assigned a suitable value, if not set. In a small to medium size operation you may use a fixed value, like 60 minutes. If you have a mixture of high frequency cities routes and infrequent long distant journeys, the best option is normally to use the dynamic auto assignment.	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
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
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,
      "orig" : "...",
      "zoneId" : "...",
      "stopIndex" : 12345,
      "stopSequence" : 12345,
      "vertexType" : "BIKEPARK",
      "bikeShareId" : "..."
    },
    "to" : {
      "name" : "...",
      "stopId" : "...",
      "stopCode" : "...",
      "platformCode" : "...",
      "lon" : 12345.0,
      "lat" : 12345.0,
      "arrival" : 12345,
      "departure" : 12345,
      "orig" : "...",
      "zoneId" : "...",
      "stopIndex" : 12345,
      "stopSequence" : 12345,
      "vertexType" : "NORMAL",
      "bikeShareId" : "..."
    },
    "itineraries" : [ {
      "duration" : 12345,
      "startTime" : 12345,
      "endTime" : 12345,
      "walkTime" : 12345,
      "transitTime" : 12345,
      "waitingTime" : 12345,
      "walkDistance" : 12345.0,
      "walkLimitExceeded" : true,
      "elevationLost" : 12345.0,
      "elevationGained" : 12345.0,
      "transfers" : 12345,
      "fare" : { },
      "legs" : [ { }, { } ],
      "systemNotices" : [ { }, { } ],
      "tooSloped" : true
    }, {
      "duration" : 12345,
      "startTime" : 12345,
      "endTime" : 12345,
      "walkTime" : 12345,
      "transitTime" : 12345,
      "waitingTime" : 12345,
      "walkDistance" : 12345.0,
      "walkLimitExceeded" : true,
      "elevationLost" : 12345.0,
      "elevationGained" : 12345.0,
      "transfers" : 12345,
      "fare" : { },
      "legs" : [ { }, { } ],
      "systemNotices" : [ { }, { } ],
      "tooSloped" : true
    } ]
  },
  "metadata" : {
    "searchWindowUsed" : 12345,
    "nextDateTime" : 12345,
    "prevDateTime" : 12345
  },
  "error" : {
    "id" : 12345,
    "msg" : "...",
    "message" : "TRIANGLE_OPTIMIZE_TYPE_NOT_SET",
    "missing" : [ "...", "..." ]
  }
}

PlannerResource Resource

GET /otp/routers/{ignoreRouterId}/plan

Example

Request

Response