Thay Google Maps API bằng map.vapp.vn: hướng dẫn chuyển đổi từng bước

Trả lời nhanh: nếu bạn dùng Google Maps Platform để hiển thị bản đồ, tìm địa chỉ và chỉ đường tại Việt Nam, bạn có thể chuyển sang map.vapp.vn bằng hai thay đổi: đổi thư viện bản đồ sang MapLibre GL JS (mã nguồn mở) trỏ tới https://map.vapp.vn/style.json, và đổi địa chỉ gọi API sang https://map.vapp.vn/api/v1/…. Gói Developer miễn phí 20.000 lượt gọi mỗi tháng; tạo khóa ngay tại trang nhà phát triển.

Bảng chuyển đổi

Việc cần làm	Google Maps Platform	map.vapp.vn
Hiển thị bản đồ	Maps JavaScript API	MapLibre GL JS + `/style.json`
Tìm tọa độ của một địa chỉ hoặc địa danh	Geocoding API (geocode/json?address=…)	`/api/v1/geocode`
Đổi tọa độ thành địa chỉ	Geocoding API (geocode/json?latlng=…)	`/api/v1/reverse`
Gợi ý khi người dùng đang gõ	Places Autocomplete	`/api/v1/autocomplete`
Chỉ đường giữa hai điểm	Routes API (computeRoutes)	`/api/v1/route`
Ma trận thời gian và quãng đường	Compute Route Matrix	`/api/v1/matrix`
Tìm địa điểm quanh một vị trí	Places API (Nearby / Text Search)	`/api/v1/places`

Bước 1 — Hiển thị bản đồ

Thay thẻ script của Google bằng MapLibre GL JS, rồi tạo bản đồ với style của map.vapp.vn. Style đã gồm nền bản đồ, nhãn tiếng Việt và đường biên giới Việt Nam có quần đảo Hoàng Sa và Trường Sa.

<link href="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css" rel="stylesheet" />
<script src="https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
<div id="map" style="height: 480px"></div>
<script>
  const map = new maplibregl.Map({
    container: "map",
    style: "https://map.vapp.vn/style.json",
    center: [106.698, 10.7725], // [kinh độ, vĩ độ]
    zoom: 14,
  });
  new maplibregl.Marker().setLngLat([106.698, 10.7725]).addTo(map);
</script>

Hai điểm khác Google: tọa độ là mảng [kinh độ, vĩ độ], và marker gắn bằng setLngLat. Giữ nguyên phần ghi nguồn ở góc bản đồ: đây là điều kiện của giấy phép dữ liệu OpenStreetMap và của gói Developer.

Bước 2 — Đổi các lệnh gọi API

Mọi API trả JSON và cho phép gọi từ trình duyệt ở tên miền khác (CORS). Ví dụ dưới đây chạy được ngay bằng curl, hoặc bấm Chạy thử để gọi API ngay trên trang: kết quả có tọa độ được ghim lên bản đồ ở Bước 1.

Tìm tọa độ của một địa chỉ hoặc địa danh

curl -G "https://map.vapp.vn/api/v1/geocode" \
  --data-urlencode "q=Chợ Bến Thành"

Mỗi kết quả có lat, lng ở cấp trên cùng, không lồng trong geometry.location.

Đổi tọa độ thành địa chỉ

curl -G "https://map.vapp.vn/api/v1/reverse" \
  --data-urlencode "lat=10.7725" \
  --data-urlencode "lng=106.6980"

Trả về một kết quả gần nhất trong result, kèm khoảng cách dist_m tính bằng mét.

Gợi ý khi người dùng đang gõ

curl -G "https://map.vapp.vn/api/v1/autocomplete" \
  --data-urlencode "q=landmark 81"

Mỗi gợi ý đã có tọa độ, nên không cần gọi thêm Place Details để lấy vị trí.

Chỉ đường giữa hai điểm

curl -G "https://map.vapp.vn/api/v1/route" \
  --data-urlencode "from=106.6980,10.7725" \
  --data-urlencode "to=106.7220,10.7950" \
  --data-urlencode "mode=motorbike"

Điểm viết theo thứ tự kinh độ, vĩ độ (lng,lat), ngược với Google. Có chế độ motorbike cho xe máy.

Ma trận thời gian và quãng đường

curl -G "https://map.vapp.vn/api/v1/matrix" \
  --data-urlencode "sources=106.6980,10.7725;106.7000,10.7800" \
  --data-urlencode "targets=106.7220,10.7950"

Nhiều điểm cách nhau bằng dấu chấm phẩy. Thời gian tính bằng giây, quãng đường bằng mét.

Tìm địa điểm quanh một vị trí

curl -G "https://map.vapp.vn/api/v1/places" \
  --data-urlencode "q=cafe" \
  --data-urlencode "at=106.7000,10.7760"

Tham số at là lng,lat; cũng nhận lat= và lng= riêng.

Bước 3 — Gắn khóa API

Gửi khóa trong header x-api-key. Khóa dùng để tính hạn mức của gói và giới hạn tần suất gọi theo phút. Khi vượt giới hạn theo phút, API trả mã 429. Mỗi lệnh gọi thành công trả về lượt còn lại trong header x-ratelimit-remaining (phút) và x-usage-monthly / x-quota-monthly (tháng) (chi tiết).

curl -G -H "x-api-key: vsk_…" "https://map.vapp.vn/api/v1/geocode" \
  --data-urlencode "q=Chợ Bến Thành"

Để nhận khóa, đăng nhập trang nhà phát triển bằng Google, bấm Tạo khóa API và sao chép khóa (khóa chỉ hiện một lần). Trang đó cũng cho thấy hạn mức đã dùng trong ngày, trong tháng và các lệnh gọi gần nhất. Gói Developer miễn phí dùng được cho cả dự án cá nhân và dự án học tập.

Những điểm cần kiểm tra khi chuyển

Thứ tự tọa độ: tìm mọi chỗ code ghép chuỗi lat,lng kiểu Google. Tham số from, to, at, sources, targets nhận lng,lat.
Đơn vị: quãng đường bằng mét, thời gian bằng giây, giống Google; nhưng tên trường khác (distance_m, duration_s).
Đường đi: geometry là GeoJSON LineString, vẽ trực tiếp bằng một lớp line của MapLibre, không cần giải mã polyline.
Địa chỉ sau sắp xếp 2025: kết quả dùng tên tỉnh và phường, xã mới. Tra tên cũ tại Tra cứu phường, xã mới.

Chi phí

Google tính tiền theo từng lượt gọi bằng USD; ví dụ Geocoding là 5.00 USD cho 1.000 lượt sau phần miễn phí (giá niêm yết đọc ngày 2026-10-15). map.vapp.vn tính theo tháng bằng VND, mọi API dùng chung một hạn mức. Xem bảng giá và so sánh với Google.

Nguồn: bảng giá Google Maps Platform; tài liệu MapLibre GL JS. Ví dụ trên được kiểm tra tự động với API thật trước mỗi lần cập nhật trang. Mỗi lần bấm Chạy thử là một lệnh gọi API tới map.vapp.vn, được ghi vào nhật ký truy vấn như mọi lệnh gọi khác, xem Chính sách bảo mật.