Matrix — Ma trận khoảng cách¶

Matrix API nằm trong bộ VIETMAP Directions API, giúp bạn tính khoảng cách và thời gian giữa nhiều điểm với nhiều điểm, hiệu quả hơn hẳn việc gọi Routing API nhiều lần.

Routing API hỗ trợ nhiều điểm trung gian ('via points') nhưng chỉ trả về một tuyến đường. Còn Matrix API tính ra NxM tuyến — chính xác hơn là NxM khoảng cách hoặc thời gian di chuyển — và nhanh hơn hẳn so với gọi Routing API NxM lần.

Ví dụ đơn giản nhất: một khách du lịch muốn biết tiệm pizza nào gần mình nhất — thay vì đo đường chim bay, cô ấy tính một ma trận 1x4. Hoặc một dịch vụ giao hàng cần chọn shipper nào phù hợp cho một đơn cụ thể.

Vài trường hợp dùng khác của Matrix API:

Bài toán logistics thường phải lấy hàng ở nhiều nơi rồi giao tới nhiều nơi.
Tính các đường vòng qua nhiều điểm trung gian rồi chọn phương án tốt nhất, ví dụ cho ứng dụng đi chung xe hoặc taxi. Trường hợp này cần yêu cầu 1-nhiều.
Tìm lộ trình tốt nhất cho khách du lịch muốn ghé được càng nhiều điểm tham quan càng tốt.

Playground¶

Bạn có thể thử Matrix API trên Playground.

Tích hợp AI Agent MỚI

Tải bộ tài liệu đã tối ưu cho AI agent (Matrix + TSP + VRP): Logistics Agent Doc

URL¶

https://maps.vietmap.vn/api/matrix/v4?apikey={your-apikey}&point={point}&point={point}&point={point}&points_encoded={points_encoded}&vehicle={vehicle}&sources={sources}&destinations={destinations}&annotation={annotation}

Method¶

GET

Chuyển từ bản cũ (tóm tắt)¶

Endpoint đổi từ /api/matrix?api-version=1.1 sang /api/matrix/v4 (không dùng tham số api-version nữa).
Matrix v4 chạy trên cùng bộ máy định tuyến v4 với Route v4, nên kết quả khớp với tuyến v4.
Tham số request và định dạng phản hồi giữ nguyên, nên chuyển đổi chỉ là đổi URL.

Xem tài liệu bản cũ: Matrix (ngừng hỗ trợ).

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 ma trận. Ví dụ: `vehicle=truck`
sources	int or string	không	all	Chỉ số các điểm dùng làm điểm đi, đếm từ `0` theo thứ tự `point` gửi lên. Nhiều điểm thì ngăn bằng dấu `;`, hoặc `all` để lấy tất cả. Ví dụ: gửi 7 điểm, lấy 2 điểm đầu làm điểm đi thì `sources=0;1`
destinations	int or string	không	all	Chỉ số các điểm dùng làm điểm đến, đếm từ `0`. Nhiều điểm thì ngăn bằng dấu `;`, hoặc `all`. Ví dụ: với 7 điểm ở trên, 5 điểm còn lại là `destinations=2;3;4;5;6`
annotation	string	không	duration	Chọn dữ liệu trả về trong ma trận. Giá trị cho phép: `duration` (thời gian, giây), `distance` (quãng đường, mét). Ví dụ: `annotation=distance`

Ví dụ¶

URL (kèm tham số)¶

https://maps.vietmap.vn/api/matrix/v4?apikey={your-apikey}&point=10.768897,106.678505&point=10.765496,106.67626&point=10.7627936,106.6750729&point=10.7616745,106.6792425&point=10.765605,106.685383&point=10.766843,106.674029&sources=0;1&destinations=2;3;4;5

Mô tả tham số query:

Tham số	Giá trị	Mô tả
point	10.768897,106.678505	`Điểm 0`, định dạng `lat,lng`
point	10.765496,106.67626	`Điểm 1`, định dạng `lat,lng`
point	10.7627936,106.6750729	`Điểm 2`, định dạng `lat,lng`
point	10.7616745,106.6792425	`Điểm 3`, định dạng `lat,lng`
point	10.765605,106.685383	`Điểm 4`, định dạng `lat,lng`
point	10.766843,106.674029	`Điểm 5`, định dạng `lat,lng`
sources	0;1	Chỉ số các điểm dùng làm điểm đi, đếm từ `0` theo thứ tự `point` gửi lên. Nhiều điểm thì ngăn bằng dấu `;`, hoặc `all` để lấy tất cả. Ví dụ: gửi 7 điểm, lấy 2 điểm đầu làm điểm đi thì `sources=0;1`
destinations	2;3;4;5	Chỉ số các điểm dùng làm điểm đến, đếm từ `0`. Nhiều điểm thì ngăn bằng dấu `;`, hoặc `all`. Ví dụ: với 7 điểm ở trên, 5 điểm còn lại là `destinations=2;3;4;5;6`

Phản hồi¶

{
    "code": "OK",
    "messages": null,
    "durations": [
        [
            230,
            201,
            386,
            193
        ],
        [
            126,
            188,
            435,
            108
        ]
    ],
    "distances": [
        [
            1766.3,
            1374.3,
            1952.2,
            1113.5
        ],
        [
            507.5,
            1152.4,
            2101.8,
            399.4
        ]
    ]
}

Mô tả phản hồi¶

Trường	Kiểu	Giá trị	Mô tả
code	string	`'OK'`	Mã trạng thái của phản hồi. Chi tiết ở Các mã trạng thái
messages	string	`null`	Thông báo kèm theo phản hồi, nếu có.
durations	array	`[[230, 201, 386, 193 ], [ 126, 188, 435, 108 ]],`	Mảng chứa thông tin thời gian (giây).
distances	array	`[[1766.3, 1374.3, 1952.2, 1113.5], [507.5, 1152.4, 2101.8, 399.4]]`	Mảng chứa thông tin quãng đường (mét).

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.