RoutingResource (OpenTripPlanner 1.3.0 API)

java.lang.Object
- org.opentripplanner.api.common.RoutingResource

Direct Known Subclasses:

GraphInspectorTileResource, LIsochrone, PlannerResource, ScriptResource, SimpleIsochrone, SIsochrone, SurfaceResource, TileService, TimeGridWs
```
public abstract class RoutingResource
extends Object
```
This class defines all the JAX-RS query parameters for a path search as fields, allowing them to be inherited by other REST resource classes (the trip planner and the Analyst WMS or tile resource). They will be properly included in API docs generated by Enunciate. This implies that the concrete REST resource subclasses will be request-scoped rather than singleton-scoped. All defaults should be specified in the RoutingRequest, NOT as annotations on the query parameters. JSON router configuration can then overwrite those built-in defaults, and only the fields of the resulting prototype routing request for which query parameters are found are overwritten here. This establishes a priority chain: RoutingRequest field initializers, then JSON router config, then query parameters.

Author:

abyrd

Field Summary

Fields
Modifier and Type	Field and Description
`protected Boolean`	`arriveBy` Whether the trip should depart or arrive at the specified date and time.
`protected String`	`bannedAgencies` The comma-separated list of banned agencies.
`protected String`	`bannedRoutes` The comma-separated list of banned routes.
`protected String`	`bannedStops` A comma-separated list of banned stops.
`protected String`	`bannedStopsHard` A comma-separated list of banned stops.
`protected String`	`bannedTrips` The comma-separated list of banned trips.
`protected Boolean`	`batch` If true, goal direction is turned off and a full path tree is built (specify only once)
`protected Integer`	`bikeBoardCost` Prevents unnecessary transfers by adding a cost for boarding a vehicle.
`protected Double`	`bikeSpeed` The user's biking speed in meters/second.
`protected Integer`	`bikeSwitchCost` The cost of the user fetching their bike and parking it again.
`protected Integer`	`bikeSwitchTime` The time it takes the user to fetch their bike and park it again in seconds.
`protected Long`	`clampInitialWait` When subtracting initial wait time, do not subtract more than this value, to prevent overly optimistic trips.
`protected String`	`date` The date that the trip should depart (or arrive, for requests where arriveBy is true).
`protected Boolean`	`disableRemainingWeightHeuristic` If true, the remaining weight heuristic is disabled.
`protected String`	`fromPlace` The start location -- either latitude, longitude pair in degrees or a Vertex label.
`protected Boolean`	`ignoreRealtimeUpdates` If true, realtime updates are ignored during this search.
`protected List<String>`	`intermediatePlaces` An ordered list of intermediate locations to be visited (see the fromPlace for format).
`protected Integer`	`maxPreTransitTime` The maximum time (in seconds) of pre-transit travel when using drive-to-transit (park and ride or kiss and ride).
`protected Integer`	`maxTransfers` The maximum number of transfers (that is, one plus the maximum number of boardings) that a trip will be allowed.
`protected Double`	`maxWalkDistance` The maximum distance (in meters) the user is willing to walk.
`protected Integer`	`minTransferTime` The minimum time, in seconds, between successive trips on different vehicles.
`protected QualifiedModeSet`	`modes` The set of modes that a user is willing to use, with qualifiers stating whether vehicles should be parked, rented, etc.
`protected Integer`	`nonpreferredTransferPenalty` An additional penalty added to boardings after the first when the transfer is not preferred.
`protected Integer`	`numItineraries` The maximum number of possible itineraries to return.
`protected OptimizeType`	`optimize` The set of characteristics that the user wants to optimize for.
`protected Integer`	`otherThanPreferredRoutesPenalty` Penalty added for using every route that is not preferred if user set any route as preferred, i.e.
`protected OTPServer`	`otpServer`
`protected String`	`preferredAgencies` The comma-separated list of preferred agencies.
`protected String`	`preferredRoutes` The list of preferred routes.
`protected Boolean`	`reverseOptimizeOnTheFly` If true, this trip will be reverse-optimized on the fly.
`String`	`routerId` The routerId selects between several graphs on the same server.
`protected Boolean`	`showIntermediateStops` Whether intermediate stops -- those that the itinerary passes in a vehicle, but does not board or alight at -- should be returned in the response.
`protected String`	`startTransitStopId` A transit stop required to be the first stop in the search (AgencyId_StopId)
`protected String`	`startTransitTripId` A transit trip acting as a starting "state" for depart-onboard routing (AgencyId_TripId)
`protected String`	`time` The time that the trip should depart (or arrive, for requests where arriveBy is true).
`protected String`	`toPlace` The end location (see fromPlace for format).
`protected Integer`	`transferPenalty` An additional penalty added to boardings after the first.
`protected Double`	`triangleSafetyFactor` For bike triangle routing, how much safety matters (range 0-1).
`protected Double`	`triangleSlopeFactor` For bike triangle routing, how much slope matters (range 0-1).
`protected Double`	`triangleTimeFactor` For bike triangle routing, how much time matters (range 0-1).
`protected String`	`unpreferredAgencies` The comma-separated list of unpreferred agencies.
`protected String`	`unpreferredRoutes` The list of unpreferred routes.
`protected Double`	`waitAtBeginningFactor` How much less bad is waiting at the beginning of the trip (replaces waitReluctance)
`protected Double`	`waitReluctance` How much worse is waiting for a transit vehicle than being on a transit vehicle, as a multiplier.
`protected Integer`	`walkBoardCost` Prevents unnecessary transfers by adding a cost for boarding a vehicle.
`protected Double`	`walkReluctance` A multiplier for how bad walking is, compared to being in transit for equal lengths of time.
`protected Double`	`walkSpeed` The user's walking speed in meters/second.
`protected Boolean`	`wheelchair` Whether the trip must be wheelchair accessible.

Constructor Summary

Constructors
Constructor and Description

RoutingResource()

Constructors
Constructor and Description
`RoutingResource()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected RoutingRequest`	`buildRequest()` Range/sanity check the query parameter fields and build a Request object from them.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - routerId
```
@PathParam(value="routerId")
public String routerId
```
    The routerId selects between several graphs on the same server. The routerId is pulled from the path, not the query parameters. However, the class RoutingResource is not annotated with a path because we don't want it to be instantiated as an endpoint. Instead, the {routerId} path parameter should be included in the path annotations of all its subclasses.
  - fromPlace
```
@QueryParam(value="fromPlace")
protected String fromPlace
```
    The start location -- either latitude, longitude pair in degrees or a Vertex label. For example, 40.714476,-74.005966 or mtanyctsubway_A27_S.
  - toPlace
```
@QueryParam(value="toPlace")
protected String toPlace
```
    The end location (see fromPlace for format).
  - intermediatePlaces
```
@QueryParam(value="intermediatePlaces")
protected List<String> intermediatePlaces
```
    An ordered list of intermediate locations to be visited (see the fromPlace for format). Parameter can be specified multiple times.
  - date
```
@QueryParam(value="date")
protected String date
```
    The date that the trip should depart (or arrive, for requests where arriveBy is true).
  - time
```
@QueryParam(value="time")
protected String time
```
    The time that the trip should depart (or arrive, for requests where arriveBy is true).
  - arriveBy
```
@QueryParam(value="arriveBy")
protected Boolean arriveBy
```
    Whether the trip should depart or arrive at the specified date and time.
  - wheelchair
```
@QueryParam(value="wheelchair")
protected Boolean wheelchair
```
    Whether the trip must be wheelchair accessible.
  - maxWalkDistance
```
@QueryParam(value="maxWalkDistance")
protected Double maxWalkDistance
```
    The maximum distance (in meters) the user is willing to walk. Defaults to unlimited.
  - maxPreTransitTime
```
@QueryParam(value="maxPreTransitTime")
protected Integer maxPreTransitTime
```
    The maximum time (in seconds) of pre-transit travel when using drive-to-transit (park and ride or kiss and ride). Defaults to unlimited.
  - walkReluctance
```
@QueryParam(value="walkReluctance")
protected Double walkReluctance
```
    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.
  - waitReluctance
```
@QueryParam(value="waitReluctance")
protected Double 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.
  - waitAtBeginningFactor
```
@QueryParam(value="waitAtBeginningFactor")
protected Double waitAtBeginningFactor
```
    How much less bad is waiting at the beginning of the trip (replaces waitReluctance)
  - walkSpeed
```
@QueryParam(value="walkSpeed")
protected Double walkSpeed
```
    The user's walking speed in meters/second. Defaults to approximately 3 MPH.
  - bikeSpeed
```
@QueryParam(value="bikeSpeed")
protected Double bikeSpeed
```
    The user's biking speed in meters/second. Defaults to approximately 11 MPH, or 9.5 for bikeshare.
  - bikeSwitchTime
```
@QueryParam(value="bikeSwitchTime")
protected Integer bikeSwitchTime
```
    The time it takes the user to fetch their bike and park it again in seconds. Defaults to 0.
  - bikeSwitchCost
```
@QueryParam(value="bikeSwitchCost")
protected Integer bikeSwitchCost
```
    The cost of the user fetching their bike and parking it again. Defaults to 0.
  - triangleSafetyFactor
```
@QueryParam(value="triangleSafetyFactor")
protected Double triangleSafetyFactor
```
    For bike triangle routing, how much safety matters (range 0-1).
  - triangleSlopeFactor
```
@QueryParam(value="triangleSlopeFactor")
protected Double triangleSlopeFactor
```
    For bike triangle routing, how much slope matters (range 0-1).
  - triangleTimeFactor
```
@QueryParam(value="triangleTimeFactor")
protected Double triangleTimeFactor
```
    For bike triangle routing, how much time matters (range 0-1).
  - optimize
```
@QueryParam(value="optimize")
protected OptimizeType optimize
```
    The set of characteristics that the user wants to optimize for. @See OptimizeType
  - modes
```
@QueryParam(value="mode")
protected QualifiedModeSet modes
```
    The set of modes that a user is willing to use, with qualifiers stating whether vehicles should be parked, rented, etc.
  - minTransferTime
```
@QueryParam(value="minTransferTime")
protected Integer minTransferTime
```
    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.
  - numItineraries
```
@QueryParam(value="numItineraries")
protected Integer numItineraries
```
    The maximum number of possible itineraries to return.
  - preferredRoutes
```
@QueryParam(value="preferredRoutes")
protected String preferredRoutes
```
    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).
  - otherThanPreferredRoutesPenalty
```
@QueryParam(value="otherThanPreferredRoutesPenalty")
protected Integer otherThanPreferredRoutesPenalty
```
    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.
  - preferredAgencies
```
@QueryParam(value="preferredAgencies")
protected String preferredAgencies
```
    The comma-separated list of preferred agencies.
  - unpreferredRoutes
```
@QueryParam(value="unpreferredRoutes")
protected String unpreferredRoutes
```
    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).
  - unpreferredAgencies
```
@QueryParam(value="unpreferredAgencies")
protected String unpreferredAgencies
```
    The comma-separated list of unpreferred agencies.
  - showIntermediateStops
```
@QueryParam(value="showIntermediateStops")
protected Boolean showIntermediateStops
```
    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.
  - walkBoardCost
```
@QueryParam(value="walkBoardCost")
protected Integer walkBoardCost
```
    Prevents unnecessary transfers by adding a cost for boarding a vehicle. This is the cost that is used when boarding while walking.
  - bikeBoardCost
```
@QueryParam(value="bikeBoardCost")
protected Integer bikeBoardCost
```
    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.
  - bannedRoutes
```
@QueryParam(value="bannedRoutes")
protected String bannedRoutes
```
    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).
  - bannedAgencies
```
@QueryParam(value="bannedAgencies")
protected String bannedAgencies
```
    The comma-separated list of banned agencies.
  - bannedTrips
```
@QueryParam(value="bannedTrips")
protected String bannedTrips
```
    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
  - bannedStops
```
@QueryParam(value="bannedStops")
protected String bannedStops
```
    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
  - bannedStopsHard
```
@QueryParam(value="bannedStopsHard")
protected String bannedStopsHard
```
    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
  - transferPenalty
```
@QueryParam(value="transferPenalty")
protected Integer transferPenalty
```
    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.
  - nonpreferredTransferPenalty
```
@QueryParam(value="nonpreferredTransferPenalty")
protected Integer nonpreferredTransferPenalty
```
    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.
  - maxTransfers
```
@QueryParam(value="maxTransfers")
protected Integer maxTransfers
```
    The maximum number of transfers (that is, one plus the maximum number of boardings) that a trip will be allowed. Larger values will slow performance, but could give better routes. This is limited on the server side by the MAX_TRANSFERS value in org.opentripplanner.api.ws.Planner.
  - batch
```
@QueryParam(value="batch")
protected Boolean batch
```
    If true, goal direction is turned off and a full path tree is built (specify only once)
  - startTransitStopId
```
@QueryParam(value="startTransitStopId")
protected String startTransitStopId
```
    A transit stop required to be the first stop in the search (AgencyId_StopId)
  - startTransitTripId
```
@QueryParam(value="startTransitTripId")
protected String startTransitTripId
```
    A transit trip acting as a starting "state" for depart-onboard routing (AgencyId_TripId)
  - clampInitialWait
```
@QueryParam(value="clampInitialWait")
protected Long clampInitialWait
```
    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.
  - reverseOptimizeOnTheFly
```
@QueryParam(value="reverseOptimizeOnTheFly")
protected Boolean reverseOptimizeOnTheFly
```
    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).
  - ignoreRealtimeUpdates
```
@QueryParam(value="ignoreRealtimeUpdates")
protected Boolean ignoreRealtimeUpdates
```
    If true, realtime updates are ignored during this search.
  - disableRemainingWeightHeuristic
```
@QueryParam(value="disableRemainingWeightHeuristic")
protected Boolean disableRemainingWeightHeuristic
```
    If true, the remaining weight heuristic is disabled. Currently only implemented for the long distance path service.
  - otpServer
```
@Context
protected OTPServer otpServer
```
- Constructor Detail
  - RoutingResource
```
public RoutingResource()
```
- Method Detail
  - buildRequest
```
protected RoutingRequest buildRequest()
                               throws ParameterException
```
    Range/sanity check the query parameter fields and build a Request object from them.
    
    Throws:
    
    ParameterException - when there is a problem interpreting a query parameter

Class RoutingResource

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

routerId

fromPlace

toPlace

intermediatePlaces

date

time

arriveBy

wheelchair

maxWalkDistance

maxPreTransitTime

walkReluctance

waitReluctance

waitAtBeginningFactor

walkSpeed

bikeSpeed

bikeSwitchTime

bikeSwitchCost

triangleSafetyFactor

triangleSlopeFactor

triangleTimeFactor

optimize

modes

minTransferTime

numItineraries

preferredRoutes

otherThanPreferredRoutesPenalty

preferredAgencies

unpreferredRoutes

unpreferredAgencies

showIntermediateStops

walkBoardCost

bikeBoardCost

bannedRoutes

bannedAgencies

bannedTrips

bannedStops

bannedStopsHard

transferPenalty

nonpreferredTransferPenalty

maxTransfers

batch

startTransitStopId

startTransitTripId

clampInitialWait

reverseOptimizeOnTheFly

ignoreRealtimeUpdates

disableRemainingWeightHeuristic

otpServer

Constructor Detail

RoutingResource

Method Detail

buildRequest