Matrix (v1.1) — Ma trận khoảng cách¶

Ngừng hỗ trợ

Chúng tôi khuyên dùng Matrix v4 API cho tích hợp mới. Phiên bản Matrix API này sẽ ngừng hỗ trợ trong tương lai.

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 thường xuyên cần các ma trận NxN lớn để giải bài toán chia tuyến đội xe.

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.

URL¶

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

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	int or string	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`, `bike`, `foot`, `motorcycle`. Chọn loại phương tiện để tính tuyến.
sources	int or string	không	all	Chỉ số các điểm dùng làm điểm đi, đếm từ `0`, hoặc `all`. Ví dụ có 7 điểm, lấy 2 điểm đầu làm điểm đi thì `sources=0;1`. Nhiều điểm thì ngăn bằng dấu `;`
destinations	int or string	không	all	Chỉ số các điểm dùng làm điểm đến, đếm từ `0`, hoặc `all`. Với ví dụ 7 điểm ở trên thì `destinations=2;3;4;5;6`. Nhiều điểm thì ngăn bằng dấu `;`
annotation	string	không	duration	Enum: duration, distance

Ví dụ¶

URL (Parameters)¶

https://maps.vietmap.vn/api/matrix?api-version=1.1&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

Query param description:

Param	Value	Description
point	10.768897,106.678505	`Point 0`, format in `lat,lng`
point	10.765496,106.67626	`Point 1`, format in `lat,lng`
point	10.7627936,106.6750729	`Point 2`, format in `lat,lng`
point	10.7616745,106.6792429	`Point 3`, format in `lat,lng`
point	10.765605,106.685383	`Point 4`, format in `lat,lng`
point	10.766843,106.674029	`Point 5`, format in `lat,lng`
sources	0;1	Chỉ số của điểm đi. In this example, API will receive `Point 0` and `Point 1` as source points
destinations	2;3;4;5	Chỉ số của điểm đến. In this example, API will receive `Point 2`, `Point 3`, `Point 4` and `Point 5` as the destination points

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¶

Field	Type	Value	Description
code	string	`'OK'`	Mã trạng thái của phản hồ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 thời gian di chuyển, tính bằng giây.
distances	array	`[[1766.3, 1374.3, 1952.2, 1113.5], [507.5, 1152.4, 2101.8, 399.4]]`	Mảng quãng đường, tính bằng mét.