Map Matching API¶
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.
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.
Try it in the Playground
Call Map Matching with real data, no code required: Open Playground
AI Agent Integration NEW
Download the optimized doc for AI agent integration: Routing Agent Doc · Machine-readable schema: OpenAPI 3.1
Or try it in Postman.
URL¶
Method¶
POST
Parameters¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| apikey | array string | yes | none | API key provided by VIETMAP for your account. Register here |
| vehicle | number | no | 1 |
|
Body (Content-Type: application/json): array of [longitude, latitude] pairs in time order — longitude first, the opposite of Route v4 point.
Example
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
]
]
// Node.js 18+. Call from your server so the API key stays private.
const body = [
[106.757849, 10.817956],
[106.759134, 10.821371],
[106.760694, 10.825196]
];
const res = await fetch("https://maps.vietmap.vn/api/match-tolls?apikey=YOUR_API_KEY&vehicle=4", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
const data = await res.json();
console.log(data);
Integrate the VIETMAP Match-tolls (Map Matching) API into my project.
Sample request (from the example in the docs):
POST https://maps.vietmap.vn/api/match-tolls?vehicle=4
Body (JSON): [[106.757849,10.817956],[106.759134,10.821371],[106.760694,10.825196]]
Requirements:
- Call the API from the server. Read the API key from the VIETMAP_API_KEY environment variable and send it as `apikey`; never hard-code it.
- Write one function that sends this request, checks the HTTP status and returns the parsed response.
- Read the docs below first. Use only parameters and response fields documented there.
Docs:
- https://maps.vietmap.vn/docs/map-api/match-tolls/index.txt
- https://maps.vietmap.vn/docs/assets/agents/routing.txt
Run this example on the Playground
JSON Output¶
{
"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) |
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
Related APIs¶
- Toll costs for trucks and containers — per-station tolls with Route v4.
- Route v4 — the route and toll cost before the trip.
- Geofencing — check positions from the same GPS feed against your zones.
- VRP — plan which vehicle takes which stops.
