# Map matching API — Vietmap API Playground

> Clean GPS data according to actual road data with map data. Ideal solution for monitoring applications, order tracking, or user management.

The Map Matching API (match-tolls) snaps a GPS trace — usually noisy and sparse — onto the roads actually driven, and reports the toll stations passed with their fees for the vehicle class (1 to 5). The trace is sent in the JSON body as coordinates in time order, as [longitude, latitude].

What it is for:
- Reconciling toll costs for a fleet.
- Redrawing real journeys from tracker data.
- Measuring distance driven more accurately than joining GPS points.
- Spotting vehicles that left their assigned route.

- Interactive page: https://tools.vietmap.vn/playground/en/map-matching
- Endpoint: `POST /api/match-tolls` on `https://maps.vietmap.vn`
- Official documentation: https://maps.vietmap.vn/docs/map-api/match-tolls/
- API key: every request needs the `apikey` parameter. Samples use `YOUR_API_KEY` as the placeholder — when integrating, read the key from an environment variable (e.g. `VIETMAP_API_KEY`). Get a key at https://maps.vietmap.vn/console-v2/consumers
- Error codes: `401` wrong API key · `403` key restricted to another domain/IP · `423` API not enabled for the key's consumer, or out of credit (body contains "exceeded credit") · `429` rate limit exceeded.

## Code samples

### cURL

```bash
curl -X POST 'https://maps.vietmap.vn/api/match-tolls?apikey=YOUR_API_KEY&vehicle=1' \
  -H 'Content-Type: application/json' \
  -d '[
  [
    106.6538842265694,
    10.76272759672899
  ],
  [
    106.65327405390536,
    10.762410814059304
  ],
  [
    106.65270927200363,
    10.762785866195022
  ],
  [
    106.652236,
    10.763346
  ],
  [
    106.65184,
    10.763564
  ],
  [
    106.651296,
    10.763603
  ],
  [
    106.651313,
    10.76329
  ],
  [
    106.651281,
    10.7628
  ],
  [
    106.650694,
    10.762969
  ],
  [
    106.6498,
    10.763475
  ],
  [
    106.649074,
    10.763686
  ],
  [
    106.648454,
    10.764128
  ],
  [
    106.64823,
    10.764644
  ],
  [
    106.647774,
    10.764902
  ],
  [
    106.647289,
    10.76501
  ],
  [
    106.64681,
    10.765064
  ],
  [
    106.64627,
    10.765323
  ],
  [
    106.645936,
    10.765663
  ],
  [
    106.645447,
    10.765917
  ],
  [
    106.644988,
    10.766128
  ],
  [
    106.644608,
    10.766234
  ],
  [
    106.644225,
    10.766287
  ]
]'
```

### JavaScript

```javascript
// In production, read the key from an environment variable instead.
const API_KEY = "YOUR_API_KEY";

const params = new URLSearchParams([
  ["apikey", API_KEY],
  ["vehicle", "1"],
]);

const body = [
  [
    106.6538842265694,
    10.76272759672899
  ],
  [
    106.65327405390536,
    10.762410814059304
  ],
  [
    106.65270927200363,
    10.762785866195022
  ],
  [
    106.652236,
    10.763346
  ],
  [
    106.65184,
    10.763564
  ],
  [
    106.651296,
    10.763603
  ],
  [
    106.651313,
    10.76329
  ],
  [
    106.651281,
    10.7628
  ],
  [
    106.650694,
    10.762969
  ],
  [
    106.6498,
    10.763475
  ],
  [
    106.649074,
    10.763686
  ],
  [
    106.648454,
    10.764128
  ],
  [
    106.64823,
    10.764644
  ],
  [
    106.647774,
    10.764902
  ],
  [
    106.647289,
    10.76501
  ],
  [
    106.64681,
    10.765064
  ],
  [
    106.64627,
    10.765323
  ],
  [
    106.645936,
    10.765663
  ],
  [
    106.645447,
    10.765917
  ],
  [
    106.644988,
    10.766128
  ],
  [
    106.644608,
    10.766234
  ],
  [
    106.644225,
    10.766287
  ]
];

const response = await fetch(`https://maps.vietmap.vn/api/match-tolls?${params}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
});
if (!response.ok) {
  throw new Error(`Vietmap ${response.status}: ${await response.text()}`);
}
const data = await response.json();
console.log(data);
```

### Python

```python
import requests

# In production, read the key from an environment variable instead.
API_KEY = "YOUR_API_KEY"

params = [
    ("apikey", API_KEY),
    ("vehicle", "1"),
]

body = [
    [
        106.6538842265694,
        10.76272759672899,
    ],
    [
        106.65327405390536,
        10.762410814059304,
    ],
    [
        106.65270927200363,
        10.762785866195022,
    ],
    [
        106.652236,
        10.763346,
    ],
    [
        106.65184,
        10.763564,
    ],
    [
        106.651296,
        10.763603,
    ],
    [
        106.651313,
        10.76329,
    ],
    [
        106.651281,
        10.7628,
    ],
    [
        106.650694,
        10.762969,
    ],
    [
        106.6498,
        10.763475,
    ],
    [
        106.649074,
        10.763686,
    ],
    [
        106.648454,
        10.764128,
    ],
    [
        106.64823,
        10.764644,
    ],
    [
        106.647774,
        10.764902,
    ],
    [
        106.647289,
        10.76501,
    ],
    [
        106.64681,
        10.765064,
    ],
    [
        106.64627,
        10.765323,
    ],
    [
        106.645936,
        10.765663,
    ],
    [
        106.645447,
        10.765917,
    ],
    [
        106.644988,
        10.766128,
    ],
    [
        106.644608,
        10.766234,
    ],
    [
        106.644225,
        10.766287,
    ],
]

response = requests.post("https://maps.vietmap.vn/api/match-tolls", params=params, json=body, timeout=60)
response.raise_for_status()
print(response.json())
```

## AI prompt

A ready-made prompt for a coding assistant (ChatGPT, Claude, Copilot…) to write the integration:

````text
I need to integrate Vietmap's Map Matching (match-tolls) API into my application.

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

Here is a sample request that works in the Vietmap API Playground:

POST https://maps.vietmap.vn/api/match-tolls?apikey=YOUR_API_KEY&vehicle=1

Body (JSON):
```json
[
  [
    106.6538842265694,
    10.76272759672899
  ],
  [
    106.65327405390536,
    10.762410814059304
  ],
  [
    106.65270927200363,
    10.762785866195022
  ],
  [
    106.652236,
    10.763346
  ],
  [
    106.65184,
    10.763564
  ],
  [
    106.651296,
    10.763603
  ],
  [
    106.651313,
    10.76329
  ],
  [
    106.651281,
    10.7628
  ],
  [
    106.650694,
    10.762969
  ],
  [
    106.6498,
    10.763475
  ],
  [
    106.649074,
    10.763686
  ],
  [
    106.648454,
    10.764128
  ],
  [
    106.64823,
    10.764644
  ],
  [
    106.647774,
    10.764902
  ],
  [
    106.647289,
    10.76501
  ],
  [
    106.64681,
    10.765064
  ],
  [
    106.64627,
    10.765323
  ],
  [
    106.645936,
    10.765663
  ],
  [
    106.645447,
    10.765917
  ],
  [
    106.644988,
    10.766128
  ],
  [
    106.644608,
    10.766234
  ],
  [
    106.644225,
    10.766287
  ]
]
```

Parameters in use:
- vehicle = 1

Write code in [my language / framework] that calls this API, with these requirements:
1. Read the API key from the VIETMAP_API_KEY environment variable; never hard-code it.
2. Send the parameters in the query string exactly as in the sample; repeated parameters (such as `point`) must keep their order.
3. Handle Vietmap's HTTP errors:
   - 401: the API key is wrong or revoked.
   - 403: the key is restricted to a domain / IP that does not match.
   - 423: the API is not enabled for the key's consumer, OR the account is out of credit — tell them apart by the response body ("exceeded credit" means out of credit).
   - 429: rate limit exceeded — retry with increasing backoff.
4. Set a request timeout, and define types (type / interface / dataclass) for the response.

If unsure about a field name, look it up in the documentation linked above instead of guessing.
````

## Reopen this exact request in the Playground

https://tools.vietmap.vn/playground/en/map-matching?point=10.76272759672899,106.6538842265694&point=10.762410814059304,106.65327405390536&point=10.762785866195022,106.65270927200363&point=10.763346,106.652236&point=10.763564,106.65184&point=10.763603,106.651296&point=10.76329,106.651313&point=10.7628,106.651281&point=10.762969,106.650694&point=10.763475,106.6498&point=10.763686,106.649074&point=10.764128,106.648454&point=10.764644,106.64823&point=10.764902,106.647774&point=10.76501,106.647289&point=10.765064,106.64681&point=10.765323,106.64627&point=10.765663,106.645936&point=10.765917,106.645447&point=10.766128,106.644988&point=10.766234,106.644608&point=10.766287,106.644225&vehicle=1