Route v3 — Chỉ đường¶
Ngừng hỗ trợ
Chúng tôi khuyên dùng Route v4 API cho tích hợp mới. Route v3 API sẽ ngừng hỗ trợ trong tương lai.
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 khai điểm đầu và điểm cuối của hành trình, kèm các ràng buộc khác như loại phương tiện, rồi nhận về tuyến đường chi tiết để vẽ lên bản đồ. API cũng trả về tổng quãng đường, thời gian đi ước tính và hướng dẫn đi từng chặng. Bạn dùng Route API để làm các ứng dụng dẫn đường, lập kế hoạch vận tải và quản lý logistics.
Playground¶
Bạn có thể thử Route v3 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/v3?apikey={your-apikey}&point={point}&point={point}&points_encoded={points_encoded}&vehicle={vehicle}&annotations={annotations}
Method¶
GET
Tham số¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| 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. 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 | Tránh một số loại đường, ví dụ ferry (phà). |
| 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, mặc định là thời điểm hiện tại. Gửi theo chuẩn ISO-8601 (UTC+0) |
| alternative | boolean | không | false | Có trả về tuyến thay thế hay không |
| heading | number | không | null | Hướng xe đang đi |
| annotations | string | không | null |
Bật thêm dữ liệu phụ theo từng đoạn của 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. Example: annotations=congestion,congestion_distance. (Requesting annotations increases compute time and payload size.) |
Ví dụ¶
Đầu vào
https://maps.vietmap.vn/api/route/v3?apikey={apikey}&point=10.755222,106.662633&point=10.7559910,106.6633234&vehicle=truck&capacity=2000
Phản hồi
{
"license": "vietmap",
"code": "OK",
"paths": [
{
"distance": 2194.4,
"weight": 351.4,
"time": 351400,
"transfers": 0,
"points_encoded": true,
"bbox": [106.70594, 10.79479, 106.71154, 10.80325],
"points": "}s{`Ac_hjSjAkCFQRu@Lu@F_@D]Ng@ZaALa@JY~AoDDEmBiBe@[WMg@M_@KmA]uA_@a@KkA]qA[[Gs@MUE_AKu@Co@Ew@CYAmAGeBKaAEsAKCQMQUGM?KBIFGHCJoBO{@Ck@AQ@MZAJAjAG|ACz@MnCEnAGlBCx@EjA?\\EvAEjBE~@Cr@F?HqBv@DBSDIBAl@HFADAVSD@JLB@h@BDADEDAJ@",
"instructions": [
{
"distance": 403.4,
"heading": 0,
"sign": 0,
"interval": [0, 11],
"text": "Tiếp tục theo Nguyễn Cửu Vân",
"time": 54800,
"street_name": "Nguyễn Cửu Vân",
"last_heading": null
},
/// More guide direction here
{
"distance": 58.7,
"heading": 0,
"sign": 0,
"interval": [71, 79],
"text": "Tiếp tục theo Đường Không Tên",
"time": 26300,
"street_name": "Đường Không Tên",
"last_heading": null
},
{
"distance": 0,
"heading": 0,
"sign": 4,
"interval": [79, 79],
"text": "Đích đến",
"time": 0,
"street_name": "Đường Không Tên",
"last_heading": null
}
],
"snapped_waypoints": "c_hjS}s{`AeDab@"
}
]
}
Mô tả phản hồi¶
| Parameter | Type | Description |
|---|---|---|
| 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:
| Sub-Parameter | Type | Description |
|---|---|---|
| distance | number | Tổng quãng đường của tuyến, tính bằng mét |
| weight | number | Trọng số nội bộ mà bộ định tuyến gán cho tuyến, dùng để so sánh các tuyến với nhau |
| time | int | Tổng thời gian đi hết tuyến, tính bằng mili giây |
| transfers | int | Số lần chuyển tuyến trong hành trình |
| points_encoded | boolean | Cho biết points và snapped_waypoints là chuỗi mã hóa polyline hay mảng tọa độ JSON |
| bbox | array | Khung bao của 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ì trả về danh sách tọa độ dạng [lat,lng]. |
| instructions | array | Mảng 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ó) |
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 |
| heading | int | Hướng đi tại bước này, tính bằng độ (0 = Bắc). Có thể vắng mặt |
| 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, ứ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] |
| text | string | Mô tả việc người dùng cần làm để đi đúng tuyến |
| time | int | Thời lượng của bước này, tính bằng mili giây |
| 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¶
| Name | Type | Description |
|---|---|---|
| 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
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.
