# Map Matching

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

Map Matching API
=======
<video controls autoplay muted loop playsinline preload="metadata">
<source src="/docs/assets/MatchingEng.mp4" type="video/mp4">
</video>
* * *

!!! info "Match vs Route"
    Match snaps a GPS trace a vehicle **has already driven** onto the road network — use it for trip reconstruction, mileage and toll reconciliation. For a route **to be driven** (including truck and container, with `toll_cost`), use [Route v4](https://maps.vietmap.vn/docs/map-api/route-version/route-v4/).


POST a JSON array of `[longitude, latitude]` points recorded from a phone or vehicle tracker. The API snaps them to the road network and returns the matched route, its length, and the toll stations along it priced for the given `vehicle` class.

!!! tip "Try it in the Playground"
    Call Map Matching with real data, no code required: **[Open Playground](https://tools.vietmap.vn/playground/map-matching)**

!!! tip "AI Agent Integration :sparkles: NEW"
    Download the optimized doc for AI agent integration: **<a href="/docs/assets/agents/routing.txt" download="routing.txt">Routing Agent Doc</a>** · Machine-readable schema: **[OpenAPI 3.1](/docs/openapi.json)**

Or try it in [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**

Parameters
----------

|Parameter|Type|Required|Default|Description|
|--- |--- |--- |--- |--- |
|apikey|array string|yes|none|API key provided by VIETMAP for your account. [Register here](https://maps.vietmap.vn/console-v2/register)|
|vehicle|number|no|1|<ul><li>= **1**  (Applicable to passenger cars: seats < `12`; trucks: gross tonnage <` 2 tons`) </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`): array of `[longitude, latitude]` pairs in time order — **longitude first**, the opposite of Route v4 `point`.

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

**Example**



```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: Run this example on the 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 }

JSON Output
-----------

```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
        ]
    ],
}
```
### Response description
| Parameter | Type   | Description                                           |
| --------- | ------ | ----------------------------------------------------- |
| path      | array  | Array containing coordinate pairs along the route    |
| distance  | float  | Total distance of the route (in kilometers)          |
| tolls     | array  | Array containing toll booth information along the route |

For the `path` array:

| Sub-Parameter | Type    | Description                                |
| ------------- | ------- | ------------------------------------------ |
| [longitude, latitude] | array of floats | Coordinate pair representing a point on the route |

For the `tolls` array:

| Sub-Parameter | Type    | Description                                     |
| ------------- | ------- | ----------------------------------------------- |
| id            | integer | Unique identifier for the toll booth            |
| name          | string  | Name of the toll booth                          |
| address       | string  | Address of the toll booth                       |
| type          | string  | Type of toll booth (entry, exit, etc.)          |
| price         | integer | Toll price in local currency                    |
| prices        | null    | Additional price information (if available)     |
    

!!! tip "Try it with your own data"
    Enter your own addresses, coordinates or parameters and see the result on a map, with a cURL command to copy: **[Open Map Matching on the Playground](https://tools.vietmap.vn/playground/map-matching)**