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

# VIETMAP Maps API — tìm địa chỉ, chỉ đường và tối ưu vận tải

![Tổng quan Map API](https://maps.vietmap.vn/docs/assets/banner.png)

VIETMAP có 20 năm kinh nghiệm trong lĩnh vực GIS và giao thông. Dữ liệu bản đồ số Việt Nam của VIETMAP bao phủ giao thông, sông ngòi và ranh giới hành chính trên toàn quốc, được cập nhật hàng tuần. Trên nền dữ liệu đó, VIETMAP cung cấp bộ API bản đồ **VIETMAP Map API** cho web và ứng dụng di động:

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

[Routing API](https://maps.vietmap.vn/docs/vi/map-api/route-version/route-v4/) của VIETMAP hỗ trợ nhiều loại phương tiện — **ô tô**, **xe máy**, và nay có thêm **xe tải** và **container** — nên tuyến đường trả về tuân thủ các quy định riêng của từng loại xe như giới hạn tải trọng (`capacity`) và đường cấm. Thêm tham số `annotations=toll` để nhận thêm **tổng phí cầu đường** (`toll_cost`) và **chi tiết theo từng trạm** (`tolls`) cho đúng loại xe bạn chọn. Thông tin này rất hữu ích cho các bài toán logistics như ước tính chi phí chuyến đi hay báo giá cho khách hàng.

Việt Nam đang sáp nhập tỉnh, thành. Trong bối cảnh đó, bộ API Chuyển đổi địa chỉ của VIETMAP giúp chức năng tìm kiếm địa chỉ và geocoding trong hệ thống của bạn nhận vào cả **địa chỉ cũ lẫn địa chỉ mới**, rồi trả về **cả hai định dạng** trong cùng một phản hồi. Bộ API này cũng **chuyển đổi địa chỉ cũ sang định dạng hành chính mới**, giúp bạn chuyển đổi hàng loạt cơ sở dữ liệu hiện có sang đơn vị hành chính mới — ứng dụng của bạn vẫn hoạt động xuyên suốt giai đoạn chuyển tiếp.

[**Tài liệu API Chuyển đổi địa chỉ**](https://maps.vietmap.vn/docs/vi/migrate-address/migrate-address/)

Với các doanh nghiệp cần hiển thị **mạng lưới cửa hàng hoặc chi nhánh** trên bản đồ, [Quản lý & Tra cứu chi nhánh](https://maps.vietmap.vn/docs/vi/map-api/local-store/overview/) là nền tảng no-code giúp quản lý toàn bộ địa điểm và nhúng bản đồ vào bất kỳ website nào. Mỗi lớp dữ liệu cũng được phục vụ dưới dạng **endpoint MVT (vector tile)**. Cách làm truyền thống là tải về một file GeoJSON lớn rồi tự vẽ từng marker: toàn bộ dữ liệu phải tải xuống, quá trình render bị chặn, và tới hàng nghìn điểm là trình duyệt có thể treo hoặc sập. Với MVT, bản đồ chỉ tải các tile thuộc vùng đang xem — **hơn 10.000 địa điểm vẫn hiển thị mượt** và dữ liệu gốc không bao giờ lộ ra phía client.

## Độ phủ dữ liệu bản đồ

VIETMAP tự xây dựng và duy trì dữ liệu bản đồ số toàn quốc cho Việt Nam — phát triển từ năm 2006 và làm mới hàng tuần. Bộ dữ liệu phủ toàn bộ **34 tỉnh thành** đến cấp thôn/ấp và là nền tảng cho tất cả các API nêu trên:

| Dữ liệu | Độ phủ | Nội dung |
| --- | --- | --- |
| **Đường bộ & mạng lưới** | **600.000+ km** | Mạng lưới đường bộ toàn quốc, đường một chiều, cấm rẽ, và quyền lưu thông riêng cho ô tô, xe máy, **xe tải** và **container**. |
| **Địa điểm / POI** | **9.362.472+** | Các địa điểm (POI) kèm tên, phân loại và lối vào. |
| **Địa chỉ** | **18.168.574+** | Địa chỉ độ chính xác cao đến số nhà và hẻm, ở **cả định dạng cũ và mới**. |
| **Biển báo giao thông** | **200.000+** | Biển báo, giới hạn tốc độ và vị trí camera tốc độ — dùng cho chỉ đường và dẫn đường. |
| **Ranh giới hành chính** | **34 tỉnh thành** | Phường/xã và tỉnh thành, luôn đồng bộ với đợt sáp nhập tỉnh năm 2025. |

## Bạn có thể xây dựng gì với VIETMAP Map API

Các bài toán thường gặp và API tương ứng:

| Bạn cần… | Dùng | Thử ngay |
| --- | --- | --- |
| Thêm **tìm kiếm / gợi ý địa chỉ** ngay khi người dùng gõ | [Autocomplete](https://maps.vietmap.vn/docs/vi/map-api/autocomplete-version/autocomplete-v4/) | [Playground](https://tools.vietmap.vn/playground/autocomplete) |
| **Geocode** địa chỉ thành tọa độ (văn bản địa chỉ → lat/lng) | [Geocoder](https://maps.vietmap.vn/docs/vi/map-api/geocode-version/geocode-v4/) | [Playground](https://tools.vietmap.vn/playground/geocode) |
| **Reverse geocode** tọa độ thành địa chỉ (lat/lng → văn bản địa chỉ) | [Reverse](https://maps.vietmap.vn/docs/vi/map-api/reverse-version/reverse-v4/) | [Playground](https://tools.vietmap.vn/playground/reverse) |
| Lấy **chỉ đường** cho ô tô, xe máy, **xe tải** và **container**, kèm tính **phí cầu đường** | [Routing](https://maps.vietmap.vn/docs/vi/map-api/route-version/route-v4/) | [Playground](https://tools.vietmap.vn/playground/route) |
| Xây **ma trận khoảng cách / thời gian di chuyển** cho nhiều điểm đi và điểm đến | [Matrix](https://maps.vietmap.vn/docs/vi/map-api/matrix-version/matrix-v4/) | [Playground](https://tools.vietmap.vn/playground/matrix) |
| **Tối ưu lộ trình giao hàng** — hành trình ngắn nhất cho một xe (TSP) hoặc kế hoạch cho cả đội xe (**VRP**) | [TSP](https://maps.vietmap.vn/docs/vi/map-api/tsp-version/tsp-v4/) · [VRP](https://maps.vietmap.vn/docs/vi/map-api/vrp/) | [TSP](https://tools.vietmap.vn/playground/tsp) · [VRP](https://tools.vietmap.vn/playground/vrp) |
| Lấy **chi tiết địa điểm** theo `ref_id` — tên, địa chỉ đầy đủ, tọa độ, điểm ra vào | [Place](https://maps.vietmap.vn/docs/vi/map-api/place-v4/) | [Playground](https://tools.vietmap.vn/playground/autocomplete) |
| Tính **vùng đi tới được** trong một khoảng thời gian di chuyển (**isochrone**) | [Isochrone](https://maps.vietmap.vn/docs/vi/map-api/isochrone/) | — |
| Tạo **hàng rào địa lý ảo** và phát hiện khi thiết bị ra/vào vùng đó (**geofencing**) | [Geofencing](https://maps.vietmap.vn/docs/vi/map-api/geofencing/) | — |
| Hiển thị **bản đồ vector / tile** tương tác, tốc độ cao | [Tilemap](https://maps.vietmap.vn/docs/vi/map-api/tilemap/) | [Map Editor](https://tools.vietmap.vn/map-editor/) |
| Tạo **ảnh bản đồ tĩnh** cho email, báo cáo hoặc link preview | [Static Map](https://maps.vietmap.vn/docs/vi/map-api/static-map-version/static-map/) | — |
| Hiển thị **mạng lưới cửa hàng / chi nhánh** trên bản đồ — render **tập dữ liệu lớn (hơn 10.000 điểm)** qua tile MVT mà không làm sập trình duyệt | [Branch Locator](https://maps.vietmap.vn/docs/vi/map-api/local-store/overview/) | — |
| Xử lý **sáp nhập đơn vị hành chính** tại Việt Nam — tìm kiếm và chuyển đổi **địa chỉ cũ ↔ mới** | [Address Migration](https://maps.vietmap.vn/docs/vi/migrate-address/migrate-address/) | [Playground](https://tools.vietmap.vn/playground/migrate-address) |

## Hạn mức & chi phí

**Miễn phí 60.000 transaction — tương đương khoảng 3.000.000đ.** Không cần thẻ tín dụng.

Một request không phải lúc nào cũng bằng một transaction:

| Gọi gì | Tốn bao nhiêu |
| --- | --- |
| Tìm địa chỉ, geocode, reverse, place, isochrone | 1 transaction |
| Chỉ đường | ⌊số điểm / 5⌋ + 1 |
| Ma trận n điểm đi × m điểm đến | n × m |
| Tối ưu lộ trình một xe qua m điểm (TSP) | m |
| Chia tuyến n xe qua m điểm (VRP) | n × m |
| Bản đồ nền | 25 tile = 1 transaction |

[Cách tính chi tiết](https://maps.vietmap.vn/docs/vi/map-api/console/request-to-transaction/) ·
[Quy đổi ngân sách ra transaction](https://maps.vietmap.vn/docs/vi/map-api/console/pricing-converter/) ·
[Giới hạn từng gói](https://maps.vietmap.vn/docs/vi/map-api/console/usage-limitation/) ·
[Các gói cước](https://maps.vietmap.vn/console-v2/payments)

## API Playground

VIETMAP có sẵn API playground để lập trình viên thử nghiệm và khám phá khả năng của các API bản đồ. Bạn có thể truy cập playground tại [https://tools.vietmap.vn/playground](https://tools.vietmap.vn/playground).

Toàn bộ API trong playground cũng có sẵn dưới dạng **Postman collection** — 14 request đã điền sẵn tham số và dữ liệu mẫu. Fork về workspace của bạn, điền `apikey` là chạy được ngay:

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

Hoặc xem [toàn bộ collection trên Postman](https://www.postman.com/orange-escape-494916/workspace/vietmap-api-collection).

Cần schema máy đọc được — cho ChatGPT Actions, Cursor, hay sinh client tự động? Tải [OpenAPI 3.1](https://maps.vietmap.vn/docs/openapi.yaml) (cũng có bản [JSON](https://maps.vietmap.vn/docs/openapi.json)) — phủ 12 endpoint: tìm địa chỉ, geocode, reverse, chuyển đổi địa chỉ, chỉ đường, map matching, ma trận, TSP, static map, style và tile bản đồ. VRP, Isochrone và Geofencing chưa có trong spec — thử [VRP trên Playground](https://tools.vietmap.vn/playground/vrp), còn lại [nhắn Zalo](https://zalo.me/3189066936017422854) cho đội hỗ trợ.

## Demo bản đồ trực tiếp
Bạn có thể dùng thử demo Live Map tại [https://tools.vietmap.vn/live](https://tools.vietmap.vn/live). Demo này giới thiệu các tính năng của dịch vụ bản đồ số — tìm kiếm địa chỉ, chỉ đường và bản đồ nền — giúp bạn trải nghiệm khả năng của các API VIETMAP trong tình huống thực tế.
## Tùy chỉnh bản đồ
[Map Editor](https://tools.vietmap.vn/map-editor/) dùng để đổi màu, icon địa điểm, chữ và ngôn ngữ của bản đồ VIETMAP trên trình duyệt, sau đó nhúng bản đồ vào website hoặc dùng trong app. Xem [hướng dẫn Map Editor](https://maps.vietmap.vn/docs/vi/map-api/map-editor/).

## Thông tin liên hệ & API Key
- Đăng ký API Key: [tại đây](https://maps.vietmap.vn/docs/vi/map-api/console/register-api-key/)
- Zalo OA: [Vietmap Solutions](https://zalo.me/3189066936017422854)
- Email: [maps.info@vietmap.vn](mailto:maps.info@vietmap.vn)
- Thông tin thêm: https://maps.vietmap.vn

## Định dạng chung của API

Hầu hết Map API là `GET`, trả về JSON và xác thực bằng tham số `apikey` trên query string:

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

| Thành phần | Giá trị |
| --- | --- |
| scheme + domain | `https://maps.vietmap.vn` |
| path | `/api/autocomplete/v4` |
| api key | `apikey={your-apikey}` |
| tham số | `text=197 tran phu` |

Một số API dùng `POST` vì nhận dữ liệu đầu vào lớn hơn — Map Matching, VRP, Geofencing và các API batch. Riêng Static Map gửi tham số dạng `multipart/form-data` và trả về ảnh thay vì JSON. Số phiên bản cũng không nằm cùng một chỗ ở mọi API: phần lớn đặt trong path (`/v4`), một số truyền qua tham số `api-version`. Bạn xem đúng URL ở trang của từng API.

## Hướng dẫn tích hợp phía backend để giao tiếp API an toàn

### 1. Tổng quan

Vì lý do **bảo mật** và **kiểm soát truy cập**, chúng tôi đặc biệt khuyến nghị bạn tích hợp API **thông qua máy chủ backend của mình**, thay vì gọi trực tiếp từ ứng dụng phía client (web hoặc mobile). Cách làm này bảo vệ **API Key** và các thông tin nhạy cảm khác khỏi bị lộ, đồng thời giảm thiểu rủi ro truy cập trái phép.

---

### 2. Kiến trúc khuyến nghị

```
Client (Ứng dụng Web / Mobile)
        |
        | HTTPS/Authorization/Encryption
        v
Máy chủ backend của bạn
        |
        | HTTPS
        v
Máy chủ API của chúng tôi
```

---

### 3. Các bước tích hợp

#### Bước 1: Backend của bạn gửi request đến máy chủ API của chúng tôi
- Backend của bạn nên xử lý xác thực người dùng (nếu có); nếu không, hãy cân nhắc áp dụng một phương thức mã hóa giữa client và server (nonce, aes, rsa,...). Sau đó gửi request đến máy chủ API của chúng tôi thay cho client.
- **Service key** hoặc **Authentication Token** phải được lưu trữ an toàn và chỉ dùng ở phía backend. **Tuyệt đối không để lộ ở phía client.** Riêng **tilemap key** được thiết kế để nhúng vào ứng dụng phía client — bạn nhớ khai báo tên miền được phép gọi trong Console.

#### Bước 2: Trả kết quả về cho client
- Khi backend nhận được phản hồi từ API, hãy trả kết quả đã xử lý về ứng dụng client theo định dạng bạn cần.
- Bạn có thể triển khai caching hoặc lọc bớt dữ liệu phản hồi nếu phù hợp.

---

### 4. Thực hành bảo mật tốt nhất
- **Không bao giờ để lộ service key hoặc Token ở phía frontend** (trình duyệt, ứng dụng di động, v.v.).
- Triển khai **giới hạn tần suất (rate limiting)** và **kiểm tra dữ liệu đầu vào** ở backend để bảo vệ hệ thống.
- Đảm bảo mọi giao tiếp giữa client ↔ backend và backend ↔ API của chúng tôi đều qua **HTTPS**. Nếu có thể, hãy tích hợp SSL pinning cho ứng dụng di động.

---

### 5. Miễn trừ trách nhiệm

⚠️ **Miễn trừ trách nhiệm:**  
Trong trường hợp API Key bị lộ hoặc có truy cập trái phép, bạn phải thông báo ngay cho VIETMAP để chúng tôi phối hợp đánh giá tình hình và xử lý phù hợp. Lưu ý rằng việc triển khai các biện pháp bảo mật đúng đắn ở backend để bảo vệ API Key và thông tin xác thực là trách nhiệm của bạn. VIETMAP không chịu trách nhiệm cho bất kỳ thiệt hại hoặc tổn thất nào phát sinh từ việc xử lý hoặc để lộ thông tin xác thực API không đúng cách.

---