Source: https://maps.vietmap.vn/docs/map-api/route-version/route-v4/
# Route
[![Route]][Route]
[Route]: https://maps.vietmap.vn/docs/assets/routing-jpg.webp
---
Route v4 returns the best road route between two or more points for `car`, `motorcycle`, `truck` or `container` (honouring weight limits). The response includes distance, travel time, encoded geometry and turn-by-turn instructions; add `annotations=toll` to get the toll stations on the route and the total `toll_cost` for the requested vehicle.
### Playground
!!! tip "Try it in the Playground"
Call Route v4 with real data, no code required: **[Open Playground](https://tools.vietmap.vn/playground/route)** · or explore it on the [Live Map](https://tools.vietmap.vn/live/)
!!! tip "AI Agent Integration :sparkles: NEW"
Download the optimized doc for AI agent integration: **Routing Agent Doc** · Machine-readable schema: **[OpenAPI 3.1](/docs/openapi.json)**
Or try it in [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).
### URL
```
https://maps.vietmap.vn/api/route/v4?apikey={your-apikey}&point={point}&point={point}&points_encoded={points_encoded}&vehicle={vehicle}&annotations={annotations}
```
## Method
**GET**
## Parameters
| Parameter | Type | Required | Default | Description |
| -------------- | ------------ | ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|apikey|string|yes|none|API key provided by VIETMAP for your account. [Register here](https://maps.vietmap.vn/console-v2/register)|
| point | array string | yes | none | The points for which the route should be calculated. Format: [latitude,longitude]. Specify at least an origin and a destination. Via points are possible. The maximum number depends on your plan. Example query: `&point=lat,lng` |
| points_encoded | boolean | no | true | Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact but requires special client code to unpack. Set this parameter to false to switch the encoding to simple coordinate pairs like [lon,lat]. See the description of the response format for more information. We suggest this query should receive `true` value to decrease the size of the response JSON. |
| vehicle | string | no | car | Enum: `car`, `motorcycle`, `truck`, `container`. Routing profile — determines speed and which roads are allowed. |
| optimize | string | no | false | **Not yet supported** — the server ignores this parameter. Planned: `true` to reorder via points for the shortest total route (TSP). |
| avoid | string | no | null | Road types to avoid. **Allowed values:** `ferry`. **Example:** `avoid=ferry` |
| capacity | integer | conditional | null | Required when `vehicle=truck`. Gross vehicle weight in kilograms. |
| time | string | no | 2025-08-01T12:01:00Z | Departure time in ISO-8601 (UTC). Defaults to now. **Example:** `time=2025-08-01T12:01:00Z` |
| alternative | boolean | no | false | Set `true` to also return alternative routes in `paths`. **Example:** `alternative=true` |
| heading | number | no | null | Current heading of the vehicle in **degrees**, `0`–`360`, `0` = north. Used to pick the correct departure direction. **Example:** `heading=45` |
| annotations | string | no | `null` | Enables extra metadata for the route. Provide a **comma-separated** list of keys. **Allowed values:** `congestion`, `congestion_distance`, `toll`. Requesting `toll` populates the `toll_cost` and `tolls` fields in each path.
**Example:** `annotations=congestion,toll`. (Requesting annotations increases compute time and payload size.) |
## Example
**Input**
```url
https://maps.vietmap.vn/api/route/v4?apikey={apikey}&point=18.7338,105.6209&point=17.75697,106.12351&vehicle=truck&capacity=2000&annotations=congestion,toll
```
[:material-play-circle: Run this example on the Playground](https://tools.vietmap.vn/playground/route?point=18.7338,105.6209&point=17.75697,106.12351&vehicle=truck&capacity=2000&annotations=congestion,toll){ .md-button .md-button--primary }
**Response**
```json
{
"license": "vietmap",
"code": "OK",
"paths": [
{
"distance": 194465.7,
"weight": 10854.3,
"time": 10854078,
"transfers": 0,
"points_encoded": true,
"bbox": [105.6139, 17.75471, 106.37462, 18.73474],
"points": "ccjqBkhtcS`E{DhFyDzDeBjHkC`Bg@xEkAnEaA|LwCxH{A~Ag@rDs@hA]bAg@|BwA~@}@dAmApG}BdHiBbCo@...",
"instructions": [
{
"distance": 3590.7,
"heading": 0,
"sign": 0,
"interval": [0, 49],
"text": "",
"time": 861754,
"street_name": ""
},
{
"distance": 1191,
"heading": 0,
"sign": 2,
"interval": [49, 67],
"text": "Quốc Lộ 46",
"time": 95123,
"street_name": "Quốc Lộ 46"
},
/// More guide direction here
{
"distance": 0,
"heading": 0,
"sign": 4,
"interval": [1555, 1555],
"text": "",
"time": 0,
"street_name": ""
}
],
"snapped_waypoints": "ccjqBkhtcSdl~DydaB",
"toll_cost": 59000,
"tolls": [
{
"id": 528,
"name": "Trạm Thu Phí Nút Giao Quốc Lộ 46B",
"address": "Cao Tốc Diễn Châu Bãi Vọt",
"type": "entry",
"price": 0
},
{
"id": 544,
"name": "Trạm Thu Phí Km 479+200",
"address": "Cao Tốc Diễn Châu Bãi Vọt",
"type": "exit",
"price": 59000,
"prices": {
"523": 140000,
"524": 96000,
"528": 59000
}
}
]
}
]
}
```
### Response description
| Parameter | Type | Description |
| --------- | ------ | ----------------------------------------------------------------- |
| license | string | License type associated with the routing data |
| code | string | Status code indicating the success or failure of the request. Details at [Status Code Values](#status-code-values) |
| messages | string | Additional messages related to the request (if any) |
| paths | array | Array containing route information including distance, time, etc. |
For each route in the `paths` array:
| Sub-Parameter | Type | Description |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| distance | number | Total distance of the route (in meters) |
| weight | number | Internal routing cost used to rank candidate paths. Unitless; only meaningful for comparing routes in the same response. |
| time | int | Total time required for the route (in milliseconds) |
| transfers | int | Number of transfers required for the route |
| points_encoded | boolean | Whether the `points` and `snapped_waypoints` fields are polyline-encoded strings rather than JSON arrays of coordinates |
| bbox | array | The bounding box of the route geometry. Format: [`minLon`, `minLat`, `maxLon`, `maxLat`] |
| points | string | Encoded points representing the route using `google polyline 5` format. If the `points_encoded` is `false`, points will response a list of `[lat,lng]` format. |
| instructions | array | Array containing turn-by-turn navigation instructions. Details at [Instruction Object Model](#instruction-object-model) |
| snapped_waypoints | string | Snapped waypoints representing the route (if available) |
| annotations | object[] | Per-segment metadata (`congestion`, `congestion_distance`). Present only when requested via `annotations`. See [Annotation Object Model](#annotation-object-model) |
| toll_cost | number | Total toll cost for the route (in VND), calculated for the requested `vehicle`. (if available) |
| tolls | object[]| Array of toll stations along the route. Details at [Toll Object Model](#toll-object-model) (if available) |
### Instruction Object Model
For each navigation instruction in the `instructions` array:
| Sub-Parameter | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| distance | double | Distance until the next instruction (in meters) |
| heading | int | Heading direction of the instruction (if available) |
| sign | int | Direction sign of the instruction, sign description [here](https://www.figma.com/design/rWyQ5TNtt6E5l8tPEE9Tkl/VietMap-navigation-symbol?node-id=354-4&t=cgtrhx0jyyMWdZ45-0) |
| interval | array | Two indices into points, referring to the beginning and the end of the segment of the route this instruction refers to. |
| text | string | A description what the user has to do in order to follow the route. |
| time | int | The duration for this instruction, in milliseconds. |
| street_name | string | The name of the street to turn onto in order to follow the route. |
| last_heading | null | Last heading direction of the instruction (if available) |
### Annotation Object Model
| Name | Type | Description |
| --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| congestion | `object[]` | Array of congestion levels for segments.(if available)
**Possible values:** `low`, `moderate`, `heavy`, `severe`, `unknown`.
**Based on average speed (km/h):**
`low`: ≥ 40;
`moderate`: 20–<40;
`heavy`: 10–<20;
`severe`: >0–≤10. |
| congestion_distance | `object[]`| Array of distances (in meters) that only includes segments where congestion level is ≥ `heavy`. (if available) |
- With more than 2 `point` values, `annotations` data may be inaccurate.
### Toll Object Model
For each toll station in the `tolls` array:
| Sub-Parameter | Type | Description |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | int | Unique identifier of the toll station. |
| name | string | Name of the toll station. |
| address | string | Address or road on which the toll station is located. |
| type | string | The role of the station on the route. Enum: `entry` (toll booth where the vehicle enters), `exit` (toll booth where the vehicle exits and where the price is charged). |
| price | number | Toll price charged at this station for the requested `vehicle` (in VND). |
| prices | object | Map of toll prices (in VND) keyed by vehicle class id, listing the charge for each supported vehicle class at this station. (if available) |
### Status Code Values
- `OK`: The request was successful and the response contains valid data.
- `INVALID_REQUEST`: The request parameters failed validation. Details about the validation errors are provided in the messages field of the response.
- `OVER_DAILY_LIMIT`: The daily request limit for your API key has been exceeded. No further requests will be processed until the limit resets.
- `MAX_POINTS_EXCEED`: The number of points in the request URL exceeds the allowed maximum for your plan. Reduce the number of points and try again.
- `ERROR_UNKNOWN`: An unexpected error occurred while processing the API request. Please check the messages field for more information or contact support if the issue persists.
- `ZERO_RESULTS`: No viable route was found between the requested waypoints.
!!! tip "Try it with your own data"
Enter your own addresses, coordinates or parameters and see the result on a map, with a cURL command to copy: **[Open Route v4 on the Playground](https://tools.vietmap.vn/playground/route)**