Route¶

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¶

Try it in the Playground

Call Route v4 with real data, no code required: Open Playground · or explore it on the Live Map

AI Agent Integration NEW

Download the optimized doc for AI agent integration: Routing Agent Doc

Or try it in Postman.

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
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

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

Response

{
  "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
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
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
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 (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
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.