optionsome
commented
1 year ago I have created a draft schema for the legacy GraphQL API:
"""
Plans an itinerary from point A to point B based on the given arguments. This query follows the
relay connection specification https://relay.dev/graphql/connections.htm.
"""
planConnection(
"""
Date of departure or arrival in format YYYY-MM-DD. Default value: current date
"""
date: String
"""
Time of departure or arrival in format hh:mm:ss. Default value: current time
"""
time: String
"""
The geographical location where the itinerary begins.
Use either this argument or `fromPlace`, but not both.
"""
from: InputCoordinates
"""
The geographical location where the itinerary ends.
Use either this argument or `toPlace`, but not both.
"""
to: InputCoordinates
"""
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.
"""
fromPlace: String
"""
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.
"""
toPlace: String
"""
Whether the itinerary must be wheelchair accessible. Default value: false
"""
wheelchair: Boolean
"""The maximum number of itineraries to return."""
numItineraries: Int
"""
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.
"""
searchWindow: Long,
"""
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.
"""
pageCursor: String
"""
A multiplier for how bad biking is, compared to being in transit for equal
lengths of time. Default value: 2.0
"""
bikeReluctance: Float
"""
A multiplier for how bad walking with a bike is, compared to being in transit for equal
lengths of time. Default value: 5.0
"""
bikeWalkingReluctance: Float
"""
A multiplier for how bad driving is, compared to being in transit for equal
lengths of time. Default value: 3.0
"""
carReluctance: Float
"""
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
"""
walkReluctance: Float
"""
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.
"""
waitReluctance: Float
"""
Max walk speed along streets, in meters per second. Default value: 1.33
"""
walkSpeed: Float
"""Max bike speed along streets, in meters per second. Default value: 5.0"""
bikeSpeed: Float
"""Time to get on and off your own bike, in seconds. Default value: 0"""
bikeSwitchTime: Int
"""
Cost of getting on and off your own bike. Unit: seconds. Default value: 0
"""
bikeSwitchCost: Int
"""
Optimization type for bicycling legs, e.g. prefer flat terrain. Default value: `QUICK`
"""
optimize: OptimizeType
"""
Triangle optimization parameters for bicycling legs. Only effective when `optimize` is set to **TRIANGLE**.
"""
triangle: InputTriangle
"""
Whether the itinerary should depart at the specified time (false), or arrive
to the destination at the specified time (true). Default value: false.
"""
arriveBy: Boolean
"""
List of routes and agencies which are given lower preference when planning the itinerary
"""
unpreferred: InputUnpreferred
"""
This prevents unnecessary transfers by adding a cost for boarding a vehicle. Unit: seconds. Default value: 600
"""
walkBoardCost: Int
"""
Separate cost for boarding a vehicle with a bicycle, which is more difficult
than on foot. Unit: seconds. Default value: 600
"""
bikeBoardCost: Int
"""
List of routes, trips, agencies and stops which are not used in the itinerary
"""
banned: InputBanned
"""
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.
"""
transferPenalty: Int
"""
List of transportation modes that the user is willing to use. Default: `["WALK","TRANSIT"]`
"""
transportModes: [TransportMode]
"""
The weight multipliers for transit modes. WALK, BICYCLE, CAR, TRANSIT and LEG_SWITCH are not included.
"""
modeWeight: InputModeWeight
"""
Debug the itinerary-filter-chain. The filters will mark itineraries as deleted, but does NOT delete them when this is enabled.
"""
debugItineraryFilter: Boolean
"""
Whether arriving at the destination with a rented (station) bicycle is allowed without
dropping it off. Default: false.
"""
allowKeepingRentedBicycleAtDestination: Boolean
"""
The cost of arriving at the destination with the rented bicycle, to discourage doing so.
Default value: 0.
"""
keepingRentedBicycleAtDestinationCost: Int
"""
Invariant: `boardSlack + alightSlack <= transferSlack`. Default value: 0
"""
boardSlack: Int
"""
Invariant: `boardSlack + alightSlack <= transferSlack`. Default value: 0
"""
alightSlack: Int
"""
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: 0
"""
minTransferTime: Int
"""
When false, return itineraries using canceled trips. Default value: true.
"""
omitCanceled: Boolean = true
"""
When true, realtime updates are ignored during this search. Default value: false
"""
ignoreRealtimeUpdates: Boolean
"""
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.
"""
locale: String
"""
Which vehicle rental networks can be used. By default, all networks are allowed.
"""
allowedVehicleRentalNetworks: [String]
"""
Which vehicle rental networks cannot be used. By default, all networks are allowed.
"""
bannedVehicleRentalNetworks: [String]
"""
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.
"""
walkSafetyFactor: Float
before: String
after: String
first: Int
last: Int
): PlanConnection @async
}
type PlanConnection {
"""The time and date of travel. Format: Unix timestamp in milliseconds."""
date: Long
"""The origin"""
from: Place!
"""The destination"""
to: Place!
"""A list of routing errors, and fields which caused them"""
routingErrors: [RoutingError!]!
"""
This is the `searchWindow` used by the raptor search. It is provided here for debugging
purpousess.
The unit is seconds.
"""
searchWindowUsed: Long
"""Information about the timings for the plan generation"""
debugOutput: debugOutput!
edges: [PlanEdge]
pageInfo: PageInfo!
}
type PlanEdge {
node: Itinerary
cursor: String!
}
leonardehrenfried
hannesj
t2gran
github-actions[bot]
Expected behavior
There should be a plan query that follows the relay connection specification.
Observed behavior
Unfortunately it's not possible to use the pagination functions of relay with the regular plan query in the GraphQL APIs.
Version of OTP used (exact commit hash or JAR name)
2.x