Vietmap Map matching API Playground

    Map matching API

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

    Code samples

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

    Replace YOUR_API_KEY with your API key before running.

    // 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);

    Replace YOUR_API_KEY with your API key before running.

    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())

    Replace YOUR_API_KEY with your API key before running.

    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.

    Paste into ChatGPT, Claude… to generate integration code. The prompt never contains your API key.

    Open in ChatGPTOpen in Claude
    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

    Opens the playground with exactly these parameters — for the docs or a colleague. The link never contains an API key.

    API Response

    Enter information and click send request to see results

    What is the Map Matching API?

    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.

    Sample request

    POST https://maps.vietmap.vn/api/match-tolls?apikey=YOUR_API_KEY&vehicle=1
body: [[106.65388, 10.76272], [106.65327, 10.76241], [106.65270, 10.76278]]

    Mind the [longitude, latitude] order — the reverse of Route’s point.

    Map Matching API FAQ

    What is map matching?
    Map matching (snap to road) fits a GPS trace — usually offset, jumpy or sparse — onto the roads the vehicle actually used. The result is a clean journey that follows the road network, for redrawing the trip and measuring distance accurately.
    How does the API work out toll fees?
    From the matched journey, match-tolls returns the toll stations passed and the fee at each for the vehicle class, 1 to 5, set with the vehicle parameter.
    What format does the GPS data use?
    The JSON body is an array of coordinates in time order, each as [longitude, latitude] — the reverse of the Route API’s point parameter.
    Does it cost anything to try the Map Matching API?
    The playground comes with a demo API key, so you can call the Map Matching API straight from the browser without signing up. To build it into a product, register a VIETMAP account for your own key. Usage is billed per transaction, each API converting requests to transactions at its own rate; the pricing page has the details and the free trial.