Route¶

A Route Maps API is a feature provided by VIETMAP that allows developers to calculate and display the optimal route between two or more locations on a map. With a Route Maps API, developers can specify the start and end points of a journey, along with any additional constraints such as preferred mode of transportation, and retrieve a detailed route that can be displayed on a map. The API may also provide information such as the total distance, estimated travel time, and turn-by-turn directions. Developers can use Route Maps APIs to create applications that help with navigation, transportation planning, and logistics management.

Playground¶

You can test the Route v4 API in our Live Map.

AI Agent Integration NEW

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

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
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`. Config the vehicle profiles for which the route should be calculated.
optimize	string	no	false	Execute TSP if the value = true. Under normal case, please do not enable this parameter (Not yet supported)
avoid	string	no	null	Avoid a specific road types, such as `ferry`.
capacity	integer	conditional	null	Required only when the `vehicle=truck`, represent for the truck's weight in kilogram
time	string	no	2025-08-01T12:01:00Z	Departure time, default value is the current date time Time sending with `ISO-8601 date representation` (UTC 0)
alternative	boolean	no	false	Return any alternative route or not
heading	number	no	null	Current heading of vehicle
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	Weight assigned to the route
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[]	Array of annotation object to calculate speed, congestion. Details at Annotation Object Model (if available)
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)

Note that when calculate route with > 2 waypoints, the annotations data may not valid

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.