# Matrix (Ma trận)

Source: https://maps.vietmap.vn/docs/vi/map-api/matrix-version/matrix-v4/

Matrix — Ma trận khoảng cách
======
<video controls autoplay muted loop playsinline preload="metadata">
<source src="/docs/assets/matrix(16x9).mp4" type="video/mp4">
</video>
* * *

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](https://maps.vietmap.vn/docs/vi/map-api/tsp-version/tsp-v4/); chia điểm cho nhiều xe thì dùng [VRP](https://maps.vietmap.vn/docs/vi/map-api/vrp/).

### Playground
!!! tip "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](https://tools.vietmap.vn/playground/matrix)**

!!! tip "Tích hợp AI Agent :sparkles: MỚI"
    Tải bộ tài liệu đã tối ưu cho AI agent (Matrix + TSP + VRP): **<a href="/docs/assets/agents/logistics.txt" download="logistics.txt">Logistics Agent Doc</a>** · Schema máy đọc: **[OpenAPI 3.1](/docs/openapi.json)**

Hoặc dùng thử bằng [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).

### 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](https://maps.vietmap.vn/docs/vi/map-api/route-version/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ợ)](https://maps.vietmap.vn/docs/vi/map-api/matrix/).

## 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](https://maps.vietmap.vn/console-v2/register)|
|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.</br> **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`.</br> 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ố)
```url
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
```

[:material-play-circle: Chạy ví dụ này trên Playground](https://tools.vietmap.vn/playground/matrix?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){ .md-button .md-button--primary }

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
```json
{
    "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](#cac-ma-trang-thai)      |
| 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. ![Bố cục hàng/cột của ma trận durations](https://maps.vietmap.vn/docs/assets/duration_description.png)  |
| 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. ![Bố cục hàng/cột của ma trận distances](https://maps.vietmap.vn/docs/assets/distance_descrition.png)          |

### 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.
 

!!! tip "Gọi thử với dữ liệu của bạn"
    Nhập địa chỉ, toạ độ hoặc tham số của bạn và xem kết quả ngay trên bản đồ, kèm lệnh cURL để sao chép: **[Mở Matrix v4 trên Playground](https://tools.vietmap.vn/playground/matrix)**