New features in 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.

Request

Parameters Added

vehicle[modes], vehicle[enable]

transit[modes], transit[enable]

taxi[modes], taxi[enable]

rented[modes], rented[enable]

pedestrian[maxDistance]|pedestrian[speed]

Parameters Changed

Base URL, Version, Resource

dep vs origin

arr vs destination

time vs departureTime/arrivalTime

intermodal_max vs alternatives

car_change_strategy vs strategy

parking_lot_name, parking_lot_coords vs place:parkingLot

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

Parameters Removed

Format

arrival

strict

routingMode

Response

Parameters Added

Parameters Changed

Parameters Removed

Codes

Examples

`vehicle[modes], vehicle[enable]`

`transit[modes], transit[enable]`

`taxi[modes], taxi[enable]`

`rented[modes], rented[enable]`

`pedestrian[maxDistance]`|`pedestrian[speed]`

`dep` vs `origin`

`arr` vs `destination`

`time` vs `departureTime/arrivalTime`

`intermodal_max` vs `alternatives`

`car_change_strategy` vs `strategy`

`parking_lot_name, parking_lot_coords` vs `place:parkingLot`

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

`arrival`

`strict`

`routingMode`