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

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.

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:

    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
        ]
    ]'

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)