Topics:

Itinerary planning

If you are not yet familiar with GraphQL and GraphiQL it is highly recommended to review those pages at first.

Glossary

Term Explanation
Itinerary A 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
Leg One part of an itinerary, e.g. walking to a bus stop or a bus ride between two stops.
Origin A geographical point where an itinerary begins.
Destination A geographical point where an itinerary ends.

Note about Itinerary leg geometries

You can ask the server to return geometries for itineraries. The API will return them in Google polyline-encoded format. It looks like this:

"legGeometry": {
  "length": 349,
  "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\\"
}

You can use this tool to see what the polyline looks on a map.

See the following examples on how to decode and use polylines:

Query examples

Note: For more details about the query type plan and its parameters you can use the Documentation Explorer provided in GraphiQL.

Itinerary planning can be tuned by multiple arguments of the plan query.

  • Time arguments (e.g. minTransferTime, bikeSwitchTime) are taken into account literally when planning the itinerary

    • For example, if minTransferTime is set to 2 minutes, it is not possible to continue the journey by another vehicle within two minutes after disembarking one vehicle
    • Values of time arguments are included in the returned duration of an itinerary
    • For example, if there is a 15 minute bicycling leg and bikeSwitchTime is set to 1 minute, the returned duration of the bicycling leg will be 17 minutes

  • Cost arguments (e.g. walkBoardCost) on the other hand are not hard limits, but preferences

    • For example, if walkBoardCost is set to 2 minutes, 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.
    • Cost is not included in the returned duration of an itinerary
    • For example, if there is a 15 minute bicycling leg and bikeSwitchCost is set to 1 minute, the returned duration of the bicycling leg will be 15 minutes

  • Multiplier arguments (e.g. walkReluctance, modeWeight) are used to multiply costs of an leg

    • For example, if walkReluctance is set to 3.0, the cost of each walking section will be multiplied by 3 and thus itineraries with less walking are preferred

Plan an itinerary from location (60.168992,24.932366) to (60.175294,24.684855)

  1. Click this link to run the query below in GraphiQL.
{
  plan(
    from: {lat: 45.744620, lon: 21.246866}
    to: {lat: 45.751619, lon: 21.216655}
    numItineraries: 3
  ) {
    itineraries {
      legs {
        startTime
        endTime
        mode
        duration
        realTime
        distance
        transitLeg
      }
    }
  }
}
  1. Press play in GraphiQL to execute the query.

Basic route from Complexul Studentesc (Complex) to Iulius Town (Lipovei)

  • Origin and destination locations can be named by using arguments fromPlace and toPlace instead of to and from

    • Values for arguments fromPlace and toPlace are in format <name>::<lat>,<lng>
  • Click this link to run the query below in GraphiQL.
{
  plan(
    fromPlace: "Complex Studentesc::45.748078,21.236596",
    toPlace: "Iulius Town::45.766413,21.227519",
  ) {
    itineraries{
      walkDistance,
      duration,
      legs {
        mode
        startTime
        endTime
        from {
          lat
          lon
          name
          stop {
            code
            name
          }
        },
        to {
          lat
          lon
          name
        },
        agency {
          gtfsId
	  name
        },
        distance
        legGeometry {
          length
          points
        }
      }
    }
  }
}
  1. Press play in GraphiQL to execute the query.

Plan an itinerary using only WALK and TRAM modes

  1. Click this link to run the query below in GraphiQL.
{
  plan(
    from: {lat: 45.744620, lon: 21.246866}
    to: {lat: 45.751619, lon: 21.216655}
    numItineraries: 3
    transportModes: [{mode: WALK}, {mode: TRAM}]
  ) {
    itineraries {
      legs {
        startTime
        endTime
        mode
        duration
        realTime
        distance
        transitLeg
      }
    }
  }
}
  1. Press play in GraphiQL to execute the query.

Plan an itinerary from Hakaniemi to Keilaniemi and modify the following parameters:

  • Return five results: (numItineraries: 5)
  • Use transportation modes other than subway (transportModes)
  • Walking speed of 1,7m/s (walkSpeed: 1.7)
  • Use a 10 minute safety margin for transfers (minTransferTime: 600)

  • Use a 5 minute boarding cost (walkBoardCost: 300)

    • Boarding cost is used to prefer itineraries with less vehicle boardings
    • For example, if walkBoardCost: 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 (walkReluctance: 2.1)

    • Walking times are multiplied with this multiplier

  • Specific departure date and time

    • date in format YYYY-MM-DD
    • time in format hh:mm:ss
  • Click this link to run the query below in GraphiQL.
{
  plan(
    fromPlace: "Shopping City::45.725141,21.200891",
    toPlace: "Dumbravita::45.786172,21.237509",
    date: "2019-12-21",
    time: "23:28:00",
    numItineraries: 5,
    transportModes: [{mode: BUS}, {mode: FUNICULAR}, {mode:TRAM}, {mode:WALK}]
    walkReluctance: 2.1,
    walkBoardCost: 300,
    minTransferTime: 600,
    walkSpeed: 1.7,
  ) {
    itineraries{
      walkDistance
      duration
      legs {
        mode
        startTime
        endTime
        from {
          lat
          lon
          name
          stop {
            code
            name
          }
        }
        to {
          lat
          lon
          name
          stop {
            code
            name
          }
        }
        trip {
        	tripHeadsign
          routeShortName
        }
        distance
        legGeometry {
          length
          points
        }
      }
    }
  }
}
  1. Change arguments date and time.
  2. Press play in GraphiQL to execute the query.

Plan an itinerary using Park & Ride

  • Using qualifier PARK for CAR mode plans an itinerary using Park & Ride, i.e. the first leg of the journey is done by driving to a car park and continuing by public transportation from there
  • Click this link to run the query below in GraphiQL.
{
  plan(
    fromPlace: "Shopping City::45.725141,21.200891",
    toPlace: "Dumbravita::45.786172,21.237509",
    transportModes: [{mode: CAR, qualifier: PARK}, {mode: TRANSIT}, {mode:WALK}]
  ) {
    itineraries{
      walkDistance
      duration
      legs {
        mode
        startTime
        endTime
        duration
        from {
          lat
          lon
          name
          stop {
            code
            name
          }
        }
        to {
          lat
          lon
          name
          stop {
            code
            name
          }
          carPark {
            carParkId
            name
          }
        }
        trip {
        	tripHeadsign
          routeShortName
        }
        distance
        legGeometry {
          length
          points
        }
      }
    }
  }
}
  1. Press play in GraphiQL to execute the query.

Plan an itinerary and query fare information

  • Note: Currently no fare information is available
  • Click this link to run the query below in GraphiQL.
{
  plan(
    from: {lat: 45.744620, lon: 21.246866}
    to: {lat: 45.751619, lon: 21.216655}
    numItineraries: 3
  ) {
    date
    itineraries {
      legs {
        startTime
        endTime
        mode
        duration
        realTime
        distance
        transitLeg
      }
      fares {
        type
        cents
        currency
      }
    }
  }
}
  1. Press play in GraphiQL to execute the query.

Plan an itinerary with ticket type restrictions

Query list of available ticket types

  • Field fareId contains ticket type ID that can be used with plan query
  • Field zones contains a list of zones where the ticket is valid
  • Click this link to run the query below in GraphiQL.
{
  ticketTypes {
    fareId
    price
    currency
    zones
  }
}
  1. Press play in GraphiQL to execute the query.

Plan an itinerary with AB ticket

  • The following query plans an itinerary from Helsinki (zone A) to Tikkurila (zone C) using only AB ticket
  • Click this link to run the query below in GraphiQL.
{
  plan(
    from: {lat: 60.1713572, lon: 24.9416544}
    to: {lat: 60.29280, lon: 25.04396}
    numItineraries: 3
    allowedTicketTypes: "HSL:AB"
  ) {
    date
    itineraries {
      legs {
        startTime
        endTime
        mode
        route {
          gtfsId
        }
        from {
          name
          stop {
            zoneId
          }
        }
        to {
          name
          stop {
            zoneId
          }
        }
        duration
        distance
        transitLeg
      }
    }
  }
}
  1. Press play in GraphiQL to execute the query.