openapi: 3.0.2
info:
title: Matrix Routing API v8
version: 8.36.4
description: |
HERE Matrix Routing service calculates the travel duration and/or distances among multiple origins and destinations through both synchronous and asynchronous API calls.
license:
name: HERE Documentation License
url: https://legal.here.com/en-gb/terms/documentation-license
externalDocs:
description: Developer Guide and Release Notes
url: https://developer.here.com/documentation/matrix-routing-api
security:
- Bearer: []
- ApiKey: []
servers:
- url: https://matrix.router.hereapi.com/v8
tags:
- name: Matrix Calculation
description: |
Calculation of routing matrices in one of the following modes:
* Flexible
* Region
* Profile
The values of the `regionDefinition` and `profile` parameters determine which mode is used.
The following table describes the capabilities and limitations of each mode.
| Mode | regionDefinition parameter | profile parameter provided? | Custom Options & Time Awareness
(incl. live traffic) | Unlimited region | Matrix size limit
(synchronous) | Matrix size limit
(asynchronous) |
|----------|------------------------------|-------------------------------|---------------------------------------------------------|-------------------------------------------------------------------------------|------------------------------------|-------------------------------------|
| Flexible | `world` | no | yes | yes | 15 x 100 or 100 x 1 | 15 x 100 or 100 x 1 |
| Region | one of:- `circle`
- `boundingBox`
- `polygon`
- `autoCircle`| no | yes | no
origins and destinations must be within a region of max 400 km diameter | 500 x 500 | 10,000 x 10,000 |
| Profile | `world` | yes | no | yes | 500 x 500 or 1 x 2000 or 2000 x 1 | 10,000 x 10,000 |
Note that the combination of specifying a `profile` along with a `regionDefinition` not equal to `world` is not allowed.
## Synchronous vs. Asynchronous Requests
\
Matrix requests can be sychronous or asynchronous.
Use the `async` query parameter to indicate the request type. All 3 modes
are compatible with both sychronous and asynchronous requests.
Synchronous requests impose additional limitations on maximum matrix sizes (see table above).
- name: List Profiles
description: |
Supported predefined profiles for calculating matrices with routes of arbitrary length.
- name: API Information
description: Status information and metadata about the service
paths:
/matrix:
post:
operationId: postMatrix
tags:
- Matrix Calculation
summary: Submit matrix for calculation
description: |
Calculates a routing matrix based on provided `origins` and `destinations`.
Response will be provided synchronously (see `200` response) or asynchronously (see `202` response)
depending on the `async` query parameter.
Travel times will be included by default i.e., when `matrixAttributes` parameter is
not specified. To return only distances or both of them, specify the
corresponding flags in `matrixAttributes`.
Maximum request size is 10 MiB (uncompressed).
parameters:
- in: query
name: async
description: |
Specifies whether the response will be provided synchronously (`false`) or asynchronously (`true`).
See Synchronous vs. Asynchronous Requests.
schema:
type: boolean
default: true
- $ref: "#/components/parameters/X-Request-Id"
requestBody:
content:
"application/json":
schema:
$ref: "#/components/schemas/MatrixRequest"
examples:
Flexible mode (default transport mode, requesting travelTimes and distances):
value:
origins:
- lat: 52.5309 # HERE Deutschland GmbH
lng: 13.3849
- lat: 52.5202 # Bundestag
lng: 13.3730
destinations:
- lat: 52.5220 # Alexanderplatz
lng: 13.4133
- lat: 52.5163 # Brandenburger Tor
lng: 13.3777
regionDefinition:
type: world
matrixAttributes: ["travelTimes", "distances"]
Flexible mode (truck with poisonous goods):
value:
origins:
- lat: 52.5309 # HERE Deutschland GmbH
lng: 13.3849
- lat: 52.5202 # Bundestag
lng: 13.3730
destinations:
- lat: 52.5220 # Alexanderplatz
lng: 13.4133
- lat: 52.5163 # Brandenburger Tor
lng: 13.3777
regionDefinition:
type: world
transportMode: truck
truck:
shippedHazardousGoods:
- poison
Region mode (circle with traffic departure time):
value:
origins:
- lat: 52.5309 # HERE Deutschland GmbH
lng: 13.3849
- lat: 52.5202 # Bundestag
lng: 13.3730
destinations:
- lat: 52.5220 # Alexanderplatz
lng: 13.4133
- lat: 52.5163 # Brandenburger Tor
lng: 13.3777
departureTime: "2020-10-19T08:00:00-01:00"
regionDefinition:
type: circle
center:
lat: 52.5309
lng: 13.3849
radius: 25000
Region mode (auto-circle with 25 km margin):
value:
origins:
- lat: 52.5309 # HERE Deutschland GmbH
lng: 13.3849
- lat: 52.5202 # Bundestag
lng: 13.3730
destinations:
- lat: 52.5220 # Alexanderplatz
lng: 13.4133
- lat: 52.5163 # Brandenburger Tor
lng: 13.3777
regionDefinition:
type: autoCircle
margin: 25000
Profile mode (car fastest):
value:
origins:
- lat: 52.5309 # HERE Berlin
lng: 13.3849
- lat: 54.0924 # Rostock
lng: 12.0991
destinations:
- lat: 51.3397 # Leipzig
lng: 12.3731
- lat: 51.0504 # Dresden
lng: 13.7373
regionDefinition:
type: world
profile: carFast
responses:
"200":
$ref: "#/components/responses/MatrixResponse"
"202":
description: Matrix calculation was successfully submitted.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/MatrixStatus"
example:
matrixId: "bc79a808-dbac-4e49-88f2-27ec66a473ef"
status: "accepted"
statusUrl: "https://routing-matrix-region-1.router.hereapi.com/v8/matrix/bc79a808-dbac-4e49-88f2-27ec66a473ef/status"
"400":
description: Matrix request contains invalid parameters.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
example:
title: Input data failed validation
status: 400
code: E601202
cause: Region size exceeds limit of maximum diameter 400000 m
action: Reduce region diameter to maximum of 400000 m.
correlationId: bc79a808-dbac-4e49-88f2-27ec66a473ef
"401":
description: Authentication failed.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/AuthError"
example:
error: Unauthorized
error_description: Token Validation Failure - invalid time in token
"403":
description: Access denied.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/AuthError"
example:
error: Forbidden
error_description: Insufficient permissions
"413":
description: Payload too large. We support max. 10 MB (uncompressed).
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
"429":
description: Too many requests.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
"500":
description: Unexpected service error.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
/matrix/{matrixId}/status:
get:
tags:
- Matrix Calculation
summary: Status of submitted matrix calculation
description: |
Returns the status of a submitted asynchronous matrix calculation. Redirects to the
matrix result if the calculation is successfully completed.
**NOTE:** Please make sure to directly use the `statusUrl` returned by the /v8/matrix
call to check this status endpoint, including the provided region URL. Due to global
load balancing, using matrix.router.hereapi.com for the status endpoint may end up
resolving to a different region than the initial calculation, resulting in a 404 error.
operationId: getMatrixStatus
parameters:
- in: path
name: matrixId
schema:
type: string
required: true
description: Matrix ID obtained upon successful submission
- $ref: "#/components/parameters/X-Request-Id"
responses:
"200":
description: Matrix calculation is either in progress or completed with an error.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/MatrixStatus"
example:
matrixId: "bc79a808-dbac-4e49-88f2-27ec66a473ef"
status: "inProgress"
"303":
description: |
Matrix calculation completed successfully.
To get the result of the calculation, follow the redirect or use the `resultUrl` field
in the response.
Note: Most HTTP client libraries will follow redirects automatically. You might want to
configure your client to handle forwarding redirects differently.
headers:
Location:
schema:
type: string
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/MatrixStatus"
example:
matrixId: "bc79a808-dbac-4e49-88f2-27ec66a473ef"
status: "completed"
resultUrl: "/v8/matrix/bc79a808-dbac-4e49-88f2-27ec66a473ef"
"401":
description: Authentication failed.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/AuthError"
example:
error: Unauthorized
error_description: Token Validation Failure - invalid time in token
"403":
description: Access denied.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/AuthError"
example:
error: Forbidden
error_description: >
These credentials do not authorize access. Please contact your
customer representative or submit a request here
https://developer.here.com/contact-us to upgrade your account. You
can also get valid credentials by registering for a free trial
license on https://developer.here.com. For details, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html.
"404":
description: Status not found for given matrix ID.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
"500":
description: Unexpected service error.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
/matrix/{matrixId}:
get:
tags:
- Matrix Calculation
summary: Result of successfully completed calculation.
operationId: getMatrix
parameters:
- in: header
name: Accept-Encoding
schema:
type: string
enum: ["gzip"]
required: true
description: This header should be set as the result will always be a compressed stream.
- in: path
name: matrixId
schema:
type: string
required: true
description: Matrix ID obtained upon successful submission
- $ref: "#/components/parameters/X-Request-Id"
responses:
"200":
$ref: "#/components/responses/MatrixResponse"
"303":
description: |
Redirect to a self-signed URL of an AWS S3 resource containing the same content as
described in the `200` response.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
"400":
description: Bad request
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
example:
title: invalid HTTP request
status: 400
code: E601106
cause: invalid matrix ID
action: Check that the provided matrix ID is in the UUID v4 format.
correlationId: 0b3b6c47-6d1b-4641-ab22-4144454cd584
"401":
description: Authentication failed.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/AuthError"
example:
error: Unauthorized
error_description: Token Validation Failure - invalid time in token
"403":
description: Access denied.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/AuthError"
example:
error: Forbidden
error_description: >
These credentials do not authorize access. Please contact your
customer representative or submit a request here
https://developer.here.com/contact-us to upgrade your account. You
can also get valid credentials by registering for a free trial
license on https://developer.here.com. For details, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html.
"404":
description: Result not found for given matrix ID.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
"406":
description: |
Request is not acceptable. The client needs to provide the proactive
content negotiation `Accept-Encoding` header to signal that it supports `gzip`.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
"500":
description: Unexpected service error.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
/profiles:
get:
tags:
- List Profiles
summary: List supported predefined profiles.
description: |
It is guaranteed that with each minor API change profiles are only added to this list,
but are never removed or modified.
parameters:
- $ref: "#/components/parameters/X-Request-Id"
operationId: getProfiles
security: []
responses:
"200":
description: List of supported predefined profiles.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Profile"
uniqueItems: true
/profiles/{profileId}:
get:
tags:
- Profile Mode
summary: Get profile definition by its ID.
operationId: getProfile
security: []
parameters:
- in: path
name: profileId
description: |
Profile ID.
This parameter is case-sensitive.
schema:
type: string
required: true
- $ref: "#/components/parameters/X-Request-Id"
responses:
"200":
description: Profile with the requested ID.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/Profile"
"401":
description: Authentication failed.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/AuthError"
example:
error: Unauthorized
error_description: Token Validation Failure - invalid time in token
"403":
description: Access denied.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/AuthError"
example:
error: Forbidden
error_description: >
These credentials do not authorize access. Please contact your
customer representative or submit a request here
https://developer.here.com/contact-us to upgrade your account. You
can also get valid credentials by registering for a free trial
license on https://developer.here.com. For details, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html.
"404":
description: Profile not found for the given profile ID.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorMessage"
/openapi:
get:
tags:
- API Information
summary: This API specification
description: Returns this API specification in YAML format.
parameters:
- $ref: "#/components/parameters/X-Request-Id"
operationId: getOpenapi
security: []
responses:
"200":
description: Open API specification of this service in YAML format
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
text/plain:
schema:
type: string
/health:
get:
tags:
- API Information
summary: Health status of the service
description: Returns HTTP status code describing the health of the service.
parameters:
- $ref: "#/components/parameters/X-Request-Id"
operationId: getHealth
security: []
responses:
"200":
description: Service is healthy
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
"503":
description: Service is unhealthy
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
/version:
get:
tags:
- API Information
summary: Full version of the API
description: Full version of the API implemented by the service.
parameters:
- $ref: "#/components/parameters/X-Request-Id"
operationId: getVersion
security: []
responses:
"200":
description: Version document
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
content:
application/json:
schema:
$ref: "#/components/schemas/Version"
components:
parameters:
X-Request-Id:
name: X-Request-Id
description:
User-provided token that can be used to trace a request or a group
of requests sent to the service.
schema:
type: string
example: 8230d7ad-3f1c-4191-a8dd-f3c42026da89
in: header
headers:
X-Correlation-Id:
description: Auto-generated id that univocally identifies the request.
schema:
type: string
example: 4199533b-6290-41db-8d79-edf4f4019a74
X-Request-Id:
description:
User-provided token that can be used to trace a request or a group
of requests sent to the service.
schema:
type: string
example: 8230d7ad-3f1c-4191-a8dd-f3c42026da89
x-mrl:
description: |
Maximum route length (distance) in meters computed for the matrix.
Returned for all Flexible mode requests, even when `matrixAttributes` does not include `distances`.
Can be used to estimate the "complexity" of the request and understand the performance characteristics.
schema:
type: integer
example: 1007042
responses:
MatrixResponse:
description: |
Result matrix was calculated for the requested `origins` and `destinations`.
The matrix contains 2 optional flat arrays, `travelTimes` and `distances` depending
on the specified `matrixAttributes` request parameter. Each array represents a 2D matrix
where rows correspond to `origins` and columns to `destinations`. The `k`-th position in
the array corresponds to the `(i, j)` position in the matrix defined by the following
relationship:
```
k = num_destinations * i + j,
```
where `i` is origin and `j` is destination.
If the calculation of a route between `i` and `j` fails or yields a route that violates
some options, the response includes
another `errorCodes` array with a detailed error code for each failed calculation.
If the error code for the entry `(i, j)` is not 0 (success) or 3 (violated options) then the
value for the entry `(i, j)` in the `travelTimes` and `distances` response array(s)
is unspecified; the client using the response should not rely on the value of the
entry `(i, j)` in the response array(s) in this case.
For the list of supported error codes cf. `errorCodes`.
If the calculation of the entire matrix failed due to an expected error, e.g. timeout,
the `matrix` field is none and the `error` field contains a detailed error description.
headers:
X-Correlation-Id:
$ref: "#/components/headers/X-Correlation-Id"
X-Request-Id:
$ref: "#/components/headers/X-Request-Id"
x-mrl:
$ref: "#/components/headers/x-mrl"
content:
application/json:
schema:
$ref: "#/components/schemas/MatrixResponse"
example:
matrixId: "bc79a808-dbac-4e49-88f2-27ec66a473ef"
matrix:
numOrigins: 2
numDestinations: 2
travelTimes: [73, 1231, 983, 400]
distances: [10, 109, 10, 30]
regionDefinition:
type: circle
center:
lat: 52.53787
lng: 13.40896
radius: 10000
securitySchemes:
ApiKey:
type: apiKey
in: query
name: apiKey
description: >
A key generated specifically to authenticate API requests. For more information
on how to get an API key, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html.
Bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: |
A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.
For more information on how to get a bearer token, see https://developer.here.com/documentation/identity-access-management/dev_guide/index.html.
schemas:
MatrixRequest:
type: object
required:
- origins
- regionDefinition
properties:
origins:
type: array
description: |
List of waypoints defining origins of the routes in the matrix.
**NOTE:** Maximum number of matched waypoints on a single segment is limited to 100 and this includes waypoints from both origins and destinations.
items:
$ref: "#/components/schemas/Waypoint"
minItems: 1
maxItems: 10000
example:
- lat: 52.53787
lng: 13.40896
- lat: 52.52387
lng: 13.70346
destinations:
type: array
description: |
List of waypoints defining destinations of the routes in the matrix. When no
`destinations` are specified, the matrix is assumed to be quadratic with `origins` used
as destinations.
**NOTE:** Maximum number of matched waypoints on a single segment is limited to 100 and this includes waypoints from both origins and destinations.
items:
$ref: "#/components/schemas/Waypoint"
minItems: 1
maxItems: 10000
regionDefinition:
$ref: "#/components/schemas/RegionDefinition"
profile:
description: |
A profile ID enables the calculation of matrices with routes of arbitrary length.
A profile comes with a set of predefined options. It is not possible to override them.
*All* profiles explicitly set `departureTime` to `any` and require that the obligatory
request parameter `regionDefinition` is set to `world`.
| Profile ID | Description |
| --------------------- | -------------------------------------------- |
| `carFast` | Car with fast routing mode |
| `carShort` | Car with short routing mode |
| `truckFast` | Truck with fast routing mode |
| `pedestrian` | Pedestrian transport mode |
| `bicycle` | Bicycle transport mode |
For the precise definition of a profile use the `profiles/{profileId}` endpoint, which
returns the routing options predefined for the profile.
It is guaranteed that with each minor API change profiles are only added to the above
list, but are never removed or modified. Profile IDs are case-sensitive.
type: string
enum:
["carFast", "carShort", "truckFast", "pedestrian", "bicycle"]
departureTime:
$ref: "#/components/schemas/DepartureTimeWithAny"
routingMode:
$ref: "#/components/schemas/RoutingMode"
transportMode:
$ref: "#/components/schemas/TransportMode"
avoid:
$ref: "#/components/schemas/Avoid"
allow:
$ref: "#/components/schemas/Allow"
maxSpeedOnSegment:
$ref: "#/components/schemas/MaxSpeedOnSegment"
exclude:
$ref: "#/components/schemas/Exclude"
vehicle:
description: Different vehicle options to use during route calculation.
allOf:
- $ref: "#/components/schemas/Vehicle"
truck:
description: Renamed to `vehicle`
deprecated: true
allOf:
- $ref: "#/components/schemas/Truck"
truckOptions:
description: Renamed to `truck`
deprecated: true
allOf:
- $ref: "#/components/schemas/Truck"
scooter:
description: Specific scooter options to use during route calculation when `transportMode = scooter`.
allOf:
- $ref: "#/components/schemas/Scooter"
pedestrian:
description: Specific pedestrian options to use during route calculation when `transportMode = pedestrian`.
allOf:
- $ref: "#/components/schemas/Pedestrian"
taxi:
description: Specific taxi options to use during route calculation when `transportMode = taxi`.
allOf:
- $ref: "#/components/schemas/Taxi"
matrixAttributes:
description: |
Defines which attributes are included in the response as part of the data representation
of the matrix entries summaries.
Can be used together with `profile` parameter.
type: array
uniqueItems: true
items:
type: string
enum: ["travelTimes", "distances"]
default: ["travelTimes"]
traffic:
$ref: "#/components/schemas/Traffic"
violationMapping:
type: array
description: |
List of items for mapping certain violated restrictions to specific error codes in the matrix.
This mapping can classify restrictions or blockages while still providing
the resulting times and distances in the calculated matrix.
Items are grouped into categories and evaluated collectively. Error codes are associated
with the `category`, rather than being tied to individual restrictions or blockages.
There are two distinct types of mappings: one for violated restrictions and another
for traffic-related blockages. These mappings should be maintained as separate violation
mapping items, although they can belong to the same category.
Each violation mapping defines how a particular violation should be managed based on
additional attributes:
`include`: the violated restriction is added to a mapped
category instead of causing a hard error code 3.
`exclude`: the violated restriction is not added to a mapped
category and still causes an error code 3. This is the default for
height and grossWeight.
`ignore`: the algorithm is not taking the restriction or
property / attribute of the road into consideration.
This is the default attribute for restrictions on bridge or time-dependent
restrictions.
Examples:
- "height": "include", "grossWeight": "include" -> map violations with
violated height and violated grossWeight.
- "height": "include", "grossWeight": "exclude" -> map violations with
violated height and NOT violated grossWeight.
- "height": "include", "grossWeight": "ignore" -> map violations with
violated height, violation or non-violation of grossWeight doesn't
matter.
- "height": "include", "currentWeight": "include" -> map violations with
violated height and violated currentWeight.
- "height": "include", "currentWeight": "exclude" -> map violations with
violated height and NOT violated currentWeight.
- "height": "include", "currentWeight": "ignore" -> map violations with
violated height, violation or non-violation of currentWeight doesn't
matter.
Unless include or exclude is stated, grossWeight or height can be
mapped regardless, if it is timeDependent or on a bridge.
Please see `matrix` description in the response section for more
information about error codes.
If additional types of restrictions are supported for mapping in the
future, they will default to "ignore" to ensure consistent results.
A violation mapping item belongs to either of two categories.
Mappings belonging to the same category are evaluated together and if they apply, it is reflected
in the errorCodes of the resulting matrix.
Two types of mappings are supported: violated restrictions or traffic blockages. These cannot
be combined into a single violation mapping item; each item must belong to one specific type.
Mapping of traffic blockages is supported for transport modes `car` and `truck`.
items:
$ref: "#/components/schemas/ViolationMappingItem"
maxItems: 10
Distance:
type: integer
minimum: 0
description: Distance in meters
Waypoint:
description: WSG-84 coordinates with additional metadata
type: object
required: ["lat", "lng"]
properties:
lat:
description: Latitude in WGS-84 degrees.
type: number
format: double
lng:
description: Longitude in WGS-84 degrees.
type: number
format: double
course:
description: |
The direction (degrees in clockwise direction, 0 is north) from which this waypoint should be approached or in which it should be left.
Values outside the range are wrapped to the range
type: number
format: double
minimum: 0
maximum: 359
sideOfStreetHint:
$ref: "#/components/schemas/SideOfStreetHint"
nameHint:
description: |
Directs the route calculation to search for a location with a similar name
Empty string values are ignored.
type: string
minCourseDistance:
description: |
Instructs the routing service to try to find a route that avoids actions for
the indicated distance. For example, if the origin is determined by a moving
vehicle, the user might not have time to react to early actions. Values greater
than 2000 meters will be capped at 2000 meters.
type: integer
format: int32
minimum: 0
radius:
description: |
Distance in meters.
Instructs the router to consider all places within the given radius as potential candidates for matching the waypoint.
This can be either because it is not important which place is used, or because it is unknown. Values higher than 200 meters are not supported.
Option cannot be combined with `snapRadius`.
maximum: 200
allOf:
- $ref: "#/components/schemas/Distance"
snapRadius:
description: |
Distance in meters.
Instructs the router to match the waypoint, within the specified radius, to the most "significant" road.
In contrast to the regular `radius` parameter, `snapRadius` sorts potential candidates in order of "significance".
For example, a highway is more significant on a zoomed-out map than a national road, a national road is more significant than a city road, etc.
Hence, `snapRadius` cannot be combined with `radius` or `radiusPenalty` parameters. The typical use case for `snapRadius` is when selecting a waypoint on
a zoomed-out view of a map on a drag-and-drop interface. The expectation on such UIs is that only roads that are visible at that zoom level
are considered for matching and a large snapRadius would enable that.
maximum: 1000000
allOf:
- $ref: "#/components/schemas/Distance"
radiusPenalty:
description: |
Penalty as percentage.
Used in conjunction with the `radius` parameter.
Router will match the waypoint within the specified radius and apply a penalty to candidates based on their air distance to the waypoint.
This penalty is proportional to the given percentage, where 100 is just the cost of the air distance, and 200 is twice the cost of the air distance.
The penalty must be chosen so that, when multiplied by the radius, the result is less than or equal to 7200.
Regardless, only values up to and including 10000 will be accepted.
This means that a maximum penalty of 3600% is allowed for a radius of 200m, 7200% for 100m and 10000% for 72m and less.
Higher values will result in an error response. `radiusPenalty` cannot be combined with `snapRadius`.
**Alpha**: This parameter is in development. It may not be stable and is subject to change.
type: integer
format: int32
minimum: 0
maximum: 10000
segmentIdHint:
description: |
Causes the router to try and match to the specified segment. Waypoint coordinates need to be on the segment,
otherwise waypoint will be matched ignoring the segment hint.
This parameter can be used when the waypoint is too close to more than one segment to force matching to a specific one.
type: string
onRoadThreshold:
description: |
In meters, allows specifying a distance within which the waypoint could be considered as being on a highway/bridge/tunnel/sliproad.
Within this threshold, the attributes of the segments do not impact the matching. Outside the threshold only segments which aren't
one of highway/bridge/tunnel/sliproad can be matched.
type: integer
format: int32
minimum: 0
example:
lat: 52.5292745
lng: 13.3796490
course: 143
SideOfStreetHint:
description: A hint as to which side of the street should be preferred for this waypoint. This hint should be a point next to the street, e.g. a POI
type: object
required: ["lat", "lng"]
properties:
lat:
description: Latitude in WGS-84 degrees.
type: number
format: double
lng:
description: Longitude in WGS-84 degrees.
type: number
format: double
match:
description: |
Determines how the side of street hint should be handled
* `always`: Always use side of street hint
* `onlyIfDivided`: Only use side of street hint on divided roads
type: string
enum: ["always", "onlyIfDivided"]
default: "onlyIfDivided"
example:
lat: 52.5293001
lng: 13.3797097
match: "always"
DepartureTimeWithAny:
description: |
Time of departure at all origins, in ISO 8601 (RFC 3339) format: the time zone offset is required.
When `departureTime` is not specified, it is implicitly assumed to be the current time.
The special value `any` enforces non time-aware routing.
In particular, dynamic traffic information is not taken into account in this case and only
free-flow speeds based on historical traffic are applied.
type: string
RoutingMode:
description: |
Specifies which optimization is applied during the calculation.
* `fast`: Route calculation from start to destination optimized by travel time. In many
cases, the route returned by `fast` mode may not be the route with the fastest
possible travel time. For example, the routing service may favor a route that remains on
a highway, even if a faster travel time can be achieved by taking a detour or shortcut
through an inconvenient side road.
* `short`: Route calculation from start to destination disregarding any speed information.
In this mode, the distance of the route is minimized, while keeping the route sensible.
This includes, for example, penalizing turns. Because of that, the resulting route will
not necessarily be the one with minimal distance.
Notes:
* The following Transport modes only support `fast` routingMode
- `bicycle`
- `bus`
- `pedestrian`
- `privateBus`
- `scooter`
- `taxi`
type: string
enum:
- fast
- short
default: fast
TransportMode:
type: string
description: |
Depending on the transport mode special constraints, speed attributes and weights are
taken into account during route calculation.
* `car`: Route calculation for cars.
* `truck`: Route calculation for trucks. This mode considers truck access- and physical limitations. It also
uses different speed assumptions when calculating the route.
* `pedestrian`: Route calculation for pedestrians.
* `bicycle`: Route calculation for bicycles.
* `taxi`: Route calculation for taxis. This mode takes into account taxi restricted streets as well as streets
reserved for exclusive taxi access. It does not, however, consider exclusive lanes in otherwise shared streets.
Also, the taxi exclusive streets are used only if either the origin or destination are on them.
* `scooter`: Route calculation for scooters. This mode takes into account roads that are allowed for scooters,
however dedicated scooter lanes are not supported. It does not consider highways, unless the special parameter
`allowHighway` is provided.
* `bus`: Route calculation for buses that are allowed to drive through the bus-only roads.
* `privateBus`: Route calculation for buses that are not allowed to drive through the bus-only roads.
Note:
`bicycle`, `bus` and `privateBus` modes are currently provided as Beta, with limited functionality.
Please refer to the Developer Guide for more details [here](https://www.here.com/docs/bundle/routing-api-developer-guide-v8/page/topics/transport-modes.html).
enum: ["car", "truck", "pedestrian", "bicycle", "taxi", "scooter", "bus", "privateBus"]
default: "car"
Avoid:
description: Avoid routes that violate these properties.
type: object
properties:
features:
$ref: "#/components/schemas/AvoidFeatures"
areas:
$ref: "#/components/schemas/Areas"
segments:
description: |
An array of segment identifiers that routes will avoid going through.
Each entry has the following structure:
`{segmentId}(#{direction})?`
The individual parts are:
* segmentId: The identifier of the referenced topology segment inside the catalog, example: `here:cm:segment:207551710`
* direction (optional): Either '*' for bidirectional (default), '+' for positive direction, or '-' for negative direction
Example of a parameter value excluding two segments:
`["here:cm:segment:207551710#+", "here:cm:segment:76771992#*"]`
**Notes**: Maximum amount of penalized segments in one request cannot be greater than 1000.
"Penalized segments" refers to segments that have a restriction on maximum baseSpeed with `maxSpeedOnSegment` or are avoided with `avoid[segments]`.
type: array
minItems: 1
items:
type: string
zoneIdentifiers:
description: |
An array of routing zone identifiers that routes will avoid going through.
**Note**: Zones specified by id in this manner are avoided even if their conditions don't apply to the current vehicle.
Time-dependent zones are avoided by id even outside of the validity period.
For example the identifier `here:cm:envzone:2` references the `Berlin Umweltzone` environmental zone
type: array
minItems: 1
items:
type: string
truckRoadTypes:
description: |
An array of truck road type identifiers that routes will avoid going through.
A truck road type identifier is associated with roads that have additional regulations applied by local administration for traversal by heavy vehicles like trucks.
For example, the BK Bearing Class regulations in Sweden, and ET categories in Mexico.
Identifiers for supported truck road types are specified at HERE Map Content
[TruckRoadType](https://developer.here.com/documentation/here-map-content/dev_guide/topics_schema/truckroadtypeattribute.truckroadtype.html).
type: array
minItems: 1
items:
type: string
tollTransponders:
description: |
Specifies that routes should avoid roads where the specified toll transponders are the only payment method.
The value of the parameter is a comma-separated list of transponder systems that the user has. Alternatively,
the user can also specify `all` as a list element to state they have all required transponders along any potential route.
**Note**: Currently, the only valid value is `all`.
type: array
items:
$ref: "#/components/schemas/TollTransponders"
example:
- "all"
zoneCategories:
$ref: "#/components/schemas/AvoidZoneCategories"
TollTransponders:
type: string
enum:
- all
Allow:
description: Explicitly allow features that require users to opt in.
type: object
properties:
hov:
description: |
This parameter specifies whether HOV lanes can be used in the calculation.
An HOV (High occupancy Vehicle) lane or carpool lane is reserved for carpool usage.
Carpool lane requires a minimum number of passengers in order for the car to use the
carpool lane.
**Note**:
- This parameter should be used with `vehicle[occupancy]`. If `vehicle[occupancy]` is set, then only HOV lanes allowing this number of occupants will be allowed. If `vehicle[occupancy]` is not set, occupancy requirements are always considered fulfilled.
type: boolean
default: false
hot:
description: |
This parameter specifies whether HOT lanes can be used in the calculation.
HOT (high-occupancy toll) lanes are HOV lanes where vehicles that do not qualify as high-occupancy are allowed to pass by paying a toll.
**Notes**:
- This parameter can be used with `allow[hov]`.
- No toll information is returned for HOT lanes since it is dynamic information.
type: boolean
default: false
MaxSpeedOnSegment:
type: array
items:
type: object
properties:
segment:
type: string
description: |
Identifier of the segment with restrictions on maximum `baseSpeed`.
Each entry has the following structure:
`{segmentId}(#{direction})?`
speed:
type: number
minimum: 1
maximum: 69.99
description: >
Maximum `baseSpeed` on segment in m/s.
description: |
Segments with restrictions on maximum `baseSpeed`.
**Notes**: Maximum amount of penalized segments in one request cannot be greater than 1000.
"Penalized segments" refers to segments that have a restriction on maximum baseSpeed with `maxSpeedOnSegment`
or are avoided with `avoid[segments]`
AvoidZoneCategories:
description: |
Specify avoidance of entire categories of routing zones, with the provision to add individual exceptions.
**Note**: Zones that don't apply to the current vehicle aren't avoided.
Time-dependent zones are avoided only during the validity period.
type: object
required:
- categories
properties:
categories:
description: |
An array of routing zone categories to avoid.
type: array
minItems: 1
items:
type: string
x-extensible-enum:
- congestionPricing
- environmental
- vignette
exceptZoneIds:
description: |
An array of zone identifiers, which will not be taken into account for evaluation of zone categories to avoid
type: array
minItems: 1
items:
type: string
AvoidFeatures:
description: |
`"avoid": {"features": [...]}`: Array of features avoided during matrix calculation.
Available avoid feature options:
* `seasonalClosure`
* `tollRoad`
* `controlledAccessHighway`
* `ferry`
* `carShuttleTrain`
* `tunnel`
* `dirtRoad`
* `difficultTurns`: This option avoids difficult turns, sharp turns and U-turns on multi-digitized roads, intersections and stopover-type waypoints. It is only supported for the `truck` transport mode.
**Disclaimer: This parameter is currently in beta release. Depending on your location and vehicle type, the outcome might not be according to the expectations. Please test the behavior of this feature for your use case before enabling it.**
* `uTurns`: This option avoids U-turns on multi-digitized roads, intersections and stopover-type waypoints. It is not supported for pedestrian, bicycle and scooter transport modes.
**Notes**
- Using `avoid[features]=tollRoad` is not recommended for large vehicles, e.g., trucks or buses.
- Using `avoid[features]=difficultTurns` together with `avoid[features]=controlledAccessHighway` or `avoid[features]=tollRoads` is not recommended.
type: array
uniqueItems: true
items:
type: string
enum: ["seasonalClosure", "tollRoad", "controlledAccessHighway", "ferry", "carShuttleTrain", "tunnel", "dirtRoad", "difficultTurns", "uTurns"]
Area:
description: |
Defines an explicit area to avoid/exclude when calculating the routes.
Areas to be avoided/excluded can be specified by boundingBoxes or polygons (as an encoded polyline or as a list of WGS-84 coordinates).
Notes:
* Minimum count of coordinates in any single polygon is 3. If less the corresponding error will be returned.
* Maximum count of coordinates in any single polygon is 16. If more the corresponding error will be returned.
* Self-intersecting polygons are not supported. If they are present in the request, the corresponding error will be returned.
oneOf:
- $ref: "#/components/schemas/BoundingBox"
- $ref: "#/components/schemas/Polygon"
- $ref: "#/components/schemas/EncodedPolygon"
discriminator:
propertyName: type
mapping:
boundingBox: "#/components/schemas/BoundingBox"
polygon: "#/components/schemas/Polygon"
encodedPolygon: "#/components/schemas/EncodedPolygon"
Areas:
description: |
List of explicit areas to avoid/exclude when calculating the routes.
Notes:
* Maximum count of avoided and excluded polygons is 20.
* Maximum total count of avoided and excluded bounding boxes and polygons is 250.
type: array
maxItems: 250
items:
$ref: "#/components/schemas/Area"
example:
- type: polygon
outer:
- lat: 35.821612
lng: 139.530864
- lat: 35.775531
lng: 139.502459
- lat: 35.775531
lng: 139.559269
- type: boundingBox
north: 35.808034
south: 35.776278
west: 139.491693
east: 139.532521
- type: encodedPolygon
outer: BG8mnlkD6-9wZAmrR19DAAlrR
Exclude:
type: object
description: |
Defines properties which will be strictly excluded from route calculation.
Note - Exclude options guarantees exclusion, but doesn't guarantee
finding a route.
properties:
countries:
description: |
A list of three-letter country codes (ISO-3166-1 alpha-3 code) that
routes will exclude.
type: array
items:
$ref: "#/components/schemas/CountryCode"
states:
description: |
A list of state codes specifying states that should be excluded
from routing. Each entry consists of a 3-letter country code
(ISO 3166-1 alpha-3) and a list of 1-3 character alphanumeric codes
representing subdivision region (ISO 3166-2).
For example, to exclude USA's New York, Pennsylvania states and
Canada's Quebeck state
[
{
"country": "CAN",
"codes": ["QC"]
},
{
"country": "USA",
"codes": ["NY", "PA"]
}
]
Note - Exclude states guarantees exclusion, but doesn't guarantee
finding a route.
type: array
items:
$ref: "#/components/schemas/StateCode"
areas:
$ref: "#/components/schemas/Areas"
CountryCode:
description: ISO-3166-1 alpha-3 code
type: string
example: FRA
StateCode:
description: |
Country code according ISO 3166-1 alpha-3 code and array of its state
codes according to ISO 3166-2.
type: object
example: { "country": "USA", "codes": ["NY", "PA"] }
RegionDefinition:
description: |
Definition of a region in which the matrix will be calculated.
Only the data **inside** of the region will be used for the calculation of the matrix. All
origins and destinations outside of the region are considered as invalid. The corresponding
values in the response matrix will be undefined.
If the region diameter is too large (cf. corresponding limits), the calculation will not be
done and an error will be returned by the service.
The special variant `world` is used to enable calculation of matrices with routes of
arbitrary length. Additionally, a profile can be selected from the list of supported
predefined profiles. For more information, refer to the documentation of the `profile`
request parameter.
oneOf:
- $ref: "#/components/schemas/Circle"
- $ref: "#/components/schemas/BoundingBox"
- $ref: "#/components/schemas/Polygon"
- $ref: "#/components/schemas/AutoCircle"
- $ref: "#/components/schemas/World"
discriminator:
propertyName: type
mapping:
circle: "#/components/schemas/Circle"
boundingBox: "#/components/schemas/BoundingBox"
polygon: "#/components/schemas/Polygon"
autoCircle: "#/components/schemas/AutoCircle"
world: "#/components/schemas/World"
example:
type: circle
center:
lat: 52.53787
lng: 13.40896
radius: 10000
Circle:
description: Region definition variant defining a circle around a coordinate on Earth.
required:
- type
- center
- radius
properties:
type:
type: string
enum: [circle]
center:
$ref: "#/components/schemas/Coordinate"
radius:
description: Radius in meters
type: integer
minimum: 0
maximum: 200000
BoundingBox:
type: object
description: A bounding box defined by two longitudes and two latitudes.
required:
- type
- north
- south
- west
- east
properties:
type:
type: string
enum: [boundingBox]
north:
description: Latitude in WGS-84 degrees of the northern boundary of the box
type: number
minimum: -90.0
maximum: 90.0
south:
description: Latitude in WGS-84 degrees of the southern boundary of the box
type: number
minimum: -90.0
maximum: 90.0
west:
description: Longitude in WGS-84 degrees of the western boundary of the box
type: number
minimum: -180.0
maximum: 180.0
east:
description: Longitude in WGS-84 degrees of the eastern boundary of the box
type: number
minimum: -180.0
maximum: 180.0
Polygon:
type: object
description: |
A polygon defined as a list of coordinates.
required:
- type
- outer
properties:
type:
type: string
enum: [polygon]
outer:
type: array
description: |
List of coordinates defining the outline of the polygon.
Notes:
* The polygon is automatically closed, so repeating the first vertex is not required.
* Self-intersecting polygons are not supported.
items:
$ref: "#/components/schemas/Coordinate"
minItems: 3
maxItems: 100
EncodedPolygon:
type: object
description: |
A [Flexible Polyline](https://github.com/heremaps/flexible-polyline) encoded string that defines the outline of the polygon.
required:
- type
- outer
properties:
type:
type: string
enum: [encodedPolygon]
outer:
type: string
description: |
A [Flexible Polyline](https://github.com/heremaps/flexible-polyline) encoded string that defines the outline of the polygon.
Notes:
* Support only 2D polyline (without `elevation` specified).
* Minimum count of vertices in polygon is 3.
* Maximum count of vertices in polygon is 100.
* The polygon is automatically closed, so repeating the first vertex is not required.
* Self-intersecting polygons are not supported.
AutoCircle:
type: object
description: |
Region definition variant defining an automatically derived circle.
The resulting circle contains all origins and destinations with a margin.
required:
- type
properties:
type:
type: string
enum: [autoCircle]
margin:
description: |
The minimal distance in meters between a given origin or destination and the perimeter
of the region.
type: integer
maximum: 200000
default: 10000
maxRadius:
description: |
Allows for limiting the radius (in meters) of the `autoCircle` to be used. The `autoCircle` will try to include most waypoints sent in the request.
Any waypoints that are outside of the generated `autoCircle` will not be used for travel time or distance calculations. Instead, the `errorCodes` field of the response will contain a value of 4 for the affected entries of the matrix.
The `maxRadius` does not include the margin specified, and `maxRadius` + `margin` must be less than or equal to 200000.
type: integer
maximum: 200000
World:
type: object
description: |
Unbounded region referring to the whole world.
The world region is only supported when a predefined profile is specified and no other
options are provided. For more information, refer to the documentation of the `profile`
request parameter.
required:
- type
properties:
type:
type: string
enum: [world]
Profile:
type: object
description: |
A profile specifies predefined request options that can be used for matrix routing in
the whole world.
properties:
profileId:
description: Unique machine- and human-readable profile ID
type:
string
departureTime:
$ref: "#/components/schemas/DepartureTimeWithAny"
routingMode:
$ref: "#/components/schemas/RoutingMode"
transportMode:
$ref: "#/components/schemas/TransportMode"
avoid:
$ref: "#/components/schemas/Avoid"
allow:
$ref: "#/components/schemas/Allow"
maxSpeedOnSegment:
$ref: "#/components/schemas/MaxSpeedOnSegment"
exclude:
$ref: "#/components/schemas/Exclude"
regionDefinition:
$ref: "#/components/schemas/RegionDefinition"
truck:
$ref: "#/components/schemas/Vehicle"
VehicleBase:
type: object
properties:
shippedHazardousGoods:
description: |
List of hazardous materials in the vehicle.
Hazardous goods restrictions refer to the limitations and regulations imposed on the transportation of specific types of hazardous materials during a trip.
The following values are possible:
* `explosive`: Materials that are capable of causing an explosion.
* `gas`: Gas (definition varies from country to country). For details, check [here](https://en.wikipedia.org/wiki/HAZMAT_Class_2_Gases).
* `flammable`: Materials that are easily ignited and capable of catching fire.
* `combustible`: Materials that have the potential to burn or catch fire.
* `organic`: Materials derived from living organisms or containing carbon compounds.
* `poison`: Substances that can cause harm or death when ingested, inhaled, or absorbed.
* `radioactive`: Materials that emit radiation and pose potential health risks.
* `corrosive`: Substances that can cause damage or destruction through chemical reactions.
* `poisonousInhalation`: Materials that are toxic when inhaled.
* `harmfulToWater`: Materials that can cause pollution or harm to water bodies.
* `other`: Other types of hazardous materials not covered by the above categories.
**Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
type: array
items:
type: string
enum:
- explosive
- gas
- flammable
- combustible
- organic
- poison
- radioactive
- corrosive
- poisonousInhalation
- harmfulToWater
- other
grossWeight:
description: |
Gross vehicle weight, including trailers and shipped goods when loaded at capacity, specified in kilograms.
If unspecified, it will default to currentWeight. If neither parameter has a value specified, it will default to 0.
**Notes:**
* Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
* Maximum weight for a car or taxi _without_ a trailer is 4250 kg.
* Maximum weight for a car or taxi _with_ a trailer is 7550 kg.
type: integer
format: int32
minimum: 0
currentWeight:
description: |
Current vehicle weight, including trailers and shipped goods currently loaded, specified in kilograms.
If unspecified, it will default to grossWeight. If neither parameter has a value specified, it will default to 0.
**Note:**
* Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
* Maximum weight for a car or taxi _without_ a trailer is 5000 kg.
* Maximum weight for a car or taxi _with_ a trailer is 8500 kg.
* A route request with `currentWeight` above `grossWeight` may result in non-compliant or invalid routes.
type: integer
format: int32
minimum: 0
weightPerAxle:
description: |
Heaviest vehicle weight-per-axle, specified in kilograms.
Heaviest weight-per-axle, regardless of axle-type or axle-group. It is evaluated against
all axle-weight restrictions, including single-axle and tandem-axle weight restrictions.
It is useful if differences between axle types, like tandem and triple axles, are not
relevant. This is the case in many countries, since they don't distinguish between these
different axle groups on signs and in regulations.
More fine-grained axle weight input is possible with `weightPerAxleGroup`.
**Note:** `weightPerAxleGroup` and `weightPerAxle` are incompatible.
**Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
type: integer
format: int32
minimum: 0
weightPerAxleGroup:
$ref: '#/components/schemas/WeightPerAxleGroup'
height:
description: |
Vehicle height, specified in centimeters.
**Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
type: integer
format: int32
minimum: 0
maximum: 5000
width:
description: |
Vehicle width, specified in centimeters.
**Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
type: integer
format: int32
minimum: 0
maximum: 5000
length:
description: |
Vehicle length, specified in centimeters.
**Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
type: integer
format: int32
minimum: 0
maximum: 30000
kpraLength:
description: |
Kingpin to rear axle length, in centimeters.
**NOTE:** Currently, the KPRA restrictions are only present in California and Idaho.
**Note:** Supported in truck, car (Beta), taxi (Beta) transport modes.
type: integer
format: int32
minimum: 0
payloadCapacity:
description: |
Allowed payload capacity, including trailers, specified in kilograms.
**Note:** Supported in truck, car (Beta), taxi (Beta) transport modes.
type: integer
format: int32
minimum: 0
tunnelCategory:
description: |
Specifies the [cargo tunnel restriction code](https://adrbook.com/en/2017/ADR/8.6.3). Route will pass only through tunnels of less restrictive categories.
**Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
type: string
enum: ["B", "C", "D", "E"]
weightLimit:
description: Renamed to `grossWeight`.
type: integer
format: int32
minimum: 0
deprecated: true
axleCount:
description: |
Specifies the total number of axles the vehicle has, i.e., axles on the base vehicle and any attached trailers.
**Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes.
type: integer
format: int32
minimum: 2
maximum: 255
category:
description: |
Specifies the category of the vehicle. The supported values are:
* `undefined`: The vehicle category is undefined, and no special considerations are taken into
account. Vehicle routing will proceed as normal.
* `lightTruck`: The vehicle is a truck light enough to be classified more as a car than as a truck.
This exempts it from many legal restrictions for normal trucks. However, restrictions related to the physical dimensions of the truck or its cargo still apply.
For more details, refer to [Truck Categories](https://developer.here.com/documentation/routing-api/dev_guide/topics/truck-routing/truck-routing.html).
**Note:** Supported only in truck transport mode.
type: string
enum:
- undefined
- lightTruck
default: undefined
trailerCount:
description: |
The number of trailers attached to the vehicle.
Maximum value when used with `transportMode=car` or `transportMode=taxi` is 1.
**Limitations:** Considered for route calculation when `transportMode` is one of (`truck`, `bus`, `privateBus`). Considered for route calculation for restrictions, but not for speed limits, when `transportMode` is `car` or `taxi`.
type: integer
format: int32
minimum: 0
maximum: 255
default: 0
licensePlate:
$ref: '#/components/schemas/LicensePlate'
speedCap:
description: |
Specifies the maximum speed, in meters per second (m/s), that the user wishes not to exceed.
This parameter affects the route's estimated time of arrival (ETA) and consumption calculation.
Limitations:
* valid for following transport modes: `car`, `truck`, `scooter`, `taxi`, `bus`, and `privateBus`
Notes:
* Car and Truck mode updates route ETA.
* Scooter mode updates route optimization and ETA.
type: number
minimum: 1.00
maximum: 70.00
engineSizeCc:
description: |
Specifies the engine size of the vehicle in cubic centimeters.
Currently, the value is used only in scooter mode.
This parameter is utilized to determine if the scooter can be classified as a moped.
Scooters with an engine size less than 51cc are considered mopeds.
**Alpha**: This API is in development. It may not be stable and is subject to change. It may have no impact on response.
type: integer
minimum: 0
maximum: 2000
occupancy:
description: |
The number of occupants on the vehicle, defined as individuals occupying a seat.
This value affects the ability of the router to use HOV (High-Occupancy Vehicles) restricted lanes. If not set and `allow[hov]=true` is set, then occupancy requirements for all HOV conditions are considered to be met.
type: integer
minimum: 1
LicensePlate:
description: |
Specifies the information about the vehicle's license plate number.
This information is used to evaluate whether certain vehicle restrictions in environmental zones apply.
Currently, only the last character of the license plate can be provided.
type: object
properties:
lastCharacter:
description: Specifies the last character of the license plate.
type: string
pattern: '^.$'
example:
lastCharacter: 7
Vehicle:
allOf:
- $ref: "#/components/schemas/VehicleBase"
- properties:
type:
$ref: '#/components/schemas/VehicleType'
Truck:
allOf:
- $ref: "#/components/schemas/VehicleBase"
- deprecated: true
properties:
type:
$ref: '#/components/schemas/TruckType'
VehicleType:
description: |
Specifies the type of the vehicle
* `straightTruck`: A truck on a single frame with a permanently attached cargo area. **Note:**
default value when truck routing mode is used.
* `tractor`: A towing vehicle that can pull one or more semi-trailers (also known as a semi-truck).
**Limitations:** only valid for `transportMode=truck`.
type: string
enum:
- straightTruck
- tractor
TruckType:
description: |
Specifies the type of truck.
* `straight`: a truck on a single frame with a permanently attached cargo area
* `tractor`: a towing vehicle that can pull one or more semi-trailers (aka semi-truck)
deprecated: true
type: string
enum:
- straight
- tractor
default: straight
WeightPerAxleGroup:
description: |
Specifies the weights of different axle groups, like single and tandem axles.
This allows specification of axle weights in a more fine-grained way than `weightPerAxle`. This
is relevant in countries with signs and regulations that specify different limits for different
axle groups, like the USA and Sweden.
Weights are specified in kilograms (kg) and are the total weight of the axle group.
**Note:** `weightPerAxleGroup` and `weightPerAxle` are incompatible.
type: object
properties:
single:
description: single axle group
type: integer
format: int32
minimum: 0
tandem:
description: tandem axle group
type: integer
format: int32
minimum: 0
triple:
description: triple axle group
type: integer
format: int32
minimum: 0
quad:
description: quad axle group
type: integer
format: int32
minimum: 0
quint:
description: quint axle group
type: integer
format: int32
minimum: 0
example:
single: 11000
tandem: 18000
Scooter:
type: object
properties:
allowHighway:
description: |
Specifies whether matrix calculation should take highways into account. When this
parameter isn't provided, then by default highways would be avoided. If the avoid
feature `controlledAccessHighway` is provided, then highways would be avoided,
even if `allowHighway` is set to `true`.
type: boolean
default: false
Pedestrian:
type: object
properties:
speed:
description: |
Specifies the walking speed in meters per second (m/s). Influences the duration of
walking segments along the route.
type: number
minimum: 0.5
maximum: 2
default: 1
Taxi:
type: object
properties:
allowDriveThroughTaxiRoads:
description: |
Specifies if a vehicle is allowed to drive through the taxi-only roads and lanes. It's
still allowed on taxi roads after the route start and before the destination even if not
allowed to drive through the taxi-only roads.
type: boolean
default: true
Traffic:
type: object
description: Traffic specific parameters.
properties:
overrideFlowDuration:
description: |
Duration in seconds for which flow traffic event would be considered valid. While flow
traffic event is valid it will be used over the historical traffic data.
**Note**: Flow traffic represents congestion not caused by any long-term incidents.
State of the flow traffic often changes fast. The farther away from the current time we
move, the less precise current flow traffic data will be and the more precise historical
traffic data becomes. That's why it's advised not to use this parameter unless you know
what you want to achieve and use the default behavior which is almost always better.
type: integer
mode:
description: |
Defines what traffic data should be used for route shape and travel duration calculation.
* `default`: Traffic data is considered.
* - If `departureTime=any` then only long-term closures will be considered.
* - If `departureTime` is not equal to `any` then all traffic data will be taken into account.
* `disabled`: All traffic data, including long term closures, is ignored.
type: string
default: "default"
enum:
- default
- disabled
ViolationMappingItem:
description: |
Generic base type for violation mappings. Violation mappings belong to either of two categories.
Mappings belonging to the same category are evaluated together and if they apply, it is reflected
in the errorCodes of the resulting matrix.
Two types of mappings are supported: violated restrictions or traffic blockages. These cannot
be combined into a single violation mapping item; each item must belong to one specific type.
oneOf:
- $ref: '#/components/schemas/ViolationMappingItemRestriction'
- $ref: '#/components/schemas/ViolationMappingItemTraffic'
discriminator:
propertyName: type
mapping:
restriction: '#/components/schemas/ViolationMappingItemRestriction'
traffic: '#/components/schemas/ViolationMappingItemTraffic'
ViolationMappingCommonItems:
type: object
properties:
category:
type: integer
minimum: 1
maximum: 2
description: |
The category number assigned to this violation mapping item. Two categories are supported, with values 1 and 2
available to categorize the mapping items.
bridge:
description: |
Specifies whether the violation is considered only if it occurs on a
bridge, only if it does not occur on a bridge, or in both cases.
allOf:
- $ref: "#/components/schemas/ViolationMappingOptionalField"
default: "ignore"
ViolationMappingItemTraffic:
description: |
Allows the mapping of traffic related blockages.
Mapping of traffic blockages is supported for transport modes `car` and `truck`.
required:
- type
type: object
properties:
type:
type: string
enum: [traffic]
allOf:
- $ref: '#/components/schemas/ViolationMappingCommonItems'
ViolationMappingItemRestriction:
description: |
Allows the mapping of violations of selected restrictions.
Mapping of violated restrictions is supported for transport mode `truck`.
required:
- type
type: object
properties:
type:
type: string
enum: [restriction]
grossWeight:
description: |
Indicates whether gross weight violation is included or excluded
for this category.
**NOTE:** A weight restriction can be of type `unknown`, meaning it
may apply to either gross or current weight. If both the vehicle’s
current_weight and gross_weight violate an `unknown` weight restriction,
and the user requests a violation mapping for only one of them
(e.g., using gross_weight:include or current_weight:include), the
service will assign the `unknown` weight restriction to the included
weight type.
Similarly, if either the vehicle’s current_weight or gross_weight
violates an `unknown` weight restriction, the service will assign
the `unknown` weight restriction to the specific weight type that
exceeds the allowed limit.For example:
* gross_weight=15000, current_weight=10000
* weight_restriction_type=Unknown with value 12000
* Since gross_weight (15,000) exceeds the restriction (12,000),
the `unknown` weight restriction will be mapped to gross_weight
rather than current_weight.
User in this case will get an error code 3.
* Please note that a restriction of type `unknown` may change To
`gross` or `current` when data becomes available in future. Similarly
a restriction of type `gross` or `current` may also change to a
different type if actual regulation changes.
allOf:
- $ref: "#/components/schemas/ViolationMappingOptionalField"
default: "exclude"
currentWeight:
description: |
Indicates whether current weight violation is included or excluded
for this category.
**NOTE:** A weight restriction can be of type `unknown`, meaning it
may apply to either gross or current weight. If both the vehicle’s
current_weight and gross_weight violate an `unknown` weight restriction,
and the user requests a violation mapping for only one of them
(e.g., using gross_weight:include or current_weight:include), the
service will assign the `unknown` weight restriction to the included
weight type.
Similarly, if either the vehicle’s current_weight or gross_weight
violates an `unknown` weight restriction, the service will assign
the `unknown` weight restriction to the specific weight type that
exceeds the allowed limit.For example:
* gross_weight=15000, current_weight=10000
* weight_restriction_type=Unknown with value 12000
* Since gross_weight (15,000) exceeds the restriction (12,000),
the `unknown` weight restriction will be mapped to gross_weight
rather than current_weight.
User in this case will get an error code 3.
* Please note that a restriction of type `unknown` may change To
`gross` or `current` when data becomes available in future. Similarly
a restriction of type `gross` or `current` may also change to a
different type if actual regulation changes.
allOf:
- $ref: "#/components/schemas/ViolationMappingOptionalField"
default: "exclude"
height:
description: |
Indicates whether height violation is included or excluded from this
category.
allOf:
- $ref: "#/components/schemas/ViolationMappingOptionalField"
default: "exclude"
timeDependent:
description: |
Specifies whether the time dependent violation of restrictions is included,
excluded or ignored for this category.
allOf:
- $ref: "#/components/schemas/ViolationMappingOptionalField"
default: "ignore"
allOf:
- $ref: '#/components/schemas/ViolationMappingCommonItems'
ViolationMappingOptionalField:
type: string
enum:
- include
- exclude
- ignore
description: |
MatrixResponse:
type: object
required:
- matrixId
properties:
matrixId:
description: Unique identifier assigned to the matrix by the service
type: string
matrix:
$ref: "#/components/schemas/Matrix"
error:
$ref: "#/components/schemas/ErrorMessage"
regionDefinition:
$ref: "#/components/schemas/RegionDefinition"
Matrix:
type: object
description: Calculated matrix
required:
- numOrigins
- numDestinations
properties:
numOrigins:
type: integer
description: Number of origins (rows) in this matrix
minimum: 0
numDestinations:
type: integer
description: Number of destinations (columns) in this matrix
minimum: 0
travelTimes:
description: Corresponds to 2D matrix of travelTimes (in seconds).
type: array
items:
type: integer
format: int32
distances:
description: |
Corresponds to 2D matrix of distances (in meters). Only returned if `distance` is
specified in the `matrixAttributes` request parameter.
type: array
items:
type: integer
format: int32
errorCodes:
type: array
items:
type: integer
format: int32
description: |
Contains error codes for matrix entries when there is at least one
unsuccessful calculation or when a violation mapping is applied to a calculation.
If a violation mapping is requested, values in the range [5 .. 10] are returned. These error codes indicate
that a violation or blockage occurred which would have otherwise resulted in error code 3, but it was ignored,
and and the result was instead mapped to a different error code.
| Value | Reason |
|-------|------------------------------------------------------------------------------------------------|
| 0 | Calculation successful |
| 1 | Graph disconnected (there is no route between `i` and `j`) |
| 2 | Matching failed (could not match `i` or `j` to a location where routing could start resp. end) |
| 3 | Route was calculated but has some violation(s) (no feasible route without violations between `i` and `j` was found). Potential violations include: - road is used that violates a user option, e.g. an `avoid` option
- road is used that violates a legal/physical restriction, e.g., a no-through zone
- road is used that is blocked by a traffic event
|
| 4 | Waypoints that are matched to or are inside the `margin`, or are completely outside the region limits (could not match `i` or `j` to a location where routing could start resp. end). |
| 5 | At least one violation defined in violation mapping category 1 was found. |
| 6 | At least one violation defined in violation mapping category 2 was found. |
| 7 | At least one unmapped violation (as described in value 3) and at least one violation of category 1 were found. |
| 8 | At least one unmapped violation (as described in value 3) and at least one violation of category 2 were found. |
| 9 | At least one violation of each category 1 and 2 was found. |
| 10 | At least one unmapped violation (as described in value 3) and one or more violations of each category 1 and 2 were found. |
| 99 | Unknown error |
MatrixStatus:
type: object
required:
- matrixId
- status
properties:
matrixId:
description: Unique identifier assigned to the matrix by the service
type: string
status:
description: Specifies the status of the matrix calculation.
type: string
enum: ["accepted", "inProgress", "completed", "timeout", "error"]
statusUrl:
description: If the `status` is `accepted`, contains the url to the matrix status.
type: string
format: uri
resultUrl:
description: If the `status` is `completed`, contains the url to the matrix result.
type: string
format: uri
error:
$ref: "#/components/schemas/ErrorMessage"
AuthError:
description: Error object reported in case of authentication or authorization errors.
type: object
properties:
error:
type: string
description: Error message
error_description:
type: string
description: Detailed information about the error
example:
error: Unauthorized
error_description: ApiKey invalid. ApiKey not found.
ErrorMessage:
type: object
required:
- title
- status
- code
- cause
- action
- correlationId
properties:
title:
description: Title of the error
type: string
status:
description: HTTP status code (coincides with HTTP response status code)
type: integer
code:
description: |
Machine readable service error code.
The prefix `E601` is fixed and is unique for this service. The last three digits
describe a specific error. Provide this error code when contacting support.
| Code | Reason |
| --------- | ---------------------------------------------------------- |
| `E601101` | Invalid json |
| `E601102` | Invalid content-type header |
| `E601103` | Invalid accept-encoding header |
| `E601104` | Invalid request size |
| `E601105` | Invalid or missing accept-encoding |
| `E601106` | Invalid matrix id |
| `E601107` | Method not allowed |
| `E601108` | Unknown matrix id |
| `E601109` | Missing obligatory path parameter `profileId` |
| `E601110` | Insufficient permissions |
| `E601111` | Rate limit exceeded |
| `E601112` | Invalid URL query parameters |
| `E601113` | Invalid POST query parameters |
| `E601201` | Unsupported routing mode |
| `E601202` | Invalid region size |
| `E601203` | Region self intersecting |
| `E601204` | Invalid vertex count of region polygon |
| `E601210` | Invalid truck height option |
| `E601211` | Invalid truck width option |
| `E601212` | Invalid truck length option |
| `E601213` | Empty origins |
| `E601214` | Empty destinations |
| `E601215` | Size of matrix exceeds limit |
| `E601217` | Region definition has to be `world` when a profile is used |
| `E601218` | Unknown profile ID |
| `E601219` | Departure time has to be `any` when a profile is used |
| `E601220` | Option conflicts with the used profile option |
| `E601221` | Invalid coordinate specified in request |
| `E601223` | `weightPerAxle` and `weightPerAxleGroup` are incompatible |
| `E601224` | Invalid SegmentId syntax |
| `E601225` | Too many segments in avoid[segments] |
| `E601226` | Invalid country code in exclude[countries] |
| `E601227` | Invalid Routing Zone Id syntax |
| `E601228` | Invalid Routing Zone Category |
| `E601229` | Invalid combination of avoid feature `difficultTurns` or `uTurns` and transport mode. |
| `E601230` | `truck[*]` and `vehicle[*]` are incompatible |
| `E601231` | Invalid `vehicle[type]` for transport mode |
| `E601232` | Too many items in avoid[areas] |
| `E601233` | Invalid speed for segment |
| `E601234` | Invalid `"vehicle":{"speedCap"=*}` value, must be in range 1.00-70.00 m/s |
| `E601235` | Invalid `"vehicle":{"speedCap"=*}` transport mode combination |
| `E601236` | `radius` and `snapRadius` are incompatible |
| `E601237` | Too many items in avoid[areas][polygon] |
| `E601238` | Too many vertices in avoid[areas][polygon] |
| `E601239` | Not enough vertices in avoid[areas][polygon] |
| `E601240` | Avoided polygon self intersecting |
| `E601241` | Invalid `"vehicle":{"kpraLength"=*}` transport mode combination |
| `E601242` | Invalid `"vehicle":{"payloadCapacity"=*}` transport mode combination |
| `E601243` | Invalid state code in exclude[states]
| `E601244` | Invalid `"violationMappings":{{"category"=*}}` transport mode combination |
| `E601245` | Number of violationMappings must be <= 10 |
| `E601246` | `radius * radiusPenalty / 100` must not exceed 7200 |
| `E601247` | `radiusPenalty` and `snapRadius` are incompatible |
| `E601248` | Invalid combination of vehicle options and transport mode |
| `E601249` | `vehicle[currentWeight]` or `vehicle[grossWeight]` exceeds limit for given `transportMode` |
| `E601250` | Invalid country code in exclude[states]
| `E601501` | Request timeout |
| `E601504` | Too many waypoints matched to a single segment |
| `E6016xx` | Internal error |
type: string
cause:
description: Human readable description of the error and/or its cause.
type: string
action:
description: Actionable instruction on how to fix this error
type: string
correlationId:
description: |
Unique ID of the request which triggered this error.
Please provide this ID in communication with support.
type: string
Version:
type: object
required:
- apiVersion
properties:
apiVersion:
type: string
description: API version in format `major.minor.patch`
example: "8.0.0"
# common data types
Coordinate:
type: object
required: ["lat", "lng"]
properties:
lat:
type: number
format: double
description: Latitude in WGS-84 degrees.
lng:
type: number
format: double
description: Longitude in WGS-84 degrees.
example:
lat: 52.53787
lng: 13.40896