# Map Matching (bám vệt GPS)

Source: https://maps.vietmap.vn/docs/vi/map-api/match-tolls/

Map Matching API — bám vệt GPS vào đường thật
=======
<video controls autoplay muted loop playsinline preload="metadata">
<source src="/docs/assets/MatchingEng.mp4" type="video/mp4">
</video>
* * *

!!! info "Match hay Route"
    Match bám vệt GPS xe **đã chạy** vào mạng lưới đường — dùng để tái dựng hành trình, đối soát km và phí cầu đường sau chuyến. Cần tuyến cho chuyến **sắp chạy** (kể cả xe tải, container, đã có sẵn `toll_cost`) thì dùng [Route v4](https://maps.vietmap.vn/docs/vi/map-api/route-version/route-v4/).


Gửi lên chuỗi tọa độ GPS thô (từ điện thoại hoặc thiết bị giám sát hành trình), API bám chúng vào mạng lưới đường và trả về tuyến xe đã đi thật, quãng đường, cùng các trạm thu phí trên tuyến tính theo hạng `vehicle` đã gửi.

!!! tip "Thử ngay trên Playground"
    Gọi thử Map Matching với dữ liệu thật, không cần viết code: **[Mở Playground](https://tools.vietmap.vn/playground/map-matching)**

!!! tip "Tích hợp AI Agent :sparkles: MỚI"
    Tải bộ tài liệu đã tối ưu cho AI agent: **<a href="/docs/assets/agents/routing.txt" download="routing.txt">Routing 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
---
```swift
https://maps.vietmap.vn/api/match-tolls?api-version=1.1&apikey={your-apikey}&vehicle={vehicle}
```

Method
------
**POST**

Tham số
----------

|Tham số|Kiểu|Bắt buộc|Mặc định|Mô tả|
|--- |--- |--- |--- |--- |
|apikey|array 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)|
|vehicle|number|không|1|<ul><li>= **1**  (Áp dụng cho xe con dưới `12` chỗ; xe tải dưới `2 tấn`) </li> <li>= **2** (Applicable to passenger cars: `seats <= 30`; trucks: gross tonnage < `4 tons`) <li>= **3** (Applicable to passenger cars: `seats > 31`; trucks: total tonnage < `10 tons`; tractors: not towing containers) <li> = **4** (Applicable to trucks: gross tonnage < `18 tons`; tractor trucks: containers <= `20 feet`); <li> = **5** (Applicable to trucks: gross tonnage >= `18 tons`; tractors: containers > `20 feet`)</ul>

**Body** (`Content-Type: application/json`): mảng các cặp `[longitude, latitude]` theo thứ tự thời gian — **kinh độ trước**, ngược với `point` của Route v4.

[![matchingtolls]][matchingtolls]
[matchingtolls]: https://maps.vietmap.vn/docs/assets/matchingtolls.webp

**Ví dụ**



```javascript
URL:
https://maps.vietmap.vn/api/match-tolls?apikey=”your-apikey”&vehicle={vehicle}

body:
[
    [
        106.757849,
        10.817956
    ],
    [
        106.759134,
        10.821371
    ],
    [
        106.760694,
        10.825196
    ]
]
```
cURL:
```
    curl --location 'https://maps.vietmap.vn/api/match-tolls?apikey=YOUR_API_KEY_HERE&vehicle=4' \
    --header 'Content-Type: application/json' \
    --data '[
        [
            106.757849,
            10.817956
        ],
        [
            106.759134,
            10.821371
        ],
        [
            106.760694,
            10.825196
        ]
    ]'
```

[:material-play-circle: Chạy ví dụ này trên Playground](https://tools.vietmap.vn/playground/map-matching?point=10.817956,106.757849&point=10.821371,106.759134&point=10.825196,106.760694&vehicle=4){ .md-button .md-button--primary }

Phản hồi
-----------

```json
{
    "distance": 0.9228444301945045,
    "tolls": [
        {
            "id": 441,
            "name": "Trạm Thu Phí Xa Lộ Hà Nội",
            "address": "Xa Lộ Hà Nội",
            "type": "",
            "price": 108000,
            "prices": null
        }
    ],

    "path": [
        [
            106.75796704230189,
            10.817930472210803
        ],
        [
            106.75817,
            10.8188359
        ],
        [
            106.758363,
            10.8199419
        ],
        [
            106.758492,
            10.8201079
        ],
        [
            106.758639,
            10.8208459
        ],
        [
            106.75879776283638,
            10.821455484269388
        ],
        [
            106.758932,
            10.8219709
        ],
        [
            106.759162,
            10.8226259
        ],
        [
            106.7593279,
            10.823036
        ],
        [
            106.7591469,
            10.8230179
        ],
        [
            106.759248,
            10.8232789
        ],
        [
            106.7593799,
            10.8237109
        ],
        [
            106.759499,
            10.8239979
        ],
        [
            106.759692,
            10.824369
        ],
        [
            106.7598349,
            10.824291
        ],
        [
            106.760204,
            10.8249049
        ],
        [
            106.76043843313977,
            10.825331492152502
        ]
    ],
}
```
### Mô tả phản hồi
| Trường | Kiểu | Mô tả |
| --------- | ------ | ----------------------------------------------------- |
| path      | array  | Mảng các cặp tọa độ dọc theo tuyến    |
| distance  | float  | Tổng quãng đường của tuyến (tính bằng km)          |
| tolls     | array  | Mảng thông tin các trạm thu phí dọc tuyến |

Với mảng `path`:

| Trường con | Kiểu    | Mô tả                                |
| ------------- | ------- | ------------------------------------------ |
| [longitude, latitude] | number[] | Một điểm trên tuyến đã bám đường, **kinh độ trước** |

Với mảng `tolls`:

| Trường con | Kiểu    | Mô tả                                     |
| ------------- | ------- | ----------------------------------------------- |
| id            | integer | Mã định danh của trạm thu phí            |
| name          | string  | Tên trạm thu phí                          |
| address       | string  | Địa chỉ hoặc tuyến đường đặt trạm thu phí                       |
| type          | string  | Loại trạm thu phí (vào, ra, v.v.)          |
| price         | integer | Mức phí, tính bằng VNĐ                    |
| prices        | null    | Thông tin giá bổ sung (nếu 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ở Map Matching trên Playground](https://tools.vietmap.vn/playground/map-matching)**