Bỏ qua

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 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.

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

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

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

Gọi 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.

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

[
  {
    "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:

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

{
  "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). Gộp bước 2 và 3 thành một hàm:

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

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

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:

<!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. Với ứng dụng di động, xem SDK Mobile.

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.
  • Code xử lý 401, 423, 429 và kiểm tra code trong phản hồi chỉ đường. Xem Mã lỗi.
  • Đã kiểm tra hạn mức của tài khoản ở Giới hạn sử dụng.
  • Đã ước tính lượng dùng hằng tháng bằng Cách tính tiền và công cụ quy đổi.
  • Theo dõi mức dùng ở Theo dõi mức dùng API Key. VIETMAP gửi email khi dùng tới 80% và 100% tổng hạn mức.

Bước tiếp theo

Hotline
Tổng đài hỗ trợ
089.616.4567 Messenger Chat Facebook zalo Chat Zalo