Source: https://maps.vietmap.vn/docs/map-api/overview/

# VIETMAP Maps API — address search, routing and fleet optimization

![Map Api Overview](https://maps.vietmap.vn/docs/assets/banner.png)

VIETMAP has 20 years of experience in GIS and transportation. Its digital map data covers traffic, rivers, and administrative boundaries throughout the country, and is updated weekly. Alongside the map data, VIETMAP also provides the VIETMAP Map APIs:

[VIETMAP Autocomplete](https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-v4/) -
[VIETMAP Geocoder](https://maps.vietmap.vn/docs/map-api/geocode-version/geocode-v4/) - 
[VIETMAP Routing](https://maps.vietmap.vn/docs/map-api/route-version/route-v4/) -
[VIETMAP Tilemap](https://maps.vietmap.vn/docs/map-api/tilemap/)

The VIETMAP [Routing API](https://maps.vietmap.vn/docs/map-api/route-version/route-v4/) supports multiple vehicle profiles — **car**, **motorcycle**, and now **truck** and **container** — so routes respect vehicle-specific rules such as weight limits (`capacity`) and restricted roads. Add `annotations=toll` to also return the **total toll cost** (`toll_cost`) and a **per-station breakdown** (`tolls`) for the requested vehicle — ideal for logistics use cases such as trip cost estimation and customer price quoting.

As Vietnam merges its provinces and cities, VIETMAP's Address Migration APIs let your search accept **either old or new addresses** as input and return **both formats** in a single response. They also **convert old addresses to the new administrative format**, so you can migrate an existing database to the new boundaries in bulk — keeping your app working throughout the transition.

[**Address Migration API Docs**](https://maps.vietmap.vn/docs/migrate-address/migrate-address/)

For businesses that need to show their **store or branch network** on a map, [Branch Locator & Management](https://maps.vietmap.vn/docs/map-api/local-store/overview/) is a no-code platform to manage all your locations and embed the map into any website. Each data layer is also served as an **MVT (vector tile) endpoint**: instead of the traditional approach — fetching one large GeoJSON file and rendering every marker manually, which downloads the entire dataset, blocks rendering, and can freeze or crash the browser once you reach thousands of points — the map only fetches the tiles covering the current viewport, so **10,000+ locations render smoothly** and your raw dataset is never exposed to the client.

## Map data coverage

VIETMAP builds and maintains its own nationwide map data for Vietnam — developed since 2006 and refreshed weekly. The dataset covers all **34 provinces** down to the village / hamlet level and powers every API above:

| Data | Coverage | What it covers |
| --- | --- | --- |
| **Roads & network** (đường bộ) | **600,000+ km** | Nationwide road network, one-way streets, turn restrictions, and vehicle-specific access for car, motorcycle, **truck** and **container**. |
| **Places / POIs** (địa điểm) | **9,362,472+** | Points of interest with names, categories, and entry points. |
| **Addresses** (địa chỉ) | **18,168,574+** | High-precision addresses down to house number and alley, in both **old and new** administrative formats. |
| **Traffic signs** (biển báo) | **200,000+** | Traffic signs, speed limits, and speed-camera locations — surfaced through routing and navigation. |
| **Administrative boundaries** | **34 provinces** | Wards and provinces, kept in sync with the 2025 provincial merger. |

## What you can build with VIETMAP Map API

Common use cases and the API that powers each one:

| You need to… | Use | Try it |
| --- | --- | --- |
| Add **address search / autocomplete** with suggestions as the user types | [Autocomplete](https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-v4/) | [Playground](https://tools.vietmap.vn/playground/autocomplete) |
| **Geocode** an address into coordinates (address text → lat/lng) | [Geocoder](https://maps.vietmap.vn/docs/map-api/geocode-version/geocode-v4/) | [Playground](https://tools.vietmap.vn/playground/geocode) |
| **Reverse geocode** coordinates into an address (lat/lng → address text) | [Reverse](https://maps.vietmap.vn/docs/map-api/reverse-version/reverse-v4/) | [Playground](https://tools.vietmap.vn/playground/reverse) |
| Get **driving directions & routing** for car, motorcycle, **truck** and **container**, including **toll cost** calculation | [Routing](https://maps.vietmap.vn/docs/map-api/route-version/route-v4/) | [Playground](https://tools.vietmap.vn/playground/route) |
| Build a **distance / travel-time matrix** for many origins and destinations | [Matrix](https://maps.vietmap.vn/docs/map-api/matrix-version/matrix-v4/) | [Playground](https://tools.vietmap.vn/playground/matrix) |
| **Optimize delivery routes** — shortest single tour (TSP) or a full **vehicle routing problem (VRP)** fleet plan | [TSP](https://maps.vietmap.vn/docs/map-api/tsp-version/tsp-v4/) · [VRP](https://maps.vietmap.vn/docs/map-api/vrp/) | [TSP](https://tools.vietmap.vn/playground/tsp) · [VRP](https://tools.vietmap.vn/playground/vrp) |
| Get **place details** by `ref_id` — name, full address, coordinates, entry points | [Place](https://maps.vietmap.vn/docs/map-api/place-v4/) | [Playground](https://tools.vietmap.vn/playground/autocomplete) |
| Compute **reachable areas** within a given travel time (**isochrone**) | [Isochrone](https://maps.vietmap.vn/docs/map-api/isochrone/) | — |
| Create **virtual boundaries** and detect when devices enter or exit them (**geofencing**) | [Geofencing](https://maps.vietmap.vn/docs/map-api/geofencing/) | — |
| Render fast, interactive **vector / tile maps** | [Tilemap](https://maps.vietmap.vn/docs/map-api/tilemap/) | [Map Editor](https://tools.vietmap.vn/map-editor/) |
| Generate **static map images** for emails, reports, or link previews | [Static Map](https://maps.vietmap.vn/docs/map-api/static-map-version/static-map/) | — |
| Show your **store / branch network** on a map — render **large datasets (10k+ points)** via MVT tiles without crashing the browser | [Branch Locator](https://maps.vietmap.vn/docs/map-api/local-store/overview/) | — |
| Handle Vietnam's **administrative merger** — search and convert **old ↔ new addresses** | [Address Migration](https://maps.vietmap.vn/docs/migrate-address/migrate-address/) | [Playground](https://tools.vietmap.vn/playground/migrate-address) |

## Quotas & cost

**60,000 free transactions — around 3,000,000 ₫ of usage.** No credit card required.

One request is not always one transaction:

| What you call | What it costs |
| --- | --- |
| Address search, geocode, reverse, place, isochrone | 1 transaction |
| Routing | ⌊stops / 5⌋ + 1 |
| Matrix of n origins × m destinations | n × m |
| Single-vehicle tour over m stops (TSP) | m |
| Fleet plan for n vehicles over m stops (VRP) | n × m |
| Base map tiles | 25 tiles = 1 transaction |

[How billing works](https://maps.vietmap.vn/docs/map-api/console/request-to-transaction/) ·
[Convert a budget into transactions](https://maps.vietmap.vn/docs/map-api/console/pricing-converter/) ·
[Per-plan limits](https://maps.vietmap.vn/docs/map-api/console/usage-limitation/) ·
[Pricing plans](https://maps.vietmap.vn/console-v2/payments)

## API Playground

VietMap provides an API playground for developers to test and explore the capabilities of our APIs. You can access the playground at [https://tools.vietmap.vn/playground](https://tools.vietmap.vn/playground).

Every API in the playground is also available as a **Postman collection** — 14 requests with parameters and sample data already filled in. Fork it into your workspace, set `apikey`, and you are ready to send:

[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork)

Or browse the [full collection on Postman](https://www.postman.com/orange-escape-494916/workspace/vietmap-api-collection).

Need a machine-readable schema — for ChatGPT Actions, Cursor, or client generation? Fetch the [OpenAPI 3.1 spec](https://maps.vietmap.vn/docs/openapi.yaml) (also as [JSON](https://maps.vietmap.vn/docs/openapi.json)) — it covers 12 endpoints: search, geocoding, reverse, address migration, routing, map matching, matrix, TSP, static map, styles and tiles. VRP, Isochrone and Geofencing are not in the spec yet — try [VRP on the Playground](https://tools.vietmap.vn/playground/vrp); for the others, [message support on Zalo](https://zalo.me/3189066936017422854).

## Live map demo
You can try our Live Map demo at [https://tools.vietmap.vn/live](https://tools.vietmap.vn/live). This demo showcases the features and functionalities of our mapping services—such as search, routing, and tile maps—allowing you to experience the capabilities of VIETMAP’s APIs in a real-world scenario.
## Customize the map
[Map Editor](https://tools.vietmap.vn/map-editor/) changes the colors, place icons, labels and language of VIETMAP maps in the browser; you then embed the map on your website or use it in your app. See the [Map Editor guide](https://maps.vietmap.vn/docs/map-api/map-editor/).

## API Key Contact information
- Register an API Key: [here](https://maps.vietmap.vn/docs/map-api/console/register-api-key/)
- Zalo OA: [Vietmap Solutions](https://zalo.me/3189066936017422854)
- Email: [maps.info@vietmap.vn](mailto:maps.info@vietmap.vn)
- More information: https://maps.vietmap.vn

## API Format Common

Most Map APIs are `GET`, return JSON, and authenticate with an `apikey` query parameter:

```
https://maps.vietmap.vn/api/autocomplete/v4?apikey={your-apikey}&text=197 tran phu
```

| Part | Value |
| --- | --- |
| scheme + domain | `https://maps.vietmap.vn` |
| path | `/api/autocomplete/v4` |
| api key | `apikey={your-apikey}` |
| parameter | `text=197 tran phu` |

Some APIs use `POST` because they take larger input — Map Matching, VRP, Geofencing and the batch APIs. Static Map is a further exception: it sends parameters as `multipart/form-data` and returns an image rather than JSON. Version numbers are not in one fixed place either: most sit in the path (`/v4`), a few are passed as an `api-version` parameter. Check the URL on each API's own page.

## Backend Integration Guide for Secure API Communication

### 1. Overview

For **security** and **access control** reasons, we strongly recommend that you integrate with our API **via your backend server**, rather than making direct calls from your client-side applications (web or mobile). This approach protects your **API Key** and other sensitive credentials from being exposed and minimizes the risk of unauthorized access.

---

### 2. Recommended Architecture

```
Client (Web / Mobile App)
        |
        | HTTPS/Authorization/Encryption
        v
Your Backend Server
        |
        | HTTPS
        v
Our API Server
```

---

### 3. Integration Steps

#### Step 1: Your Backend Sends Requests to Our API Server
- Your backend server should handle user authentication (if applicable), if not, consider to integrate some encryption method between your client and server (nonce, aes, rsa,...). Then send requests to our API server on behalf of your client.
- Your **service key** or **Authentication Token** must be securely stored and only used on your backend. **Never expose it on the client side.** The **tilemap key** is the exception — it is meant to be embedded in client-side code, so restrict it by domain in the Console.

#### Step 2: Return the Response to Your Client
- Once your backend receives the API response, return the processed result to your client application in the format you need.
- You may implement caching or response filtering as appropriate.

---

### 4. Security Best Practices
- **Never expose your service key or tokens on the frontend** (browser, mobile app, etc.).
- Implement **rate limiting** and **input validation** on your backend to protect your system.
- Ensure all communications between client ↔ backend and backend ↔ our API are secured via **HTTPS**. If possible, please integrate SSL pinning on your mobile app.

---

### 5. Disclaimer

⚠️ **Disclaimer:**  
In the event of any API Key exposure or unauthorized access, you must immediately notify Vietmap so that we can work with you to assess the situation and take appropriate action. Please note that it is your responsibility to implement proper security measures on your backend to protect your API Key and credentials. Vietmap is not liable for any damages or losses resulting from improper handling or exposure of your API credentials.

---