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

Matrix v4 trả về thời gian (giây) hoặc quãng đường (mét) cho mọi cặp điểm đi → điểm đến trong một lần gọi, thay vì gọi Route N×M lần. Response chỉ có số, không có geometry. Chọn điểm đi bằng sources, điểm đến bằng destinations, loại dữ liệu bằng annotation.

Dùng khi cần chọn shipper hoặc cửa hàng gần khách nhất (ma trận 1×N), hoặc lấy ma trận N×N làm đầu vào cho bộ giải tuyến của bạn. Cần sắp thứ tự điểm thì dùng TSP v4; chia điểm cho nhiều xe thì dùng VRP.

Playground¶

Thử ngay trên Playground

Gọi thử Matrix v4 với dữ liệu thật, không cần viết code: Mở 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

Hoặc dùng thử bằng Postman.

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	`Điểm 0` và `Điểm 1` là điểm đi → ma trận có 2 hàng
destinations	2;3;4;5	`Điểm 2` đến `Điểm 5` là điểm đến → ma trận có 4 cột

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 ]],`	`durations[i][j]` là thời gian (giây) từ `sources[i]` tới `destinations[j]`. Mỗi hàng một điểm đi, mỗi cột một điểm đến.
distances	array	`[[1766.3, 1374.3, 1952.2, 1113.5], [507.5, 1152.4, 2101.8, 399.4]]`	Cùng bố cục với `durations`, đơn vị 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.