# VIETMAP Maps API

> Map APIs for Vietnam, built on VIETMAP's own nationwide map data — 600,000+ km of roads, 18 million+ addresses, 9.3 million+ places, refreshed weekly. Address search that accepts both the pre-2025 and post-merger administrative formats, truck and container routing with per-station toll costs, distance matrix, TSP and VRP fleet optimization, and vector or raster base maps.

The API reference is bilingual: English at `/docs/` and Vietnamese at `/docs/vi/` — every URL below has a
Vietnamese twin under `/docs/vi/`, listed in the **Tiếng Việt** section. The mobile SDK guides, the Web SDK overview and the Web SDK examples are bilingual too; the generated SDK class reference is English only.

Every request authenticates with an `apikey` query parameter. Get a key at https://maps.vietmap.vn/console-v2/register — new accounts start with 60,000 free transactions, no credit card required, and the keys arrive by email immediately after verification. Most endpoints are GET and return JSON; Map Matching, VRP, Geofencing and Static Map use POST, and Static Map returns an image. Coordinates in query parameters are `lat,lng`; coordinates inside JSON bodies (Map Matching, VRP) are `[longitude, latitude]`. Error codes: `401` wrong key, `423` out of quota or API not enabled for this key.

Every documentation page is also served as plain-text Markdown: append `index.txt` to its URL, e.g. https://maps.vietmap.vn/docs/map-api/route-version/route-v4/index.txt

## Agent integration guides

Self-contained references written for LLM context windows. Each one covers a group of endpoints with parameters, request and response examples, and error handling — read one of these before the HTML reference.

- [Search & Geocoding](https://maps.vietmap.vn/docs/assets/agents/search-geocoding.txt): Autocomplete v4, Search (Geocode) v4, Place v4, Reverse v4 — old and new address formats via `display_type`
- [Routing](https://maps.vietmap.vn/docs/assets/agents/routing.txt): Route v4 for car, motorcycle, truck and container with toll costs; Map Matching for GPS traces
- [Logistics & Boundaries](https://maps.vietmap.vn/docs/assets/agents/logistics.txt): Matrix, TSP, VRP with capacity, time windows, skills and priority; Isochrone; Geofencing
- [Data Tools](https://maps.vietmap.vn/docs/assets/agents/data-tools.txt): Address Migration between old and new administrative units
- [Map Display](https://maps.vietmap.vn/docs/assets/agents/map-display.txt): Tilemap styles, Traffic layer, Web SDK (GL JS), Leaflet binding, mobile SDKs
- [Console, Keys & Pricing](https://maps.vietmap.vn/docs/assets/agents/console.txt): Registration, tilemap key vs services key, quotas, how requests convert into transactions

## API reference

- [Overview](https://maps.vietmap.vn/docs/map-api/overview/): What you can build, data coverage, quotas and cost, request format
- [Quickstart](https://maps.vietmap.vn/docs/map-api/quickstart/): Two keys, first call (Autocomplete v4 then Place v4), a map with a marker, production checklist
- [Error codes](https://maps.vietmap.vn/docs/map-api/errors/): HTTP statuses (401, 423, 429...), routing `code` values, a retry wrapper
- [Guide: delivery route planning](https://maps.vietmap.vn/docs/map-api/use-cases/delivery-routing-guide/): Geocode, VRP, Route v4, Geofencing and Map Matching chained, with coordinate order per API
- [Guide: address input at checkout](https://maps.vietmap.vn/docs/map-api/use-cases/checkout-address-guide/): Autocomplete v4, Place v4 and Reverse v4 behind your server, old and new address formats
- [Register and get API keys](https://maps.vietmap.vn/docs/map-api/console/register-api-key/): Step by step, including a first `curl` request and the error table
- [How requests convert into transactions](https://maps.vietmap.vn/docs/map-api/console/request-to-transaction/): Per-API billing formulas

### Search and addresses

- [Autocomplete v4](https://maps.vietmap.vn/docs/map-api/autocomplete-version/autocomplete-v4/): Suggestions while the user types; returns `ref_id` for Place v4
- [Geocode v4](https://maps.vietmap.vn/docs/map-api/geocode-version/geocode-v4/): Full address string to candidates
- [Place v4](https://maps.vietmap.vn/docs/map-api/place-v4/): `ref_id` to coordinates and address components
- [Reverse v4](https://maps.vietmap.vn/docs/map-api/reverse-version/reverse-v4/): Coordinates to the nearest address
- [Address Migration](https://maps.vietmap.vn/docs/migrate-address/migrate-address-docs/): Convert one address between old and new administrative units

### Routing and logistics

- [Route v4](https://maps.vietmap.vn/docs/map-api/route-version/route-v4/): Turn-by-turn route, vehicle profiles, `annotations=toll` for toll cost per station
- [Map Matching](https://maps.vietmap.vn/docs/map-api/match-tolls/): Snap a GPS trace to the road network and list tolls passed
- [Toll costs for trucks and containers](https://maps.vietmap.vn/docs/map-api/toll-cost/): Per-station toll costs with Route v4 and `annotations=toll`, with code samples
- [Matrix v4](https://maps.vietmap.vn/docs/map-api/matrix-version/matrix-v4/): Travel time or distance between n origins and m destinations
- [TSP v4](https://maps.vietmap.vn/docs/map-api/tsp-version/tsp-v4/): Optimal stop order for one vehicle
- [VRP](https://maps.vietmap.vn/docs/map-api/vrp/): Assign stops across a fleet with capacity, time windows, skills and priority

### Map display

- [Tilemap](https://maps.vietmap.vn/docs/map-api/tilemap/): Vector style URLs (street, light, dark, hybrid) and raster satellite tiles
- [Traffic layer](https://maps.vietmap.vn/docs/map-api/traffic-layer/): Real-time congestion as a vector style merged on top of the base map
- [Map Editor](https://maps.vietmap.vn/docs/map-api/map-editor/): Build a custom style in the browser — templates, per-layer colors, icon sets, labels — and get one Style URL for web and mobile
- [Leaflet integration](https://maps.vietmap.vn/docs/map-api/tilemap-leaflet/): `@vietmap/vietmap-gl-leaflet` for existing Leaflet projects
- [Static Map](https://maps.vietmap.vn/docs/map-api/static-map-version/static-map/): Rendered map images for emails and reports

## Tiếng Việt

Bản tiếng Việt của tài liệu API — cùng nội dung, cùng cấu trúc với bản tiếng Anh ở trên.

- [Tổng quan Map API](https://maps.vietmap.vn/docs/vi/map-api/overview/): Xây được gì, độ phủ dữ liệu, hạn mức và chi phí
- [Bắt đầu nhanh](https://maps.vietmap.vn/docs/vi/map-api/quickstart/): Hai loại key, lần gọi đầu tiên, bản đồ có marker, danh sách kiểm tra trước khi chạy thật
- [Mã lỗi](https://maps.vietmap.vn/docs/vi/map-api/errors/): Mã HTTP (401, 423, 429...), `code` của nhóm chỉ đường, hàm bọc gọi lại
- [Tích hợp lập tuyến giao hàng](https://maps.vietmap.vn/docs/vi/map-api/use-cases/delivery-routing-guide/): Ghép Geocode, VRP, Route v4, Geofencing, Map Matching; thứ tự toạ độ từng API
- [Tích hợp ô nhập địa chỉ](https://maps.vietmap.vn/docs/vi/map-api/use-cases/checkout-address-guide/): Autocomplete v4, Place v4, Reverse v4 qua server của bạn; địa chỉ cũ và mới
- [Đăng ký và lấy API key](https://maps.vietmap.vn/docs/vi/map-api/console/register-api-key/): Từng bước, kèm request curl đầu tiên và bảng mã lỗi
- [Cách tính transaction](https://maps.vietmap.vn/docs/vi/map-api/console/request-to-transaction/): Công thức tính tiền từng API
- [Autocomplete v4](https://maps.vietmap.vn/docs/vi/map-api/autocomplete-version/autocomplete-v4/): Gợi ý khi gõ; trả `ref_id` cho Place v4
- [Geocode v4](https://maps.vietmap.vn/docs/vi/map-api/geocode-version/geocode-v4/): Chuỗi địa chỉ đầy đủ ra danh sách ứng viên
- [Place v4](https://maps.vietmap.vn/docs/vi/map-api/place-v4/): `ref_id` ra toạ độ và thành phần địa chỉ
- [Reverse v4](https://maps.vietmap.vn/docs/vi/map-api/reverse-version/reverse-v4/): Toạ độ ra địa chỉ gần nhất
- [Chuyển đổi địa chỉ](https://maps.vietmap.vn/docs/vi/migrate-address/migrate-address-docs/): Đổi địa chỉ giữa đơn vị hành chính cũ và mới
- [Route v4](https://maps.vietmap.vn/docs/vi/map-api/route-version/route-v4/): Chỉ đường, loại xe, `annotations=toll` cho phí cầu đường
- [Map Matching](https://maps.vietmap.vn/docs/vi/map-api/match-tolls/): Bám vệt GPS vào đường và liệt kê trạm thu phí
- [Tính phí cầu đường cho xe tải, container](https://maps.vietmap.vn/docs/vi/map-api/toll-cost/): Phí theo từng trạm bằng Route v4 với `annotations=toll`, kèm code mẫu
- [Matrix v4](https://maps.vietmap.vn/docs/vi/map-api/matrix-version/matrix-v4/): Thời gian/quãng đường giữa n điểm đi và m điểm đến
- [TSP v4](https://maps.vietmap.vn/docs/vi/map-api/tsp-version/tsp-v4/): Thứ tự ghé tối ưu cho một xe
- [VRP](https://maps.vietmap.vn/docs/vi/map-api/vrp/): Chia điểm cho đội xe với tải trọng, khung giờ, kỹ năng
- [Tilemap](https://maps.vietmap.vn/docs/vi/map-api/tilemap/): URL style vector và tile raster vệ tinh
- [Lớp giao thông](https://maps.vietmap.vn/docs/vi/map-api/traffic-layer/): Kẹt xe thời gian thực dạng style vector ghép lên nền
- [Map Editor](https://maps.vietmap.vn/docs/vi/map-api/map-editor/): Tự tạo style bản đồ trên trình duyệt — mẫu, màu từng lớp, bộ icon, nhãn — trả về Style URL cho web và mobile
- [Dùng với Leaflet](https://maps.vietmap.vn/docs/vi/map-api/tilemap-leaflet/): `@vietmap/vietmap-gl-leaflet` cho dự án Leaflet sẵn có
- [Static Map](https://maps.vietmap.vn/docs/vi/map-api/static-map-version/static-map/): Ảnh bản đồ PNG cho email và báo cáo
- [Tổng quan SDK di động](https://maps.vietmap.vn/docs/vi/sdk-mobile/overview/): Android, iOS, Flutter, React Native: bản đồ và dẫn đường
- [SDK Web](https://maps.vietmap.vn/docs/vi/sdk-web-gl/overview/): VietMap GL JS, cài đặt và khởi tạo bản đồ

## Try it

- [Playground](https://tools.vietmap.vn/playground/): Call every API from the browser with a visual map
  - Playground pages take the request parameters in the URL, so you can hand a user a ready-made request, e.g. https://tools.vietmap.vn/playground/route?point=21.0285,105.8542&point=21.0368,105.8346&vehicle=motorcycle&annotations=toll (pages: tilemap, autocomplete, geocode, reverse, route, matrix, map-matching, tsp, vrp?sample=…, migrate-address)
- [Map Editor](https://tools.vietmap.vn/map-editor/): Build and save a custom map style, then copy its Style URL
- [Postman collection](https://www.postman.com/orange-escape-494916/workspace/vietmap-api-collection): 14 requests with parameters and sample data filled in
- [Live map demo](https://tools.vietmap.vn/live/): Search, routing and base maps in one page

## Optional

- [OpenAPI 3.1 spec](https://maps.vietmap.vn/docs/openapi.json): Machine-readable schema for 14 endpoints — search, geocoding, reverse, address migration, routing, map matching, matrix, TSP, VRP, geofencing, static map, styles and tiles — also as [YAML](https://maps.vietmap.vn/docs/openapi.yaml)
- Not in the OpenAPI spec yet: Isochrone, which is enabled per API key on request. [Contact support on Zalo](https://zalo.me/3189066936017422854) or email maps.info@vietmap.vn
- [Full reference in one file](https://maps.vietmap.vn/docs/llms-full.txt): All six agent guides concatenated
- [GitHub](https://github.com/vietmap-company): SDKs and integrations
- [npm](https://www.npmjs.com/org/vietmap): `@vietmap/vietmap-gl-js`, `@vietmap/vietmap-gl-leaflet`