Simplifying Your Journey with HERE Public Transit Routing API v8

In our previous blogs, we explored the HERE Public Transit Next Departures and Station Search APIs, which provided valuable tools for accessing real-time departure information and discovering nearby transit stations. In this edition, we are excited to introduce the HERE Public Transit Routing API v8. 

Exploring the Public Transit Routing API v8

The Public Transit Routing API v8 offers the most efficient and relevant transit routes between any given pair of locations. By specifying start and end points, you can request public transit routes that utilize all available transit modes within a city or metropolitan area.

The response from the /routes endpoint consists of a series of sections representing legs of the route, each containing essential information such as departure and arrival times, as well as details about the mode of transportation. Additionally, you can choose to include other properties, such as the route shape encoded in the HERE Flexible Polyline format, by making optional requests.

Basic API Request

Getting started with the API is simple. A transit route calculation requires a single GET request, with the only required parameters being the origin and destination coordinates in WGS84 format: <latitude>,<longitude>.

        GET https://transit.router.hereapi.com/v8/routes
    ?origin=41.79457,12.25473
    &destination=41.90096,12.50243
Authorization: Bearer 

  

Optional Parameters and Use Cases

The Public Transit Routing API v8 caters to a variety of the following use cases by setting the following optional query parameters:

• departureTime and arrivalTime.

Use case: These two query parameters can be used to define routes based on arrival or departure times so that routes can be planned hours or days in advance.

Format: string <date-time> (Time)

Description: Specifies the time of departure and arrival as defined by either date-time or full-date T partial-time in RFC 3339, section 5.6 (for example, 2019-06-24T01:23:45). The requested time is converted to the local time at origin. When the optional timezone offset is not specified, time is assumed to be local. If neither departureTime or arrivalTime are specified, current time at departure location will be used. All Time values in the response are returned in the timezone of each location.

Example:

        GET https://transit.router.hereapi.com/v8/routes
    ?origin=41.79457,12.25473
    &destination=41.90096,12.50243
    &departureTime=2023-06-24T01:23:45
    &arrivalTime=2023-06-24T03:23:45
Authorization: Bearer 
  

• modes.

Use case: This parameter can be used to filter specific transit modes, such as rail or metro only.

Format: Array of strings (TransitModesFilter)

Description: Transit mode filter used to determine which modes of transit to include in the response. By default, all supported transit modes are permitted. Supported modes: highSpeedTrain, intercityTrain, interRegionalTrain, regionalTrain, cityTrain, bus, ferry, subway, lightRail, privateBus, inclined, aerial, busRapid, monorail, flight, spaceship. This parameter also support an exclusion list: It's sufficient to specify each mode to exclude by prefixing it with -. Mixing of inclusive and exclusive transit modes is not allowed.

Examples: subway,bus. will return only subways and busses, and -subway,-bus. will return all modes except subways and busses.

        GET https://transit.router.hereapi.com/v8/routes
    ?origin=41.79457,12.25473
    &destination=41.90096,12.50243
    &modes=subway,bus
Authorization: Bearer 
  

• pedestrian[maxDistance].

Use case: This parameter can be used to set a maximum distance for walking to the nearest transit stop/station or the walking speed.

Format: integer [0 .. 6000]

Description: Maximum allowed walking distance in meters (e.g. when looking for nearest stations). Default value is 2000.

Example:

        GET https://transit.router.hereapi.com/v8/routes
    ?origin=41.79457,12.25473
    &destination=41.90096,12.50243
    &pedestrian[maxDistance]=4500
Authorization: Bearer 
  

• changes.

Use case: This parameter can be used to specify the number of changes or transfers allowed during the journey

Format: integer [0 .. 6]

Description: Maximum number of changes or transfers allowed in a route. Unlimited number of changes is permitted when not set.

Example:

        GET https://transit.router.hereapi.com/v8/routes
    ?origin=41.79457,12.25473
    &destination=41.90096,12.50243
    &changes=4
Authorization: Bearer 
  

• alternatives.

Use case: This parameter can be used to set the number of alternatives route returned in the response. 

Format: integer [ 0 .. 5 ]

Description: Number of alternative routes to return aside from the optimal route. Default value is 0.

Example:

        GET https://transit.router.hereapi.com/v8/routes
    ?origin=41.79457,12.25473
    &destination=41.90096,12.50243
    &alternatives=2
Authorization: Bearer 
  

• return

Items Enum: "intermediate", "fares", "polyline", "actions", "travelSummary", "incidents" , and "bookingLinks"

Description:

• intermediate - List of intermediate stops within a section of the route. If enabled, the response includes intermediateStops attribute. Each intermediate stop includes stop/station names, WGS-84 geocoordinates, and the departure times at the stops.
• fares - List of fares/tickets to cover a section of the route.
• polyline - Polyline for the route in Flexible Polyline Encoding.
• actions - Actions (such as maneuvers or tasks) that must be taken to complete the section.
• travelSummary - Include summary for the travel portion of the section.
• incidents - Include a list of all incidents applicable to each section.
• bookingLinks - Include a list of links to book a ride for a section of the route.

Example:

        GET https://transit.router.hereapi.com/v8/routes
    ?origin=41.79457,12.25473
    &destination=41.90096,12.50243
    &return=polyline,actions,travelSummary
Authorization: Bearer 
  

Response

If the route calculation was successful, the /routes response contains the requested details about the calculated route:

• one optimal transit route, unless alternatives is greater than zero
• multiple transit sections with each segment (representing either a pedestrian or a transit segment) containing departure/arrival times, duration and coordinates
• the transit segment shows the actual stops or stations of departure and arrival. Optionally, all intermediate stops in between can be also requested using the parameter return=intermediate
• a set of operators that run the services included in the alternatives, including operator code, operator name and links to operator websites, if any
• the shape of the route in the polyline field encoded using Flexible Polyline

        {
  "routes": [
    {
      "id": "R00132f-C0",
      "sections": [
        {
          "id": "R00132f-C0-S0",
          "type": "pedestrian",
          "polyline": "BHkrsl9Y6503pHq9Gr1O9uB9uBhjCjmEAz1BjUp8B_1Kr2T5hKw0JruFxoKk6Dl-D",
          "departure": {
            "time": "2020-04-22T12:17:00+02:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 41.79457,
                "lng": 12.25473
              }
            }
          },
          "arrival": {
            "time": "2020-04-22T12:23:00+02:00",
            "place": {
              "name": "Fiumicino Aeroporto",
              "type": "station",
              "location": {
                "lat": 41.793466,
                "lng": 12.251997
              },
              "id": "415713377"
            }
          }
        },
        {
          "id": "R00132f-C0-S1",
          "type": "transit",
          "polyline": "BHsq1k9Yow_1pHr9sEk8sEzjGooJ7wFw9J_mE0iJngDg1Hn9Bw_IvC8jJkcg1H08BkkHgj9Bkh3E0rhDkriHoi6Nkl9egmqB4g3D4qJ49vBz9D0isB3-d89qI8gIwr_Bw2oB87_Ds9oB41oEgvUoyoD0xJ4rjE7jEgqjBrhiBs8jF4Swqa8sHghlBkm4BwngF8x-B4m3Ekq7BsixCgw0B8rmC4gTolrB8oE04rBngIgo8E_qHsqwD44CktyBs4KoppB0mgBg7sBgggF8vnD88sBoyY0k3F41kB88Y0mMgzSstXs4tB8jgCsorB40YkhpB7zBos-BnppBwlQrpF08V0rC8zV8kLo-NgsTolIw-a4hGwrkCoGgkDoGo4BA4rBoGo4Bg9D464B4SoyJAo4B4rBgxTo4B45YojEol9CoG4vEnG4vEvMwienGgvFv3CowU_xBolSn4BolS_nG4qsBnrKohhCn8E4zgB_6Oo8oDAo1FAoxCAg9DvMw2UwM4zyCnGw3CoG4mQ4rBw9TwwDw9TofwiFg-KgyaozQgxToqc41Vg9D4rBg7OwuOg-K40Ow3Cw7FwiFg-KghHo8doxCwpd4kCw9sBoqDw_hBgvFwzY4rBwwD4So4BofwiFgvFo9L4kbgmqB4yZw1mBsvHs9K03asuUoyd0oLk0J3D8mK7nCoiHvjCs9ZzkNwhcrtSsyDnzGw5QnrjBw3C_uFwla3uvBgZ3rBomZ3gxB4kCvpE4_Q36fgyB39C4kC_8Dkmaz10Bwlfn75Boh6Cz-zD48Pjha",
          "departure": {
            "time": "2020-04-22T12:23:00+02:00",
            "place": {
              "name": "Fiumicino Aeroporto",
              "type": "station",
              "location": {
                "lat": 41.793466,
                "lng": 12.251997
              },
              "id": "415713377"
            }
          },
          "arrival": {
            "time": "2020-04-22T12:55:00+02:00",
            "place": {
              "name": "Roma Termini",
              "type": "station",
              "location": {
                "lat": 41.90054,
                "lng": 12.502168
              },
              "id": "415712984"
            }
          },
          "transport": {
            "mode": "regionalTrain",
            "name": "LE",
            "category": "Regional Train",
            "color": "#4C8DC1",
            "textColor": "#000000",
            "headsign": "Roma Termini"
          },
          "agency": {
            "id": "aDmtre00",
            "name": "Trenitalia",
            "website": "http://www.trenitalia.com/"
          },
          "attributions": [
            {
              "id": "R00132f-C0-S1-link-0",
              "href": "http://creativecommons.org/licenses/by/3.0/it/",
              "text": "Some line names used in this product or service were edited to align with official transportation maps.",
              "type": "disclaimer"
            }
          ]
        },
        {
          "id": "R00132f-C0-S2",
          "type": "pedestrian",
          "polyline": "BHyvnm_YgztuuHw8GsqH",
          "departure": {
            "time": "2020-04-22T12:55:00+02:00",
            "place": {
              "name": "Roma Termini",
              "type": "station",
              "location": {
                "lat": 41.90054,
                "lng": 12.502168
              },
              "id": "415712984"
            }
          },
          "arrival": {
            "time": "2020-04-22T12:56:00+02:00",
            "place": {
              "type": "place",
              "location": {
                "lat": 41.90096,
                "lng": 12.50243
              }
            }
          }
        }
      ]
    }
  ]
}

  

Integration with Maps API for Javascript

The class H.service.publicTransit.Service encapsulates the HERE Public Transit API in a service stub, providing methods to access its resources. And the method getRoutes(params,onResult,onError) sends a request to the Public Transit API to o calculate a transit route. The supported parameters are the same as the REST requests above. 

        function calculateRouteFromAtoB (platform) {
  var router = platform.getPublicTransitService(),
      routeRequestParams = {
        origin: '52.5208,13.4093', // Fernsehturm
        destination: '52.5034,13.3280',  // Kurfürstendamm
        return: 'polyline,actions,travelSummary'
      };


  router.getRoutes(
    routeRequestParams,
    onSuccess,
    onError
  );
}
  

Sample Application

Conclusion

The HERE Public Transit Routing API v8 simplifies the process of planning public transit journeys. Its robust features, comprehensive routing options, and integration possibilities make it a valuable asset for developers creating transit-focused applications. Stay tuned for future updates, tutorials, and use cases showcasing the API's capabilities. Join the HERE developer Slack community and start simplifying public transportation routing today!