Geocode địa chỉ Việt Nam: đổi địa chỉ thành tọa độ bằng API
Trả lời nhanh: gọi GET https://map.vapp.vn/api/v1/geocode?q=<địa chỉ>. API tách địa
chỉ thành số nhà, đường, phường/xã, quận/huyện, tỉnh, tìm đúng con đường trong đúng tỉnh, rồi đặt số nhà lên đường đó. Địa chỉ
ghi theo kiểu mới (sau 01/07/2025, không có quận) và kiểu cũ (có quận, huyện) đều dùng được. Kết quả tốt nhất là
results[0], với lat, lng và mức tin cậy confidence.
Thử ngay: gõ một địa chỉ
Đang tải…Địa chỉ đã tách (parsed)
| Kết quả | lat, lng | confidence | Nghĩa là |
|---|
Lệnh gọi cho địa chỉ trên:
Mỗi lần tìm, trang gửi một lệnh gọi geocode tới map.vapp.vn. Lệnh gọi được ghi vào nhật ký truy vấn như mọi lệnh gọi API, xem Chính sách bảo mật.
Vì sao địa chỉ Việt Nam khó geocode
- Hai cách ghi cùng tồn tại. Từ 01/07/2025 địa chỉ chỉ còn tỉnh và phường/xã, nhưng dữ liệu khách hàng, hoá đơn và giấy tờ cũ vẫn ghi quận, huyện và tên phường cũ.
- Tên đường lặp lại. Một tỉnh có thể có nhiều đường cùng tên (Lê Lợi, Nguyễn Huệ, Trần Phú…). Không có tỉnh hoặc phường, xã, tên đường không đủ để biết là đường nào.
- Số nhà trong hẻm. Số như
749/45/16là nhà số 16 trong hẻm 45 của hẻm 749. Hẻm nhỏ thường chưa có trên bản đồ. - Cách gõ khác nhau. Không dấu, viết tắt (
Q.1,P.4,TP.HCM), thiếu dấu phẩy.
Bước 1 — Gọi API geocode
curl -G "https://map.vapp.vn/api/v1/geocode" \
--data-urlencode "q=54 Nguyễn Huệ, phường Sài Gòn, TP.HCM" \
--data-urlencode "limit=1"parsed là địa chỉ đã tách (viết thường, không dấu); results[0] là kết quả tốt nhất, có lat, lng.
| Tham số | Ý nghĩa |
|---|---|
q | Địa chỉ hoặc tên địa điểm, có dấu hoặc không dấu. |
limit | Số kết quả tối đa, từ 1 đến 25, mặc định 8. Khi geocode hàng loạt, dùng limit=1. |
Gửi khóa trong header x-api-key như mọi API khác (xem hướng dẫn chuyển từ
Google Maps).
Bước 2 — Đọc kết quả
| Trường | Ý nghĩa |
|---|---|
lat, lng | Tọa độ (WGS 84), ở cấp trên cùng của mỗi kết quả. |
name, kind | Tên đường hoặc địa điểm đã khớp, và loại của nó (đường, địa danh, cửa hàng…). |
province | Tỉnh, thành phố chứa tọa độ, theo ranh giới hành chính trên OpenStreetMap. |
district | Đơn vị hành chính cấp dưới tỉnh chứa tọa độ, theo cùng ranh giới. Ranh giới hiện tại là phường, xã
mới, nên trường này thường là tên phường, xã mới (ví dụ "Phường Sài Gòn"), dù tên trường vẫn là district. |
precision | interpolated: số nhà được nội suy dọc đường. Không có trường này: tọa độ là điểm đã lưu
của đường hoặc địa điểm đó. |
place_id | Mã ổn định của kết quả (vm_…), dùng để lưu và so sánh. |
parsed | Ở cấp trên cùng của phản hồi: địa chỉ bạn gửi đã tách thành house, street,
ward, district, province (viết thường, không dấu). Xem trường này trước tiên khi kết quả sai. |
confidence | Ý nghĩa |
|---|---|
exact | Tên khớp tốt (đường, địa danh hoặc đơn vị hành chính) |
street | Đúng đường; số nhà được nội suy dọc đường, hoặc chỉ khớp tên đường |
district | Chỉ khớp một đơn vị hành chính |
approximate | Gần đúng: kiểm tra lại |
fuzzy | Mơ hồ: không nên dùng tự động |
confidence nói tên đã khớp tốt đến đâu, không bảo đảm tọa độ đúng tỉnh. Hãy luôn so province của kết quả
với tỉnh trong địa chỉ của bạn.
Bước 3 — Địa chỉ cũ và địa chỉ mới
Không cần đổi địa chỉ cũ sang địa chỉ mới trước khi geocode. Lệnh gọi dưới đây ghi địa chỉ ở Bước 1 theo kiểu cũ, và cho cùng tọa độ:
curl -G "https://map.vapp.vn/api/v1/geocode" \
--data-urlencode "q=54 Nguyễn Huệ, quận 1, TP.HCM" \
--data-urlencode "limit=1"Không cần đổi địa chỉ cũ sang địa chỉ mới trước khi geocode: quận cũ được dùng để chọn đúng đường. Phường số cũ cũng dùng được, ví dụ "phường 4, quận 8". Nếu bạn cần cả địa chỉ mới để lưu, đổi bằng API
address/convert trong hướng dẫn chuẩn hoá địa chỉ sau sáp nhập.
Bước 4 — Số nhà và hẻm
Khi địa chỉ có số nhà, API tìm con đường rồi đặt số nhà dọc theo đường đó, dựa trên các hẻm và địa điểm đã biết số nhà trên cùng
đường. Với số nhà nhiều cấp như 749/45/16, API dùng số đầu tiên (đầu hẻm 749 trên đường chính). Kết quả loại này có
precision: "interpolated" và confidence: "street".
Tọa độ nội suy nằm trên tim đường, không phải trên mái nhà. Muốn giao hàng tới tận cửa trong hẻm sâu, hãy cho người nhận chỉnh
lại vị trí trên bản đồ, hoặc gọi API đổi tọa độ thành địa chỉ (/api/v1/reverse) để họ xác nhận.
Bước 5 — Địa danh, không dấu, gõ sai
curl -G "https://map.vapp.vn/api/v1/geocode" \
--data-urlencode "q=cho ben thanh" \
--data-urlencode "limit=3"Tên được so khớp cả khi không dấu và khi gõ sai nhẹ. Kết quả trả về tên có dấu. Khi người dùng đang gõ, dùng API gợi ý /api/v1/autocomplete thay cho geocode: mỗi gợi ý đã có tọa độ.
Bước 6 — Geocode hàng loạt
- Ghép mỗi địa chỉ thành một chuỗi đủ phần: số nhà, đường, phường/xã, (quận/huyện nếu là địa chỉ cũ), tỉnh/thành phố.
- Ghi tên tỉnh, thành phố đầy đủ hoặc theo dạng thường dùng ("TP.HCM", "Hồ Chí Minh", "Đà Nẵng"). Khi không có tỉnh, một tên đường phổ biến có thể khớp với đường cùng tên ở tỉnh khác.
- Gọi với
limit=1; lưulat,lng,place_id,confidencevàprecisioncạnh địa chỉ gốc. - Đánh dấu để kiểm tra riêng các dòng có
provincekhác tỉnh trong địa chỉ, cóconfidencelàapproximatehoặcfuzzy, hoặc không có kết quả. - Lưu kết quả lại: cùng một địa chỉ không cần geocode lại mỗi lần dùng.
Mỗi địa chỉ là một lượt gọi API, tính vào hạn mức của gói (xem bảng giá).
Giới hạn cần biết
- Số nhà là nội suy, không phải điểm đo thực địa; đường mới, hẻm chưa có trên bản đồ thì chỉ khớp tới đường chính.
- Kết quả tốt nhất khi địa chỉ có tỉnh, thành phố. Viết tắt đứng một mình, không có "TP." (ví dụ chỉ "HCM"), có thể chưa được nhận ra là tên thành phố.
- Ranh giới trong
province,districtlà ranh giới trên OpenStreetMap, không phải bản đồ hành chính chính thức.
Ví dụ API trên được kiểm tra tự động với API thật trước mỗi lần cập nhật trang, kể cả tỉnh mà kết quả đầu tiên phải nằm trong.