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

# Bắt đầu nhanh

Hướng dẫn này đi từ đăng ký tài khoản tới lần gọi API đầu tiên và hiển thị địa chỉ trên bản đồ.

## 1. Lấy API key

[Đăng ký tài khoản](https://maps.vietmap.vn/console-v2/register) và xác nhận email. Email thứ hai, tiêu đề **Account Registration Information**, gửi kèm hai key dùng được ngay:

| Key | Dùng cho | Đặt ở đâu |
| --- | --- | --- |
| Services key | Map API: tìm địa chỉ, geocode, chỉ đường, ma trận, tối ưu lộ trình | Chỉ ở backend |
| Tilemap key | Hiển thị bản đồ nền trong SDK | Code phía client, giới hạn theo domain trong Console |

Tài khoản mới có 60.000 transaction miễn phí, tương đương khoảng 3.000.000đ. Hướng dẫn đăng ký từng bước có ảnh ở [Đăng ký API key](https://maps.vietmap.vn/docs/vi/map-api/console/register-api-key/).

Các ví dụ dưới đây đọc services key từ biến môi trường:

```bash
export VIETMAP_API_KEY="services key của bạn"
```

## 2. Tìm một địa chỉ

Gọi [Autocomplete v4](https://maps.vietmap.vn/docs/vi/map-api/autocomplete-version/autocomplete-v4/) bằng services key. `focus` là toạ độ dạng `lat,lng` (vĩ độ trước), giúp xếp các kết quả gần điểm đó lên đầu.

```bash
curl -G 'https://maps.vietmap.vn/api/autocomplete/v4' \
  --data-urlencode "apikey=$VIETMAP_API_KEY" \
  --data-urlencode 'text=197 tran phu' \
  --data-urlencode 'focus=10.7588,106.6753'
```

Kết quả (rút gọn):

```json
[
  {
    "ref_id": "auto:RAkPcicmZ3d-NQ...",
    "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
    "name": "197 Trần Phú",
    "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh"
  }
]
```

Mỗi kết quả có `ref_id` để lấy toạ độ ở bước tiếp theo.

## 3. Lấy toạ độ

Truyền nguyên `ref_id` người dùng đã chọn, kể cả tiền tố, vào [Place v4](https://maps.vietmap.vn/docs/vi/map-api/place-v4/):

```bash
curl -G 'https://maps.vietmap.vn/api/place/v4' \
  --data-urlencode "apikey=$VIETMAP_API_KEY" \
  --data-urlencode 'refid=<ref_id từ bước 2>'
```

Kết quả (rút gọn):

```json
{
  "display": "197 Đường Trần Phú,Phường Chợ Quán,Thành Phố Hồ Chí Minh",
  "ward": "Phường Chợ Quán",
  "city": "Thành Phố Hồ Chí Minh",
  "lat": 10.759222947000069,
  "lng": 106.67590269100003
}
```

Mỗi request Autocomplete hoặc Place tính 1 transaction ([Cách tính tiền](https://maps.vietmap.vn/docs/vi/map-api/console/request-to-transaction/)). Gộp bước 2 và 3 thành một hàm:

=== "JavaScript"

    ```js
    // Node.js 18+. Gọi từ server để không lộ API key.
    const KEY = process.env.VIETMAP_API_KEY;
    const API = "https://maps.vietmap.vn/api";

    async function getJson(url) {
      const res = await fetch(url);
      if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
      return res.json();
    }

    // Chuỗi địa chỉ -> kết quả khớp nhất, kèm toạ độ
    async function locate(text, focus) {
      const q = new URLSearchParams({ apikey: KEY, text });
      if (focus) q.set("focus", focus);
      const results = await getJson(`${API}/autocomplete/v4?${q}`);
      if (results.length === 0) return null;
      const p = new URLSearchParams({ apikey: KEY, refid: results[0].ref_id });
      return getJson(`${API}/place/v4?${p}`); // { display, lat, lng, ... }
    }

    console.log(await locate("197 tran phu", "10.7588,106.6753"));
    ```

=== "Python"

    ```python
    import os

    import requests

    KEY = os.environ["VIETMAP_API_KEY"]
    API = "https://maps.vietmap.vn/api"


    def get_json(url, params):
        resp = requests.get(url, params=params, timeout=10)
        resp.raise_for_status()
        return resp.json()


    def locate(text, focus):
        """Chuỗi địa chỉ -> kết quả khớp nhất, kèm toạ độ."""
        results = get_json(f"{API}/autocomplete/v4", {"apikey": KEY, "text": text, "focus": focus})
        if not results:
            return None
        return get_json(f"{API}/place/v4", {"apikey": KEY, "refid": results[0]["ref_id"]})


    print(locate("197 tran phu", "10.7588,106.6753"))
    ```

=== "Prompt cho AI agent"

    ``` { .text .vm-prompt }
    Tích hợp tìm địa chỉ của VIETMAP vào dự án của tôi.

    1. GET https://maps.vietmap.vn/api/autocomplete/v4
         text=<chuỗi người dùng gõ>
         focus=<vĩ độ,kinh độ của người dùng, nếu có>
       Trả về mảng gợi ý, mỗi phần tử có ref_id và display.
    2. GET https://maps.vietmap.vn/api/place/v4
         refid=<ref_id người dùng chọn, giữ nguyên tiền tố>
       Kết quả có display, lat, lng và các thành phần địa chỉ.

    Yêu cầu:
    - Gọi API từ server. Đọc API key từ biến môi trường VIETMAP_API_KEY và truyền qua `apikey`, không ghi cứng trong code.
    - Viết hàm locate(text, focus) trả về địa chỉ khớp nhất kèm lat, lng; kiểm tra mã HTTP (401: sai key, 423: hết hạn mức hoặc API chưa bật).
    - Đọc tài liệu bên dưới trước. Chỉ dùng tham số và trường dữ liệu có trong tài liệu.

    Tài liệu:
    - https://maps.vietmap.vn/docs/vi/map-api/quickstart/index.txt
    - https://maps.vietmap.vn/docs/vi/map-api/autocomplete-version/autocomplete-v4/index.txt
    - https://maps.vietmap.vn/docs/vi/map-api/place-v4/index.txt
    - https://maps.vietmap.vn/docs/assets/agents/search-geocoding.txt
    ```

## 4. Hiện lên bản đồ

Bản đồ dùng **tilemap key**. Lưu đoạn mã dưới đây thành `map.html` và mở bằng trình duyệt:

```html
<!DOCTYPE html>
<html lang="vi">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <link rel="stylesheet" href="https://unpkg.com/@vietmap/vietmap-gl-js@6.0.1/dist/vietmap-gl.css" />
  <script src="https://unpkg.com/@vietmap/vietmap-gl-js@6.0.1/dist/vietmap-gl.js"></script>
  <style>html, body, #map { height: 100%; margin: 0; }</style>
</head>
<body>
  <div id="map"></div>
  <script>
    // Toạ độ từ bước 3. Ở đây thứ tự là [kinh độ, vĩ độ].
    const lngLat = [106.67590269100003, 10.759222947000069];
    const map = new vietmapgl.Map({
      container: "map",
      style: "https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=YOUR_TILEMAP_KEY",
      center: lngLat,
      zoom: 16,
    });
    map.addControl(new vietmapgl.NavigationControl());
    new vietmapgl.Marker().setLngLat(lngLat).addTo(map);
  </script>
</body>
</html>
```

`tm` trong URL là style đường phố; các style khác (sáng, tối, vệ tinh) và cách đổi style xem ở [Tilemap](https://maps.vietmap.vn/docs/vi/map-api/tilemap/). Với ứng dụng di động, xem [SDK Mobile](https://maps.vietmap.vn/docs/vi/sdk-mobile/overview/).

## 5. Trước khi chạy thật

- Services key chỉ nằm ở server, đọc từ biến môi trường, không có trong code trình duyệt hay app.
- Tilemap key đã giới hạn theo domain (và IP) ở [Quản lý API Key](https://maps.vietmap.vn/docs/vi/map-api/console/manage-api-key/).
- Code xử lý `401`, `423`, `429` và kiểm tra `code` trong phản hồi chỉ đường. Xem [Mã lỗi](https://maps.vietmap.vn/docs/vi/map-api/errors/).
- Đã kiểm tra hạn mức của tài khoản ở [Giới hạn sử dụng](https://maps.vietmap.vn/docs/vi/map-api/console/usage-limitation/).
- Đã ước tính lượng dùng hằng tháng bằng [Cách tính tiền](https://maps.vietmap.vn/docs/vi/map-api/console/request-to-transaction/) và [công cụ quy đổi](https://maps.vietmap.vn/docs/vi/map-api/console/pricing-converter/).
- Theo dõi mức dùng ở [Theo dõi mức dùng API Key](https://maps.vietmap.vn/docs/vi/map-api/console/monitor-api-key-usage/). VIETMAP gửi email khi dùng tới 80% và 100% tổng hạn mức.

## Bước tiếp theo

- Giải pháp: [Chỉ đường cho xe tải và container](https://maps.vietmap.vn/docs/vi/map-api/use-cases/truck-routing/), [Logistics và giao hàng](https://maps.vietmap.vn/docs/vi/map-api/use-cases/delivery-routing/), [Gợi ý địa chỉ khi đặt hàng](https://maps.vietmap.vn/docs/vi/map-api/use-cases/checkout-address/).
- [Playground](https://tools.vietmap.vn/playground/): thử mọi API trên bản đồ.
- [Tài liệu cho AI agent](https://maps.vietmap.vn/docs/llms.txt): tích hợp cùng trợ lý AI.