Route — Chỉ đường¶

Route API của VIETMAP cho phép bạn tính và hiển thị tuyến đường tối ưu giữa hai hay nhiều vị trí trên bản đồ. Bạn gắn chức năng chỉ đường này vào ứng dụng của mình để người dùng tìm được đường đi hiệu quả nhất giữa các điểm.

Playground¶

Bạn có thể thử Route v4 trên Live Map.

Tích hợp AI Agent MỚI

Tải bộ tài liệu đã tối ưu cho AI agent: Routing Agent Doc

URL¶

https://maps.vietmap.vn/api/route/v4?apikey={your-apikey}&point=10.762622,106.660172&point=10.801891,106.706610&points_encoded=true&vehicle=car&annotations=congestion,toll

Method¶

GET

Tham số¶

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
apikey	string	có	không	API key VIETMAP cấp cho tài khoản của bạn. Đăng ký tại đây
point	array string	có	không	Các điểm cần tính tuyến. Định dạng `[latitude,longitude]` — vĩ độ trước. Ít nhất phải có điểm đi và điểm đến; có thể thêm điểm trung gian. Số điểm tối đa tùy theo gói bạn đang dùng. Ví dụ: `&point=10.762622,106.660172`
points_encoded	boolean	không	true	Chọn cách mã hóa tọa độ trả về trong `points` và `snapped_waypoints`. `true`: chuỗi polyline `google polyline 5` — payload nhỏ, phía client phải dùng thư viện polyline để giải mã. `false`: trả về mảng tọa độ thô, đọc được ngay. Mặc định `true`. Chúng tôi khuyên để `true` để giảm kích thước JSON phản hồi.
vehicle	string	không	car	Enum: `car`, `motorcycle`, `truck`, `container`. Loại phương tiện dùng để tính tuyến — quyết định tốc độ và các đường được phép đi.
optimize	string	không	false	Đặt `true` để chạy TSP sắp lại thứ tự điểm. Bình thường bạn đừng bật tham số này. (Chưa hỗ trợ — hiện gửi lên sẽ bị bỏ qua)
avoid	string	không	null	Loại đường cần tránh khi tính tuyến. Giá trị cho phép: `ferry` (phà). Ví dụ: `avoid=ferry`
capacity	integer	tùy điều kiện	null	Chỉ bắt buộc khi `vehicle=truck`, là khối lượng xe tải tính bằng kilogram
time	string	không	2025-08-01T12:01:00Z	Giờ khởi hành theo chuẩn `ISO-8601` (UTC+0). Bỏ trống thì lấy thời điểm hiện tại. Ví dụ: `time=2025-08-01T12:01:00Z`
alternative	boolean	không	false	Đặt `true` để nhận thêm tuyến thay thế ngoài tuyến tốt nhất. Ví dụ: `alternative=true`
heading	number	không	null	Hướng xe đang đi, tính bằng độ trong dải `0`–`360`, `0` = hướng Bắc. Dùng để chọn chiều xuất phát đúng làn. Ví dụ: `heading=45`
annotations	string	không	`null`	Bật thêm dữ liệu phụ cho tuyến. Truyền danh sách khóa cách nhau bằng dấu phẩy. Giá trị cho phép: `congestion`, `congestion_distance`, `toll`. Truyền `toll` sẽ điền dữ liệu vào hai trường `toll_cost` và `tolls` của từng tuyến. Ví dụ: `annotations=congestion,toll`. (Bật annotations làm tăng thời gian tính và kích thước phản hồi.)

Ví dụ¶

Đầu vào

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

Phản hồi

{
  "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
          }
        }
      ]
    }
  ]
}

Mô tả phản hồi¶

Trường	Kiểu	Mô tả
license	string	Loại giấy phép của dữ liệu chỉ đường
code	string	Mã trạng thái cho biết yêu cầu thành công hay thất bại. Chi tiết ở Các mã trạng thái
messages	string	Thông báo thêm liên quan tới yêu cầu (nếu có)
paths	array	Mảng chứa thông tin tuyến: quãng đường, thời gian, v.v.

Với mỗi tuyến trong mảng paths:

Trường con	Kiểu	Mô tả
distance	number	Tổng quãng đường của tuyến, tính bằng mét. Ví dụ: `194465.7` (~194 km)
weight	number	Trọng số gán cho tuyến
time	int	Giờ khởi hành theo chuẩn `ISO-8601` (UTC+0). Bỏ trống thì lấy thời điểm hiện tại. Ví dụ: `time=2025-08-01T12:01:00Z`
transfers	int	Số lần chuyển tuyến cần thiết
points_encoded	boolean	Cho biết `points` và `snapped_waypoints` là chuỗi mã hóa polyline hay mảng JSON tọa độ
bbox	array	Khung bao của hình học tuyến. Định dạng: [`minLon`, `minLat`, `maxLon`, `maxLat`]
points	string	Chuỗi điểm mã hóa theo `google polyline 5`. Nếu `points_encoded` là `false` thì points trả về danh sách `[lat,lng]` format.
instructions	array	Mảng chứa hướng dẫn đi từng chặng. Chi tiết ở Instruction Object Model
snapped_waypoints	string	Các điểm đã bám vào đường của tuyến (nếu có)
annotations	object[]	Mảng annotation dùng để tính tốc độ và mức kẹt xe. Chi tiết ở Annotation Object Model (nếu có)
toll_cost	number	Tổng phí cầu đường của tuyến, tính bằng VNĐ, theo đúng `vehicle` đã gửi. Chỉ có khi request kèm `annotations=toll`. Ví dụ: `140000`
tolls	object[]	Mảng các trạm thu phí dọc tuyến. Chi tiết ở Toll Object Model (nếu có)

Instruction Object Model¶

Với mỗi hướng dẫn trong mảng instructions:

Trường con	Kiểu	Mô tả
distance	double	Quãng đường tới hướng dẫn kế tiếp, tính bằng mét. Ví dụ: `192`
heading	int	Hướng xe đang đi, tính bằng độ trong dải `0`–`360`, `0` = hướng Bắc. Dùng để chọn chiều xuất phát đúng làn. Ví dụ: `heading=45`
sign	int	Mã hướng rẽ của bước hướng dẫn, xem bảng ký hiệu tại đây
interval	array	Hai chỉ số trong mảng `points` (đã giải mã), ứng với điểm đầu và điểm cuối của đoạn mà hướng dẫn này nói tới. Ví dụ: `[0, 49]` nghĩa là bước này trải từ điểm thứ 0 đến điểm thứ 49.
text	string	Mô tả việc người dùng cần làm để đi đúng tuyến.
time	int	Giờ khởi hành theo chuẩn `ISO-8601` (UTC+0). Bỏ trống thì lấy thời điểm hiện tại. Ví dụ: `time=2025-08-01T12:01:00Z`
street_name	string	Tên đường cần rẽ vào để đi đúng tuyến.
last_heading	null	Hướng đi cuối của bước hướng dẫn (nếu có)

Annotation Object Model¶

Tên	Kiểu	Mô tả
congestion	`object[]`	Mảng mức kẹt xe của từng đoạn. (nếu có) Các giá trị: `low`, `moderate`, `heavy`, `severe`, `unknown`. Dựa trên tốc độ trung bình (km/h): `low`: ≥ 40; `moderate`: 20–<40; `heavy`: 10–<20; `severe`: >0–≤10.
congestion_distance	`object[]`	Mảng quãng đường (mét), chỉ gồm các đoạn có mức kẹt từ `heavy` trở lên. (nếu có)

Lưu ý: khi tính tuyến với > 2 điểm, dữ liệu annotations có thể không chính xác

Toll Object Model¶

Với mỗi trạm thu phí trong mảng tolls:

Trường con	Kiểu	Mô tả
id	int	Mã định danh của trạm thu phí.
name	string	Tên trạm thu phí.
address	string	Địa chỉ hoặc tuyến đường đặt trạm thu phí.
type	string	Vai trò của trạm trên tuyến. Enum: `entry` (trạm xe vào), `exit` (trạm xe ra, cũng là nơi tính phí).
price	number	Mức phí thu tại trạm này cho `vehicle` đã gửi, tính bằng VNĐ. Ví dụ: `140000`
prices	object	Bảng phí (VNĐ) theo mã hạng xe, liệt kê mức thu cho từng hạng xe được hỗ trợ tại trạm này. (nếu có)

Các mã trạng thái¶

OK: Yêu cầu thành công, phản hồi chứa dữ liệu hợp lệ.
INVALID_REQUEST: Tham số gửi lên không hợp lệ. Chi tiết lỗi nằm trong trường messages của phản hồi.
OVER_DAILY_LIMIT: API key đã vượt hạn mức lượt gọi trong ngày. Các lượt gọi tiếp theo sẽ không được xử lý cho tới khi hạn mức được đặt lại.
MAX_POINTS_EXCEED: Số điểm trong URL vượt quá mức tối đa của gói bạn đang dùng. Bạn giảm bớt số điểm rồi gọi lại.
ERROR_UNKNOWN: Có lỗi ngoài dự kiến khi xử lý yêu cầu. Bạn xem trường messages để biết thêm, hoặc liên hệ hỗ trợ nếu vẫn không được.
ZERO_RESULTS: Không tìm được tuyến đường khả thi giữa các điểm yêu cầu.