Migrate to Intermodal Routing API v8

This document highlights the most important changes necessary to migrate to the new version (v8).

Note

The missing API versions from v1 to v8 are due to internal version alignment.

Request

This section describes changes in the request.

Parameters Added

vehicle[modes], vehicle[enable]

vehicle[modes] vehicle[enable]
Format Array of Modes (strings) or Array of Excluded modes (strings) Array of strings
Behavior Modes filter used to determine which vehicle modes to include in the response. By default, all supported vehicle modes are permitted. Route parts where the private vehicle modes are allowed. By default, vehicle modes are not allowed (transit[enable]=[]).

Note

The value for vehicle could be a private car or a bicycle.

transit[modes], transit[enable]

transit[modes] transit[enable]
Format Array of Modes (strings) or Array of Excluded modes (strings) Array of strings
Behavior Mode filter used to determine which transit modes to include in the response. By default, all supported transit modes are permitted. Route parts where the transit modes are allowed. By default, transit modes are allowed everywhere in the route (transit[enable]=["routeHead","routeTail","entireRoute"]).

taxi[modes], taxi[enable]

taxi[modes] taxi[enable]
Format Array of Modes (strings) or Array of Excluded modes (strings) Array of strings
Behavior Modes filter used to determine which taxi modes to include in the response. By default, all supported taxi modes are permitted. Route parts where the taxi vehicle modes are allowed. By default, taxi modes are allowed everywhere in the route (taxi[enable]=["routeHead","routeTail","entireRoute"]).

rented[modes], rented[enable]

rented[modes] rented[enable]
Format Array of Modes (strings) or Array of Excluded modes (strings) Array of strings
Behavior Modes filter used to determine which rented modes to include in the response. By default, all supported rented modes are permitted. Route parts where the rented vehicle modes are allowed. By default, rented modes are allowed everywhere in the route (rented[enable]=["routeHead","routeTail","entireRoute"]).

Note

Rented vehicles or vehicle-sharing services are offered by third-party providers in major cities.

pedestrian[maxDistance]|pedestrian[speed]

pedestrian[maxDistance] pedestrian[speed]
Format integer, 0-6000 float, 0.5-2
Behavior Maximum walking distance (meters). By default, it is set to 2000. Maximum walking speed (meters per second). By default, it is set to 1.

Parameters Changed

The following parameters are changed in this migration.

Base URL, Version, Resource

Parameter HERE v1 HERE v8
Base URL string, https://mobility.ls.hereapi.com/v1/route string, https://intermodal.router.hereapi.com
Version string, /v1 string, /v8
Resource string, /route string, /routes

dep vs origin

The migration renames dep (v1) parameter to origin (v8).

dep origin
Format string, {lat},{lng}[,{name}] string, {lat},{lng}[;name={name}]
Behavior Sets WGS-84 compliant departure coordinates. Sets WGS-84 compliant origin coordinates.

arr vs destination

The migration renames arr (v1) parameter to destination (v8).

arr destination
Format string, {lat},{lng}[,{name}] string, {lat},{lng}[;name={name}]
Behavior Sets WGS-84 compliant arrival coordinates. Sets WGS-84 compliant destination coordinates.

time vs departureTime/arrivalTime

This migration renames time (v1) parameter to departureTime (v8).

time departureTime
Format DateTime,
YYYY-mm-ddTHH:MM:SS(.NNN)(Z|+/-AA:BB)
DateTime,
YYYY-mm-ddTHH:MM:SS(.NNN)(Z|+/-AA:BB)
Behavior Specifies the departure/arrival time (ISO 8601). When the optional timezone offset is not specified, time is assumed to be local. Sets departure time. See RFC 3339, section 5.6.

intermodal_max vs alternatives

This migration renames intermodal_max (v1) parameter to alternatives (v8).

intermodal_max alternatives
Format integer, 1-6 integer, 0-5
Behavior Sets the max number of Park and Ride routes to be returned in the response. By default, it is set to 3. Values greater than 6 are clipped to 6. Sets the number of alternative routes to return aside from the optimal route. By default, it is set to 0.

car_change_strategy vs strategy

This migration renames car_change_strategy (v1) parameter to strategy (v8). It is set through the via=strategy={strategy} parameter (v8).

car_change_strategy strategy
Format string, snake_case string, camelCase
Behavior Sets the strategy to find Park and Ride routes. By default, it is set to diverse_choices. Sets the strategy to find Park and Ride routes. By default, it is set to diverseChoices.

parking_lot_name, parking_lot_coords vs place:parkingLot

This migration renames parking_lot_name, parking_lot_coords (v1) parameter to place:parkingLot (v8). It is set through the via=place:parkingLot (v8) parameter.

parking_lot_name, parking_lot_coords place:parkingLot
Format string, name, {lat},{lng} string, place:parkingLot
Behavior Sets the name and geo-coordinates for parking lot. Ignored unless the value of strategy is single_lot. Mutually exclusive parameters. Sets the strategy to find Park and Ride routes. By default, it is set to diverseChoices.

details, graph, maneuvers vs return=intermediate,polyline,actions

This migration renames details, graph, maneuvers (v1) parameter to intermediate, polyline, actions (v8). They can be set through the return (v8) parameter. By default, all options are disables.

details, graph, maneuvers return=intermediate,polyline,actions
Format boolean, 1/0 array of strings, intermediate,polyline,...
Behavior Enables/Disables response options. By default, only details is enabled. All options are disabled by default.

Note

The following attributes were added to the sections parameter in the response:

  • travelSummary: Enables summary for the travel portion of the section.
  • fares: List of fares/tickets to cover a section of the route.

Parameters Removed

The following parameters are removed in this migration.

Format

This migration removes the Format parameter (v1). The response is always returned in JSON format (v8).

arrival

This migration removes arrival parameter (v1) as the departureTime/arrivalTime parameters can now be set individually (v8).

strict

This migration removes strict parameter (v1). By default, it is set to 0 (v8).

routingMode

This migration removes routingMode parameter (v1). By default, it is set to realtime (v8).

Response

This section describes changes in the response.

Parameters Added

This migration introduces the following parameters in response (v8):

  • notices: To response object, and routes, and sections parameters
  • spans: For more information, see the Routing API v8 Developer Guide
  • type: Similar to mode parameter (v1)
  • preActions, actions, postActions: Similar to Guidance parameter (v1). For more information, see Action Concept
  • intermediateStops
  • fares: Similar to Tariff parameter (v1)
  • travelSummary: Similar to Journey parameter (v1)
  • agency, attributions: Similar to Operators parameter (v1)
  • transport: Similar to Transport in Dep parameter (v1) in sections. For more information, see Transport Concept

Parameters Changed

This migration introduces the following changes to parameters in response (v8):

  • renames Connection parameter (v1) to routes (v8)
  • renames Sec parameter (v1) to sections (v8)
  • renames Dep and Arr parameters (v1) to departure and arrival (v8)
  • renames Stn parameter (v1) to place (v8)
  • renames distance parameter (v1) to length (v8)
  • changes the integer mode parameter (v1) to string (v8)
  • renames x, and y parameters (v1) to lng, and lat (v8)
  • renames graph parameter (v1) to polyline (v8) and changes its format to Flexible Polyline

Parameters Removed

This migration removes the following parameters in (v8) response:

  • Res
  • valid_until
  • context
  • serviceUrl
  • mode: From sections parameter (v1)
  • transfers
  • duration: From sections parameter (v1)
  • Guidance
  • Freq: From Dep parameter (v1) in sections
  • Journey
  • Tariff
  • Transport
  • Operators

Codes

The following table describes the response codes changed in this migration.

v1 error code v8 error code Status code Description
GW100 E602000 400 Bad request Wrong parameter type or parameter missing
I4 N/A 401 Unauthorized for wrong credential, 403 Forbidden for access not allowed N/A
GW0001 N/A 200 OK Returns empty routes list and notice object
GW0002 E602100, E602101, E602102 504 Gateway Timeout, 503 Service Unavailable, 502 Bad Gateway Backend failed to provide a response
GW0006 E602103 500 Internal Server Error Unexpected error
GW0007 N/A 200 OK No support for this API in this area
K9360 E602104 400 Bad request Invalid Period

Examples

Note

The Intermodal Routing API v1 example uses a HERE API Key to authenticate the request. HERE Token Credentials authentication is only possible in Intermodal Routing API v8. For information on other possible options, see the Identity & Access Management Guide.

results matching ""

    No results matching ""