openapi: 3.2.0 info: title: Matrix Routing API v8 Matrix Calculation API version: 8.49.0 description: HERE Matrix Routing service calculates the travel duration, distances, and consumptions 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 servers: - url: https://matrix.router.hereapi.com/v8 security: - Bearer: [] - ApiKey: [] 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.' 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. For other supported attributes, the corresponding flags must be specified 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 lng: 13.3849 - lat: 52.5202 lng: 13.373 destinations: - lat: 52.522 lng: 13.4133 - lat: 52.5163 lng: 13.3777 regionDefinition: type: world matrixAttributes: - travelTimes - distances Flexible mode (truck with poisonous goods): value: origins: - lat: 52.5309 lng: 13.3849 - lat: 52.5202 lng: 13.373 destinations: - lat: 52.522 lng: 13.4133 - lat: 52.5163 lng: 13.3777 regionDefinition: type: world transportMode: truck truck: shippedHazardousGoods: - poison Region mode (circle with traffic departure time): value: origins: - lat: 52.5309 lng: 13.3849 - lat: 52.5202 lng: 13.373 destinations: - lat: 52.522 lng: 13.4133 - lat: 52.5163 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 lng: 13.3849 - lat: 52.5202 lng: 13.373 destinations: - lat: 52.522 lng: 13.4133 - lat: 52.5163 lng: 13.3777 regionDefinition: type: autoCircle margin: 25000 Profile mode (car fastest): value: origins: - lat: 52.5309 lng: 13.3849 - lat: 54.0924 lng: 12.0991 destinations: - lat: 51.3397 lng: 12.3731 - lat: 51.0504 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: Unauthorized error_description: apiKey invalid. apiKey not found. '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: Unauthorized error_description: apiKey invalid. apiKey not found. '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' components: schemas: RoutingMode: description: "Specifies which optimization is applied during the calculation.\n\n* `fast`: Route calculation from start to destination optimized by travel time. In many\n cases, the route returned by `fast` mode may not be the route with the fastest\n possible travel time. For example, the routing service may favor a route that remains on\n a highway, even if a faster travel time can be achieved by taking a detour or shortcut\n through an inconvenient side road.\n* `short`: Route calculation from start to destination disregarding any speed information.\n In this mode, the distance of the route is minimized, while keeping the route sensible.\n This includes, for example, penalizing turns. Because of that, the resulting route will\n not necessarily be the one with minimal distance.\n\nNotes:\n* The following Transport modes only support `fast` routingMode\n - `bicycle`\n - `bus`\n - `pedestrian`\n - `privateBus`\n - `scooter`\n - `taxi`\n" type: string enum: - fast - short default: fast Circle: type: object 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 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 or POST body validation failed | | `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 | | `E601222` | Invalid axle count | | `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"=*}` or `"vehicle":{"speedCapPerFc"=[{"speed"=*}]}` 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] | | `E601251` | Invalid pedestrian mode combination | | `E601252` | Invalid pedestrian parameter | | `E601253` | Invalid truck tires count option | | `E601260` | Invalid EV request | | `E601261` | Parameter out of range | | `E601262` | Invalid experimental ETA customization | | `E601299` | Experimental feature not enabled | | `E601501` | Request timeout | | `E601504` | Too many waypoints matched to a single segment | | `E601505` | Too complex request | | `E601506` | Invalid `"vehicle":{"speedCapPerFc"=*}` transport mode combination | | `E601507` | Invalid `"vehicle":{"speedCapPerFc"=[{"fc"=*}]}` fc value, must be in range 1-5 | | `E601508` | `arrivalTime` only supports matrix with single destination | | `E601509` | Invalid combination of `departureTime` and `arrivalTime` | | `E601510` | `arrivalTime` only supports matrix calculation in flexible mode | | `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 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]` ' MatrixResponse: type: object required: - matrixId properties: matrixId: description: Unique identifier assigned to the matrix by the service type: string matrix: $ref: '#/components/schemas/Matrix' regionDefinition: $ref: '#/components/schemas/RegionDefinition' 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`, or `arrivalTime` is provided, 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 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. 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: "Items extensible enum: `congestionPricing` `environmental` `vignette` `...` \nAn array of routing zone categories to avoid.\n" 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 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: type: integer 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: type: integer 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.379649 course: 143 EV: type: object description: "EV properties to be used only when requesting `consumptions` in `matrixAttributes`.\n\n**Note:** Access to the `consumptions` feature is currently restricted.\nIf you would like to use it, please reach out to your Account Manager or \n[contact us ](https://www.here.com/contact) to get access.\n\nThere are two consumption models (`empirical`, `physical`). Set the `consumptionModel` parameter to choose which model to use.\n\nRequired `empirical` model properties:\n* `freeFlowSpeedTable`\n\nRequired `physical` model properties:\n* `driveEfficiency`\n* `recuperationEfficiency`\n\nWhen using the physical model, certain properties of the `vehicle` parameter are also required (see documentation for the `vehicle` parameter for more details):\n* `rollingResistanceCoefficient`\n* `airDragCoefficient`\n* `currentWeight`\n* `frontalArea` or combination of `width` and `height`\n" oneOf: - $ref: '#/components/schemas/EVEmpiricalModel' - $ref: '#/components/schemas/EVPhysicalModel' discriminator: propertyName: consumptionModel mapping: empirical: '#/components/schemas/EVEmpiricalModel' physical: '#/components/schemas/EVPhysicalModel' AvoidFeatures: description: "`\"avoid\": {\"features\": [...]}`: Array of features avoided during matrix calculation.\n Available avoid feature options:\n * `seasonalClosure`\n * `tollRoad`\n * `controlledAccessHighway`\n * `ferry`\n * `carShuttleTrain`\n * `tunnel`\n * `dirtRoad`\n * `difficultTurns`: **Deprecated** (see Notes for details). 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.\n * `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.\n\n **Notes**\n - Using `avoid[features]=tollRoad` is not recommended for large vehicles, e.g., trucks or buses.\n - `avoid[features]=difficultTurns` is currently deprecated and will be ignored in the future. Using `avoid[features]=difficultTurns` together with `avoid[features]=controlledAccessHighway` or `avoid[features]=tollRoads` is not recommended, as it may lead to routes which could include difficult turns.\n" type: array uniqueItems: true items: type: string enum: - seasonalClosure - tollRoad - controlledAccessHighway - ferry - carShuttleTrain - tunnel - dirtRoad - difficultTurns - uTurns 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' 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 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 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.\n\nEach entry has the following structure:\n`{segmentId}(#{direction})?`\n\nThe individual parts are:\n* segmentId: The identifier of the referenced topology segment inside the catalog, example: `here:cm:segment:207551710`\n* direction (optional): Either '*' for bidirectional (default), '+' for positive direction, or '-' for negative direction\n\nExample of a parameter value excluding two segments:\n`[\"here:cm:segment:207551710#+\", \"here:cm:segment:76771992#*\"]`\n\n**Notes**: Maximum amount of penalized segments in one request cannot be greater than 1000.\n \"Penalized segments\" refers to segments that have a restriction on maximum baseSpeed with `maxSpeedOnSegment` or are avoided with `avoid[segments]`.\n" type: array minItems: 1 items: type: string zoneIdentifiers: description: "An array of routing zone identifiers that routes will avoid going through.\n\n**Note**: Zones specified by id in this manner are avoided even if their conditions don't apply to the current vehicle.\nTime-dependent zones are avoided by id even outside of the validity period. \n\nFor example the identifier `here:cm:envzone:2` references the `Berlin Umweltzone` environmental zone\n" 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://docs.here.com/map-content/docs/truckroadtypeattribute-truckroadtype). ' 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' 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 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 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 ConsumptionSpeedTableEntry: description: '' type: object properties: speed: description: 'Speed in km/h. **Note:** We do not use SI units (m/s) to specify speed in this particular case. ' type: integer minimum: 0 maximum: 255 consumption: description: 'Consumption rate at the given speed. For EV, the consumption is in Watt-hours per meter (Wh/m). ' type: number minimum: 0 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 ConsumptionSpeedTable: description: 'Function curve specifying consumption rate at a given speed, where speed values are strictly increasing. The table is an array specifying data points along the function. The function is linearly interpolated between the data points. For speeds less than the first entry, the first consumption value is used, and for speeds greater than the last entry, the last consumption value is used. ' type: array items: $ref: '#/components/schemas/ConsumptionSpeedTableEntry' minItems: 2 example: - speed: 0 consumption: 0.2394 - speed: 14 consumption: 0.2394 - speed: 36 consumption: 0.2586 - speed: 52 consumption: 0.196 - speed: 68 consumption: 0.2074 - speed: 83 consumption: 0.238 - speed: 95 consumption: 0.2597 - speed: 105 consumption: 0.2597 - speed: 115 consumption: 0.2964 - speed: 125 consumption: 0.3367 - speed: 135 consumption: 0.3508 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' 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.\n\nAn HOV (High occupancy Vehicle) lane or carpool lane is reserved for carpool usage.\nCarpool lane requires a minimum number of passengers in order for the car to use the\ncarpool lane.\n\n**Note**:\n - 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.\n" type: boolean default: false hot: description: "This parameter specifies whether HOT lanes can be used in the calculation.\n\nHOT (high-occupancy toll) lanes are HOV lanes where vehicles that do not qualify as high-occupancy are allowed to pass by paying a toll.\n\n**Notes**:\n - This parameter can be used with `allow[hov]`.\n - No toll information is returned for HOT lanes since it is dynamic information.\n" type: boolean default: false 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 `distances` is specified in the `matrixAttributes` request parameter. ' type: array items: type: integer format: int32 consumptions: description: 'Corresponds to 2D matrix of the estimated net energy consumed based on consumption model specified by the `ev` parameter. Only returned if `consumptions` is specified in the `matrixAttributes` parameter. See `consumptionScale` for unit information. ' type: array items: type: integer format: int32 consumptionScale: description: 'Values in `consumptions` are pre-multiplied by this scale in order to return integer results. Divide the values in `consumptions` by this scale to get consumption in kWh. Only returned if `consumptions` is specified in the `matrixAttributes` parameter. ' type: integer errorCodes: type: array items: type: integer format: int32 description: "Contains error codes for matrix entries when there is at least one\nunsuccessful calculation or when a violation mapping is applied to a calculation.\n\nIf a violation mapping is requested, values in the range [5 .. 10] are returned. These error codes indicate\nthat a violation or blockage occurred which would have otherwise resulted in error code 3, but it was ignored, \nand and the result was instead mapped to a different error code.\n\n| Value | Reason |\n|-------|------------------------------------------------------------------------------------------------|\n| 0 | Calculation successful |\n| 1 | Graph disconnected (there is no route between `i` and `j`) |\n| 2 | Matching failed (could not match `i` or `j` to a location where routing could start resp. end) |\n| 3 | Route was calculated but has some violation(s) (no feasible route without violations between `i` and `j` was found). Potential violations include:
  1. road is used that violates a user option, e.g. an `avoid` option
  2. road is used that violates a legal/physical restriction, e.g., a no-through zone
  3. road is used that is blocked by a traffic event
|\n| 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). |\n| 5 | At least one violation defined in violation mapping category 1 was found. |\n| 6 | At least one violation defined in violation mapping category 2 was found. |\n| 7 | At least one unmapped violation (as described in value 3) and at least one violation of category 1 were found. |\n| 8 | At least one unmapped violation (as described in value 3) and at least one violation of category 2 were found. |\n| 9 | At least one violation of each category 1 and 2 was found. |\n| 10 | At least one unmapped violation (as described in value 3) and one or more violations of each category 1 and 2 were found. |\n| 99 | Unknown error |\n" 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 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' 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 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.\n\nNotes:\n * Support only 2D polyline (without `elevation` specified).\n * Minimum count of vertices in polygon is 3.\n * Maximum count of vertices in polygon is 100.\n * The polygon is automatically closed, so repeating the first vertex is not required.\n * Self-intersecting polygons are not supported.\n" EVEmpiricalModel: description: Specifies parameters required for calculation of energy consumption for electric vehicles using Empirical model. type: object properties: consumptionModel: type: string enum: - empirical freeFlowSpeedTable: $ref: '#/components/schemas/ConsumptionSpeedTable' trafficSpeedTable: description: 'Function curve specifying consumption rate at a given traffic-reduced speed on a flat stretch of road. See `freeFlowSpeedTable` for a description of the format. ' allOf: - $ref: '#/components/schemas/ConsumptionSpeedTable' ascent: description: 'Rate of energy consumed per meter rise in elevation in Wh/m. ' type: number minimum: 0 descent: description: 'Rate of energy recovered per meter fall in elevation in Wh/m. ' type: number minimum: 0 auxiliaryConsumption: description: 'Rate of energy (in Wh/s) consumed by the vehicle''s auxiliary systems (for example, air conditioning, lights). The value represents the number of Watt-hours consumed per second of travel. ' type: number minimum: 0 required: - consumptionModel - freeFlowSpeedTable ViolationMappingItemAvoidAreasAndSegments: required: - category - type 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 \navailable to categorize the mapping items.\n" type: type: string enum: - avoidAreasAndSegments description: "Allows the mapping of user specified avoidance of areas or individual segments. \nThis type of mapping is supported for transport modes `car` and `truck`.\n" Distance: type: integer minimum: 0 description: Distance in meters 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 ViolationMappingOptionalField: type: string enum: - include - exclude - ignore description: "Defines how a specific violation attribute should be handled within a \nviolation mapping. Use:\n `include`: the violated restriction is added to a mapped\n category instead of causing a hard error code 3.\n\n `exclude`: the violated restriction is not added to a mapped\n category and still causes an error code 3. This is the default for\n height and grossWeight.\n\n `ignore`: the algorithm is not taking the restriction or\n property / attribute of the road into consideration.\n This is the default attribute for restrictions on bridge or time-dependent\n" 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 maximum: 90 south: description: Latitude in WGS-84 degrees of the southern boundary of the box type: number minimum: -90 maximum: 90 west: description: Longitude in WGS-84 degrees of the western boundary of the box type: number minimum: -180 maximum: 180 east: description: Longitude in WGS-84 degrees of the eastern boundary of the box type: number minimum: -180 maximum: 180 ViolationMappingItemTraffic: required: - category - type 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 \navailable to categorize the mapping items.\n" 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 type: type: string enum: - traffic description: "Allows the mapping of traffic related blockages. \nMapping of traffic blockages is supported for transport modes `car` and `truck`.\n" ViolationMappingItem: description: "Generic base type for violation mappings. Violation mappings belong to either of two categories. \nMappings belonging to the same category are evaluated together and if they apply, it is reflected \nin the errorCodes of the resulting matrix.\nTwo types of mappings are supported: violated restrictions or traffic blockages. These cannot \nbe combined into a single violation mapping item; each item must belong to one specific type.\n" oneOf: - $ref: '#/components/schemas/ViolationMappingItemRestriction' - $ref: '#/components/schemas/ViolationMappingItemTraffic' - $ref: '#/components/schemas/ViolationMappingItemAvoidAreasAndSegments' discriminator: propertyName: type mapping: restriction: '#/components/schemas/ViolationMappingItemRestriction' traffic: '#/components/schemas/ViolationMappingItemTraffic' avoidAreasAndSegments: '#/components/schemas/ViolationMappingItemAvoidAreasAndSegments' ViolationMappingItemRestriction: required: - category - type 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 \navailable to categorize the mapping items.\n" 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 type: type: string enum: - restriction description: 'Allows the mapping of violations of selected restrictions. Mapping of violated restrictions is supported for transport mode `truck`. For the type of `restriction`, at least one of the concrete restrictions, e.g., `grossWeight`, `currentWeight` or `height`, must be specified with value `include` or `ignore`. For example: - `{ "category": 1, "type": "restriction", "grossWeight": "include" }` - `{ "category": 1, "type": "restriction", "height": "ignore" }` ' grossWeight: description: "Indicates whether gross weight violation is included or excluded\nfor this category.\n\n**NOTE:** A weight restriction can be of type `unknown`, meaning it \nmay apply to either gross or current weight. If both the vehicle’s \ncurrent_weight and gross_weight violate an `unknown` weight restriction,\nand the user requests a violation mapping for only one of them\n(e.g., using gross_weight:include or current_weight:include), the \nservice will assign the `unknown` weight restriction to the included \nweight type.\nSimilarly, if either the vehicle’s current_weight or gross_weight \nviolates an `unknown` weight restriction, the service will assign \nthe `unknown` weight restriction to the specific weight type that \nexceeds the allowed limit.For example:\n* gross_weight=15000, current_weight=10000\n* weight_restriction_type=Unknown with value 12000\n* Since gross_weight (15,000) exceeds the restriction (12,000), \nthe `unknown` weight restriction will be mapped to gross_weight \nrather than current_weight.\n\nUser in this case will get an error code 3.\n\n* Please note that a restriction of type `unknown` may change To\n`gross` or `current` when data becomes available in future. Similarly\na restriction of type `gross` or `current` may also change to a \ndifferent type if actual regulation changes.\n" allOf: - $ref: '#/components/schemas/ViolationMappingOptionalField' default: exclude currentWeight: description: "Indicates whether current weight violation is included or excluded\nfor this category.\n\n**NOTE:** A weight restriction can be of type `unknown`, meaning it \nmay apply to either gross or current weight. If both the vehicle’s \ncurrent_weight and gross_weight violate an `unknown` weight restriction,\nand the user requests a violation mapping for only one of them\n(e.g., using gross_weight:include or current_weight:include), the \nservice will assign the `unknown` weight restriction to the included \nweight type.\nSimilarly, if either the vehicle’s current_weight or gross_weight \nviolates an `unknown` weight restriction, the service will assign \nthe `unknown` weight restriction to the specific weight type that \nexceeds the allowed limit.For example:\n* gross_weight=15000, current_weight=10000\n* weight_restriction_type=Unknown with value 12000\n* Since gross_weight (15,000) exceeds the restriction (12,000), \nthe `unknown` weight restriction will be mapped to gross_weight \nrather than current_weight.\n\nUser in this case will get an error code 3.\n\n* Please note that a restriction of type `unknown` may change To\n`gross` or `current` when data becomes available in future. Similarly\na restriction of type `gross` or `current` may also change to a \ndifferent type if actual regulation changes.\n" 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, \nexcluded or ignored for this category.\n" allOf: - $ref: '#/components/schemas/ViolationMappingOptionalField' default: ignore 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://docs.here.com/routing/docs/routing-v8-transport-modes-overview). ' enum: - car - truck - pedestrian - bicycle - taxi - scooter - bus - privateBus default: car 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, including both `origins` and `destinations`. For requests where only `origins` are specified, the `origins` list is also used as `destinations`, thus limiting the number of `origins` to 50 in such a request. ' 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, including 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. The only request parameters permitted in combination with `profile` are the required parameters `origins` and `regionDefinition`, and the optional parameters `destinations` and `matrixAttributes`. ' type: string enum: - carFast - carShort - truckFast - pedestrian - bicycle departureTime: $ref: '#/components/schemas/DepartureTimeWithAny' arrivalTime: $ref: '#/components/schemas/ArrivalTime' 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' ev: $ref: '#/components/schemas/EV' 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\nof the matrix entries summaries.\nSee `ev` and `vehicle` parameters for additional attributes to specify to calculate `consumptions`.\n\n**Notes:**\n* Access to the `consumptions` feature is currently restricted.\nIf you would like to use it, please reach out to your Account Manager or \n[contact us ](https://www.here.com/contact) to get access.\n* The attribute `consumptions` cannot be used together with `profile` parameter.\n* Requesting all three attributes is supported for matrix sizes up to 1000 x 1000.\n" type: array uniqueItems: true items: type: string enum: - travelTimes - distances - consumptions 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. \nThis mapping can classify restrictions or blockages while still providing\nthe resulting times and distances in the calculated matrix.\nItems are grouped into categories and evaluated collectively. Error codes are associated\nwith the `category`, rather than being tied to individual restrictions or blockages.\n\nThere are three distinct types of mappings:\n* violated restrictions \n* traffic-related blockages \n* violations when avoiding areas or individual segments\n\nThese mappings must be maintained as separate violation mapping items, although they can belong to \nthe same category.\n\nA violation mapping type can support additional parameters defining how a particular violation should be \nmanaged. There are three settings for these parameters:\n\n`include`: the violated restriction is added to a mapped\ncategory instead of causing a hard error code 3.\n\n`exclude`: the violated restriction is not added to a mapped\ncategory and still causes an error code 3. This is the default for\nheight and grossWeight.\n\n`ignore`: the algorithm is not taking the restriction or\nproperty / attribute of the road into consideration.\nThis is the default attribute for restrictions on bridge or time-dependent \nrestrictions.\n\nThe parameters for each mapping type are listed in the respective schema.\n\nExamples for mappings of different types as `category` 1:\n\n- map violations with violated height and violated grossWeight:
\n `{ \"category\": 1, \"type\": \"restriction\", \"grossWeight\": \"include\", \"height\": \"include\" }`\n- map violations with violated height and NOT violated grossWeight:
\n `{ \"category\": 1, \"type\": \"restriction\", \"height\": \"include\", \"grossWeight\": \"exclude\" }`\n- map violations with violated height, violation or non-violation of grossWeight doesn't\n matter:
\n `{ \"category\": 1, \"type\": \"restriction\", \"height\": \"include\", \"grossWeight\": \"ignore\" }`\n- map violations with violated height and violated currentWeight:
\n `{ \"category\": 1, \"type\": \"restriction\", \"height\": \"include\", \"currentWeight\": \"include\" }`\n- map violations with violated height and NOT violated currentWeight:
\n `{ \"category\": 1, \"type\": \"restriction\", \"height\": \"include\", \"currentWeight\": \"exclude\" }`\n- map violations with violated height, violation or non-violation of currentWeight doesn't\n matter:
\n `{ \"category\": 1, \"type\": \"restriction\",\"height\": \"include\", \"currentWeight\": \"ignore\" }`\n- map violations of avoiding an area or a segment:
\n `{ \"category\": 1, \"type\": \"avoidAreasAndSegments\" }`\n- map violations of traffic-related blockages outside of bridges:
\n `{ \"category\": 1, \"type\": \"traffic\", \"bridge\": \"exclude\" }`\n\nUnless include or exclude is stated, grossWeight or height can be\nmapped regardless, if it is timeDependent or on a bridge.\nPlease see `matrix` description in the response section for more \ninformation about error codes.\n\nIf additional types of restrictions are supported for mapping in the\nfuture, they will default to \"ignore\" to ensure consistent results.\n\nA violation mapping item belongs to either of two categories. \n\nMappings of type `traffic` or `avoidAreasAndSegments` are only supported for \ntransport modes `car` and `truck`.\n" items: $ref: '#/components/schemas/ViolationMappingItem' maxItems: 10 CountryCode: description: ISO-3166-1 alpha-3 code type: string example: FRA Truck: 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' emptyWeight: description: 'Empty weight of the vehicle combination ready to be driven, including necessary fluids and equipment determined by the local regulations, specified in kilograms. **Note:** * 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 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: 'Total vehicle length, including all trailers, specified in centimeters. **Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes. ' type: integer format: int32 minimum: 0 maximum: 30000 frontalArea: description: 'Frontal area represents the total cross section area of the vehicle as viewed from the front, specified in square meters. Physical consumption model is using this value in combination with `airDragCoefficient` to calculate the consumption caused by air resistance. **Note:** This attribute, or both `width` and `height`, is required when using `ev[consumptionModel]=physical` for EV consumption. ' type: number minimum: 0.5 maximum: 50 rollingResistanceCoefficient: description: 'Rolling resistance refers to the resistance experienced by your vehicle tire as it rolls over a surface. The main causes of this resistance are tire deformation, wing drag, and friction with the ground. The coefficient of rolling resistance is a numerical value indicating the severity of this factor. **Note:** This attribute is required when using `ev[consumptionModel]=physical` for EV consumption. ' type: number maximum: 0.5 exclusiveMinimum: 0.001 airDragCoefficient: description: 'The drag coefficient of an vehicle defines the way the vehicle is expected to pass through the surrounding air. More streamlined vehicles are more aerodynamic and therefore have smaller drag coefficient. **Note:** This attribute is required when using `ev[consumptionModel]=physical` for EV consumption. ' type: number maximum: 1 exclusiveMinimum: 0.1 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 trailerLength: description: 'Length of the longest trailer, specified in centimeters. **Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes. ' type: integer format: int32 minimum: 0 maximum: 2000 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 tiresCount: description: 'Specifies the total number of tires the vehicle has, i.e., the tires on the base vehicle and any attached trailers. ' type: integer format: int32 minimum: 1 maximum: 255 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:\n\n* `undefined`: The vehicle category is undefined, and no special considerations are taken into\n account. Vehicle routing will proceed as normal.\n* `lightTruck`: The vehicle is a truck light enough to be classified more as a car than as a truck.\n 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.\n\n For more details, refer to [Truck Categories](https://docs.here.com/routing/docs/routing-v8-truck-routing#truck-categories).\n\n **Note:** Supported only in truck transport mode.\n" 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.\nThis parameter affects the route's estimated time of arrival (ETA).\n\nLimitations:\n * valid for following transport modes: `car`, `truck`, `scooter`, `taxi`, `bus`, and `privateBus`\n\nNotes:\n * Car and Truck mode updates route ETA.\n * Scooter mode updates route optimization and ETA.\n * Resulting ETA can not be decreased by this parameter.\n" type: number minimum: 1 maximum: 70 speedCapPerFc: type: array items: type: object properties: speed: type: number description: 'Speed in meters per second (m/s). ' minimum: 1 maximum: 70 fc: type: number minimum: 1 maximum: 5 description: 'FC - Functional Class, as defined [here](https://docs.here.com/map-content/docs/functional-class). ' description: "Specifies the maximum speeds, in meters per second (m/s), per FC that the user wishes not to exceed.\nThis parameter affects the route's estimated time of arrival (ETA).\n\nLimitations:\n * valid for following transport modes: `car`, `truck`\n\nNotes:\n * Resulting ETA can not be decreased by this parameter.\n * vehicle[speedCapPerFc] and vehicle[speedCap] may be used in combination. For FCs where both values are specified, the minimum value is used.\n" 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 commercial: description: 'Specifies whether the vehicle is a commercial or a non-commercial vehicle. Used for speed limits and accessing delivery areas. * By default, trucks are considered commercial vehicles, while all other transport modes are considered non-commercial. * For commercial cars, commercial speed limits apply, which may differ from speed limits for passenger cars. * Commercial cars can enter delivery areas, similarly to trucks. * For examples and limitations see [Developer Guide](https://docs.here.com/routing/docs/routing-v8-light-commercial-vehicle-routing) **Note:** supported in `car`, `truck`, `bus`, `privateBus` and `taxi`. ' type: boolean type: $ref: '#/components/schemas/TruckType' deprecated: true TollTransponders: type: string enum: - all EVPhysicalModel: description: Specifies parameters required for calculation of energy consumption for electric vehicles using physical model. type: object properties: consumptionModel: type: string enum: - physical driveEfficiency: description: 'The proportion of the energy drawn from the battery that is used to move the vehicle. (This is to factor in energy losses through heat in the motors, for example.) ' type: number minimum: 0.1 maximum: 1 recuperationEfficiency: description: 'The proportion of the energy gained when braking or going downhill that can be recuperated and restored as battery charge. ' type: number minimum: 0 maximum: 1 auxiliaryPowerConsumption: description: 'Power (in W) consumed by the vehicle''s auxiliary systems (for example, air conditioning, lights). ' type: number minimum: 0 airDensity: description: 'The density of air (in kg/m³) used for calculating aerodynamic drag. ' type: number minimum: 0.5 maximum: 2 default: 1.225 required: - consumptionModel - driveEfficiency - recuperationEfficiency 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 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 DepartureTimeWithAny: description: 'Time of departure at all origins, in ISO 8601 (RFC 3339) format: the time zone offset is required, e.g., `2025-08-06T11:20:00+02:00` 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 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 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\nfrom routing. Each entry consists of a 3-letter country code\n(ISO 3166-1 alpha-3) and a list of 1-3 character alphanumeric codes\nrepresenting subdivision region (ISO 3166-2).\n\nFor example, to exclude USA's New York, Pennsylvania states and\nCanada's Quebec state\n [\n {\n \"country\": \"CAN\",\n \"codes\": [\"QC\"]\n },\n {\n \"country\": \"USA\",\n \"codes\": [\"NY\", \"PA\"]\n }\n ]\n\nNote - Exclude states guarantees exclusion, but doesn't guarantee\nfinding a route.\n" type: array items: $ref: '#/components/schemas/StateCode' areas: $ref: '#/components/schemas/Areas' 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 Vehicle: 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' emptyWeight: description: 'Empty weight of the vehicle combination ready to be driven, including necessary fluids and equipment determined by the local regulations, specified in kilograms. **Note:** * 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 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: 'Total vehicle length, including all trailers, specified in centimeters. **Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes. ' type: integer format: int32 minimum: 0 maximum: 30000 frontalArea: description: 'Frontal area represents the total cross section area of the vehicle as viewed from the front, specified in square meters. Physical consumption model is using this value in combination with `airDragCoefficient` to calculate the consumption caused by air resistance. **Note:** This attribute, or both `width` and `height`, is required when using `ev[consumptionModel]=physical` for EV consumption. ' type: number minimum: 0.5 maximum: 50 rollingResistanceCoefficient: description: 'Rolling resistance refers to the resistance experienced by your vehicle tire as it rolls over a surface. The main causes of this resistance are tire deformation, wing drag, and friction with the ground. The coefficient of rolling resistance is a numerical value indicating the severity of this factor. **Note:** This attribute is required when using `ev[consumptionModel]=physical` for EV consumption. ' type: number maximum: 0.5 exclusiveMinimum: 0.001 airDragCoefficient: description: 'The drag coefficient of an vehicle defines the way the vehicle is expected to pass through the surrounding air. More streamlined vehicles are more aerodynamic and therefore have smaller drag coefficient. **Note:** This attribute is required when using `ev[consumptionModel]=physical` for EV consumption. ' type: number maximum: 1 exclusiveMinimum: 0.1 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 trailerLength: description: 'Length of the longest trailer, specified in centimeters. **Note:** Supported in truck, bus, privateBus, car (Beta), taxi (Beta) transport modes. ' type: integer format: int32 minimum: 0 maximum: 2000 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 tiresCount: description: 'Specifies the total number of tires the vehicle has, i.e., the tires on the base vehicle and any attached trailers. ' type: integer format: int32 minimum: 1 maximum: 255 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:\n\n* `undefined`: The vehicle category is undefined, and no special considerations are taken into\n account. Vehicle routing will proceed as normal.\n* `lightTruck`: The vehicle is a truck light enough to be classified more as a car than as a truck.\n 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.\n\n For more details, refer to [Truck Categories](https://docs.here.com/routing/docs/routing-v8-truck-routing#truck-categories).\n\n **Note:** Supported only in truck transport mode.\n" 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.\nThis parameter affects the route's estimated time of arrival (ETA).\n\nLimitations:\n * valid for following transport modes: `car`, `truck`, `scooter`, `taxi`, `bus`, and `privateBus`\n\nNotes:\n * Car and Truck mode updates route ETA.\n * Scooter mode updates route optimization and ETA.\n * Resulting ETA can not be decreased by this parameter.\n" type: number minimum: 1 maximum: 70 speedCapPerFc: type: array items: type: object properties: speed: type: number description: 'Speed in meters per second (m/s). ' minimum: 1 maximum: 70 fc: type: number minimum: 1 maximum: 5 description: 'FC - Functional Class, as defined [here](https://docs.here.com/map-content/docs/functional-class). ' description: "Specifies the maximum speeds, in meters per second (m/s), per FC that the user wishes not to exceed.\nThis parameter affects the route's estimated time of arrival (ETA).\n\nLimitations:\n * valid for following transport modes: `car`, `truck`\n\nNotes:\n * Resulting ETA can not be decreased by this parameter.\n * vehicle[speedCapPerFc] and vehicle[speedCap] may be used in combination. For FCs where both values are specified, the minimum value is used.\n" 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 commercial: description: 'Specifies whether the vehicle is a commercial or a non-commercial vehicle. Used for speed limits and accessing delivery areas. * By default, trucks are considered commercial vehicles, while all other transport modes are considered non-commercial. * For commercial cars, commercial speed limits apply, which may differ from speed limits for passenger cars. * Commercial cars can enter delivery areas, similarly to trucks. * For examples and limitations see [Developer Guide](https://docs.here.com/routing/docs/routing-v8-light-commercial-vehicle-routing) **Note:** supported in `car`, `truck`, `bus`, `privateBus` and `taxi`. ' type: boolean type: $ref: '#/components/schemas/VehicleType' ArrivalTime: description: 'Time of arrival at a destination, in ISO 8601 (RFC 3339) format: the time zone offset is required, e.g., `2025-08-06T11:20:00+02:00` `arrivalTime` can not be used together with `departureTime`. Note: This parameter can only be used for N x 1 matrix (multiple origins, single destination) calculation in flexible mode. ' type: string 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-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 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-Correlation-Id: description: Auto-generated id that univocally identifies the request. schema: type: string example: 4199533b-6290-41db-8d79-edf4f4019a74 responses: MatrixResponse: description: 'Result matrix was calculated for the requested `origins` and `destinations`. The matrix contains 3 optional flat arrays, `travelTimes`, `distances`, and `consumptions` 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 the [Identity and Access Management Developer Guide](https://docs.here.com/identity-and-access-management/docs/readme). ' 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 the [Identity and Access Management Developer Guide](https://docs.here.com/identity-and-access-management/docs/readme). ' externalDocs: description: Developer Guide and Release Notes url: https://www.here.com/docs/category/matrix-routing-api-v8