If you are not yet familiar with GraphQL and GraphiQL it is highly recommended to review those pages at first.
\n| Term | \nExplanation | \n
|---|---|
| Itinerary | \nA combination of different transportation modes at certain times to reach from origin to destination. For example, walking to a bus stop, taking a bus for two stops and then walking to the final destination. Commonly used synonym: journey | \n
| Leg | \nOne part of an itinerary, e.g. walking to a bus stop or a bus ride between two stops. | \n
| Origin | \nA geographical point where an itinerary begins. | \n
| Destination | \nA geographical point where an itinerary ends. | \n
You can ask the server to return geometries for itineraries. The API will return them in Google polyline-encoded format. It looks like this:
\n\"legGeometry\": {\n \"length\": 349,\n \"points\": \"wwfnJyjdwCXlAHLNfAFHDZz@nEh@hBXfA\\\\hAR^VLnChAD@HDHDjBt@^N|@`@JDHNFB`@RHDJFD@PD^fBDNNp@@JBPHl@FdA@d@@TFrCDnATpEL~CBnA@pADpELbQ?pB?nBC~@DdC?R?LDtC?P?j@@XG~@Ef@CPCHGHoAtAQT_@f@w@rAc@~@g@lAi@fBc@hBWvASzAWrBUtBQxBOtBMhCOvEEhCCfC@vB@fBDrCFlCJnCb@xIfFl_APdDr@dMd@bIV~D\\\\bFPnCjAtMt@~GxAhMlBfOz@jHVjCR~BNpCHrBFjCDdC?`CC`DIfDSxDUhDe@fFu@tHMzA{AlOcBtPCXE`@sCrY_BbPShCeAxJc@pDg@nECJi@~Di@dDUbAkA~Gk@bD_@vBUbB]lBe@lDY~B[rCWbC_@~DYfDW|BQ~Am@tGOfBOxAWlCKzAMvAIbAMpBIpAAd@GhACp@EhAEtAA~ACfCAnC@fA?rAClDC`G@`BCxHKlCMhIK~FE|CA~@@|@BxB@^?@DtAHbBLzALjBHbBFlAF|ADxAD|BNrEPjCTtHdAhVp@jSVlPFjJ?dC?hE?dJ?xC?vLDfKDpEF|CFnDPjHZvH\\\\xH|@jQXnF\\\\nFBXdAtSJtCZrG@^b@`K^dJLnDLtDj@bRT`IAb@?~@?dA@~A?fA?|@AjAE~BA`BBdABd@Bh@HfARnBPpBl@zFt@lGr@vE\\\\|Cz@dHrA|JdAtHPpAl@dEjA~I~AvNv@tIx@vKTtD`@nHTrENtDRzEPvHR|J\\\\`VNdKAjEFpLBlFDjCBfCFxBNjE`@nH@j@An@Cr@I^O^y@l@iAt@S@IAIGMKCICIKIKEI?MDILKVQVW^WVUPSJuAT??_ANaALg@No@ZkAz@a@ZKR]j@a@h@i@fA[f@Q`@u@dCmAvEw@dCk@nAe@z@S\\\\iAnAeA`Ai@f@eAfBy@rBu@rCMf@WfAU`Ac@`Bi@`CKh@ANUdBq@~GW|BQdAK^M\\\\IROVMLs@d@q@\\\\]P}@R{@BaA@_@Iu@E]?CAU?M?W@i@DKBg@NUDq@V}@^g@XQJk@h@EDQPeBnBIHILU\\\\\"\n}Note: For more details about the query type planConnection and its parameters you can use the Documentation Explorer provided in GraphiQL.
\nNote: Some additional examples can be found on the Bicycles, cars and e-scooters page.
\nItinerary planning can be tuned by multiple arguments of the planConnection query.
\nTime arguments are taken into account literally when planning the itinerary
\npreferences: {street: { transit: {transfer: {slack: \"2m\"}}}, it is not possible to continue the journey by another vehicle within two minutes after disembarking one vehicleCost arguments on the other hand are not hard limits, but preferences
\npreferences: {street: {walk: {boardCost: 120}}}, it is possible to continue the journey immediately after disembarking from one vehicle, but up to 2 minutes longer itineraries are preferred if they have one transfer less and up to 4 minutes longer itineraries are preferred if they have two transfers less, etc.boardCost is set to 1 minute, the returned duration of the walking leg will be 15 minutesMultiplier arguments (e.g. preferences: {street: {walk: {reluctance: 3}}}) are used to multiply costs of an leg
reluctance is set to 3.0, the cost of each walking section will be multiplied by 3 and thus itineraries with less walking are preferred{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.168992, longitude: 24.932366}}}\n destination: {location: {coordinate: {latitude: 60.175294, longitude: 24.684855}}}\n first: 2\n ) {\n pageInfo {\n endCursor\n }\n edges {\n node {\n start\n end\n legs {\n duration\n mode\n distance\n start {\n scheduledTime\n }\n end {\n scheduledTime\n }\n mode\n duration\n realtimeState\n }\n emissionsPerPerson {\n co2\n }\n }\n }\n }\n}It is possible to define a searchWindow in the requests to ensure that itineraries are searched from a specified search window time.\nHowever, usually specifying a search window in the request doesn't make sense as it can be inefficient. If one isn't specified, a search\nwindow is computed during the request which in many cases yields results. If one wants to specify a search window, it should preferable be\nbetween 30 minutes and 8 hours (depends on how dense the transit network is in the area), and it should be used together with pagination.
The planConnection query follows the Relay Graphql Cursor Connection specification. Only\ndifference is that there are no cursors available for the itineraries in the middle of a response (a hard-coded place holder string\nis returned instead).
Pagination is highly recommended as usually it's possible to get enough itineraries without specifying a relatively high searchWindow in the\nrequest. Higher searchWindow will mean that fetching the itineraries will take more time and in most cases, more itineraries will be found\nthan what is necessary.
The first argument in the GraphQL query specifies the number of itinerary plans to be returned. To retrieve more results, you can use the after argument with the value of endCursor from the previous query's response's pageInfo.
{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.168992, longitude: 24.932366}}}\n destination: {location: {coordinate: {latitude: 60.175294, longitude: 24.684855}}}\n first: 2\n after: <endCursor from previous query>\n )....Alternatively, if you want to fetch previous itineraries, before and last arguments can be used.
{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.168992, longitude: 24.932366}}}\n destination: {location: {coordinate: {latitude: 60.175294, longitude: 24.684855}}}\n last: 2\n before: <startCursor from previous query>\n )....Note: Pagination back-and-forth is not recommended. The previously returned itineraries should be stored in the client.
\nNote: If it's likely that you need to fetch for more itineraries, it's more efficient to just fetch more itineraries in the first\nrequest instead of limiting it with the first or last as it's likely that the backend will have a lot more itineraries available to be returned.
label. The label is then returned with the location\nin the itineraries.{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.168992, longitude: 24.932366}}, label: \"Kamppi, Helsinki\"}\n destination: {location: {coordinate: {latitude: 60.175294, longitude: 24.684855}}, label: \"Pisa, Espoo\"}\n first: 2\n ) {\n pageInfo {\n endCursor\n }\n edges {\n node {\n start\n end\n legs {\n from {\n name\n }\n to {\n name\n }\n start {\n scheduledTime\n }\n end {\n scheduledTime\n }\n mode\n duration\n realtimeState\n }\n emissionsPerPerson {\n co2\n }\n }\n }\n }\n}WALK is used for direct street suggestions,\naccess, egress and transfers.{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.199196699999995, longitude: 24.9397302}}}\n destination: {location: {coordinate: {latitude: 60.168438, longitude: 24.929283}}}\n first: 2\n modes: {transit: {transit: [{mode: RAIL}]}}\n ) {\n pageInfo {\n endCursor\n }\n edges {\n node {\n start\n end\n legs {\n from {\n name\n }\n to {\n name\n }\n start {\n scheduledTime\n }\n end {\n scheduledTime\n }\n mode\n duration\n realtimeState\n }\n emissionsPerPerson {\n co2\n }\n }\n }\n }\n}fist: 5)modes: {transit: {transit: [{mode: BUS}, {mode: RAIL}, {mode: TRAM}, {mode: FERRY}]}})preferences: {street: {walk: {speed: 1.7}}})Use a 10 minute safety margin for transfers (preferences: {street: { transit: {transfer: {slack: \"10m\"}}})
Use a 5 minute boarding cost (preferences: {street: {walk: {boardCost: 300}}})
boardCost: 300 is used and there is a 48min itinerary with one boarding and a 45min itinerary with two boardings, the 48 minute itinerary is returned, because its total cost is smaller (48min + 5min vs. 45min + 5min + 5min)Use multiplier of 2.1 for walk reluctance to prefer routes with less walking (preferences: {street: {walk: {reluctance: 2.1}}})
Specific departure date and time
\ndateTime: {earliestDeparture: \"2024-06-13T14:30+03:00\"} In ISO-8601-formatted datetime with offset, e.g. 2024-06-13T14:30+03:00 for 2:30pm on June 13th 2024 at Helsinki's offset from UTC.{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.179267, longitude: 24.951501}}, label: \"Hakaniemi, Helsinki\"}\n destination: {location: {coordinate: {latitude: 60.1762, longitude: 24.836584}}, label: \"Keilaniemi, Espoo\"}\n first: 5\n dateTime: {earliestDeparture: \"2024-06-13T14:30+03:00\"}\n modes: {transit: {transit: [{mode: BUS}, {mode: RAIL}, {mode: TRAM}, {mode: FERRY}]}}\n preferences: {street: {walk: {speed: 1.7, reluctance: 2.1, boardCost: 300}}, transit: {transfer: {slack: \"10M\"}}}\n ) {\n pageInfo {\n endCursor\n }\n edges {\n node {\n walkDistance\n duration\n legs {\n from {\n lat\n lon\n name\n stop {\n code\n name\n }\n }\n to {\n lat\n lon\n name\n stop {\n code\n name\n }\n }\n trip {\n tripHeadsign\n routeShortName\n }\n distance\n legGeometry {\n length\n points\n }\n }\n }\n }\n }\n}earliestDeparture arguments.{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.168992, longitude: 24.932366}}, label: \"Kamppi, Helsinki\"}\n destination: {location: {coordinate: {latitude: 60.175294, longitude: 24.684855}}, label: \"Pisa, Espoo\"}\n first: 1\n ) {\n pageInfo {\n endCursor\n }\n edges {\n node {\n start\n end\n legs {\n nextLegs(numberOfLegs: 3) {\n start {\n scheduledTime\n }\n }\n from {\n name\n }\n to {\n name\n }\n start {\n scheduledTime\n }\n end {\n scheduledTime\n }\n mode\n duration\n }\n \n }\n }\n }\n}There are two types of via locations: pass-through via locations and visit via locations. With pass-through\nvia locations, it is only possible to choose stop locations as via locations and you must either board or alight\na vehicle on the stop or go through the stop on public transportation. With visit via locations, going through\nthe stop on a vehicle is not possible, but alighting or boarding a vehicle at the stop is possible. Visit via\nlocations also support coordinates that one must travel through on street (without being on a transit vehicle).\nCurrently, it is not possible to use both types of via locations in the same query.
\n{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.199196699999995, longitude: 24.9397302}}}\n destination: {location: {coordinate: {latitude: 60.168438, longitude: 24.929283}}}\n via: [ {\n passThrough: {\n stopLocationIds: \"HSL:1122127\"\n }\n } ]\n first: 2\n ) {\n pageInfo {\n endCursor\n }\n edges {\n node {\n start\n end\n legs {\n stopCalls {\n stopLocation {\n ... on Stop {\n gtfsId\n }\n }\n }\n from {\n name\n stop {\n gtfsId\n }\n viaLocationType\n }\n to {\n name\n stop {\n gtfsId\n }\n viaLocationType\n }\n start {\n scheduledTime\n }\n end {\n scheduledTime\n }\n }\n }\n }\n }\n}{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.199196699999995, longitude: 24.9397302}}}\n destination: {location: {coordinate: {latitude: 60.168438, longitude: 24.929283}}}\n via: [ {\n visit: {\n coordinate: {\n latitude: 60.1950122434621\n longitude: 24.9390506744384\n }\n }\n },\n {\n visit: {\n stopLocationIds: [\"HSL:1122127\"]\n }\n }]\n first: 2\n ) {\n pageInfo {\n endCursor\n }\n edges {\n node {\n start\n end\n legs {\n from {\n name\n viaLocationType\n }\n to {\n name\n viaLocationType\n }\n start {\n scheduledTime\n }\n end {\n scheduledTime\n }\n }\n }\n }\n }\n}{\n planConnection(\n origin: {location: {coordinate: {latitude: 60.199196699999995, longitude: 24.9397302}}}\n destination: {location: {coordinate: {latitude: 60.168438, longitude: 24.929283}}}\n first: 2\n ) {\n pageInfo {\n endCursor\n }\n edges {\n node {\n start\n end\n legs {\n fareProducts {\n product {\n id\n name\n ... on DefaultFareProduct {\n price {\n amount\n }\n }\n }\n }\n from {\n name\n }\n to {\n name\n }\n start {\n scheduledTime\n }\n end {\n scheduledTime\n }\n \n }\n }\n }\n }\n}