Skip to content

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

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
vehicle number no 1
  • = 1 (Applicable to passenger cars: seats < 12; trucks: gross tonnage <2 tons)
  • = 2 (Applicable to passenger cars: seats <= 30; trucks: gross tonnage < 4 tons)
  • = 3 (Applicable to passenger cars: seats > 31; trucks: total tonnage < 10 tons; tractors: not towing containers)
  • = 4 (Applicable to trucks: gross tonnage < 18 tons; tractor trucks: containers <= 20 feet);
  • = 5 (Applicable to trucks: gross tonnage >= 18 tons; tractors: containers > 20 feet)

Body (Content-Type: application/json): array of [longitude, latitude] pairs in time order — longitude first, the opposite of Route v4 point.

matchingtolls

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
    ]
]
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
    ]
]'
// 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);
import requests

body = [
    [106.757849, 10.817956],
    [106.759134, 10.821371],
    [106.760694, 10.825196]
]
resp = requests.post("https://maps.vietmap.vn/api/match-tolls?apikey=YOUR_API_KEY&vehicle=4", json=body, timeout=30)
resp.raise_for_status()
print(resp.json())
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

Hotline
Tổng đài hỗ trợ
089.616.4567
Messenger Chat Facebook zalo Chat Zalo