Toạ độ ra phường xã API

Đổi vĩ độ, kinh độ ra tỉnh và phường, xã mới (sau 1/7/2025) kèm mã đơn vị; tra hàng loạt tới 1000 điểm, kiểm tra điểm thuộc xã và lấy ranh giới xã.

GETPOSThttps://apibox.io.vn/v1/vn-geo

Dữ liệu & JSON▶ Dùng thử online

Gửi lat và lng (hệ WGS 84, như toạ độ điện thoại, GPS trả về), API trả về tỉnh (34 đơn vị) và phường / xã / đặc khu (3.321 đơn vị) chứa điểm đó theo sắp xếp từ 1/7/2025, cùng mã Cục Thống kê, tên và mã bưu chính như /v1/vn-provinces. distance=1 cho thêm khoảng cách tới ranh giới xã; ward=<mã> kèm toạ độ cho biết điểm có nằm trong xã đó không (chấm công, giới hạn vùng), còn ward=<mã> riêng lẻ trả về khung bao, tâm, diện tích và, với geometry=1, ranh giới đã đơn giản hoá dạng GeoJSON.

Tra hàng loạt bằng POST points dạng [[lat, lng], …] hoặc [{"lat": …, "lng": …}] (tối đa 1000 điểm mỗi lần). Điểm nằm sát ngoài mọi xã (bãi biển, bờ sông, lệch vài mét so với ranh giới đơn giản hoá) được gán cho xã gần nhất trong phạm vi max_distance mét (mặc định 250), kèm inside: false và distance_m; xa hơn (ngoài biển, nước láng giềng) thì found: false và có thông tin xã gần nhất để tham khảo.

Ranh giới lấy từ phần GIS của bộ dữ liệu mở ThangLeQuoc/vietnamese-provinces-database (giấy phép MIT), xây dựng từ bản đồ tham chiếu chính thức sapnhap.bando.com.vn, được đơn giản hoá khoảng 30 m mà vẫn giữ các cạnh chung khớp nhau (không hở, không chồng giữa hai xã kề nhau). Vì vậy điểm cách ranh giới vài chục mét có thể rơi sang xã bên cạnh: kết quả được đánh dấu approximate, không thay cho xác định địa chính hay pháp lý. Không tra số nhà.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`lat`	query\|body	number	không		Vĩ độ, độ thập phân (WGS 84). Hoặc `latlng=21.0288,105.8525`, hoặc ghi cặp toạ độ trên đường dẫn `/v1/vn-geo/21.0288,105.8525`.
`lng`	query\|body	number	không		Kinh độ, độ thập phân (nhận cả `lon`).
`points`	body	array	không		Tra hàng loạt: tối đa 1000 điểm dạng `[[lat, lng], …]`, `[{"lat","lng"}]` hoặc `"lat,lng;lat,lng"`.
`ward`	query\|body	string	không		Mã phường, xã (5 số). Kèm toạ độ: điểm có thuộc xã này không? Riêng lẻ: khung bao, tâm, diện tích của xã.
`geometry`	query\|body	boolean	không	`false`	Khi chỉ có `ward`: thêm ranh giới đã đơn giản hoá dạng GeoJSON MultiPolygon.
`distance`	query\|body	boolean	không	`false`	Thêm `boundary_distance_m`: khoảng cách từ điểm tới ranh giới xã chứa nó.
`max_distance`	query\|body	number	không	`250`	Gán điểm nằm ngoài mọi xã cho xã gần nhất trong phạm vi bấy nhiêu mét (0–50000).

Ví dụ

curl "https://apibox.io.vn/v1/vn-geo?lat=10.7725&lng=106.698" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-geo?lat=10.7725&lng=106.698', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/vn-geo?lat=10.7725&lng=106.698",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-geo?lat=10.7725&lng=106.698');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "lat": 10.7725,
  "lng": 106.698,
  "found": true,
  "inside": true,
  "province": {
    "code": "79",
    "name": "Hồ Chí Minh",
    "full_name": "Thành phố Hồ Chí Minh"
  },
  "ward": {
    "code": "26743",
    "name": "Bến Thành",
    "full_name": "Phường Bến Thành",
    "type": "Phường",
    "type_en": "ward",
    "postal_code": "71009"
  },
  "approximate": true,
  "precision_m": 30,
  "data": {
    "admin_version": "v5.2.0",
    "built_at": "2026-11-11",
    "legal_basis": "Nghị quyết 202/2025/QH15 (34 provinces) and the UBTVQH resolutions on ward-level units, effective 1/7/2025; latest change in the dataset: 388/NQ-UBTVQH16",
    "source": "ThangLeQuoc/vietnamese-provinces-database GIS add-on (MIT), derived from sapnhap.bando.com.vn (NXB Tài nguyên Môi trường và Bản đồ Việt Nam)"
  }
}

Ứng dụng

Tự điền phường, xã, tỉnh mới từ vị trí GPS trong app giao hàng, khảo sát
Kiểm tra nhân viên chấm công có ở đúng xã được giao không
Chuyển bảng toạ độ cửa hàng, khách hàng sang đơn vị hành chính mới
Vẽ ranh giới một xã lên bản đồ từ mã xã

Hỏi đáp

Có phải đơn vị hành chính mới sau 1/7/2025 không?

Đúng: 34 tỉnh, thành và 3.321 phường, xã, đặc khu, dùng chung mã với /v1/vn-provinces. Dữ liệu được đối chiếu hằng tuần với bản phát hành mới nhất.

Độ chính xác thế nào?

Ranh giới được đơn giản hoá khoảng 30 m; khi kiểm thử 99,7% điểm ngẫu nhiên trùng với bản đồ gốc, phần còn lại nằm cách ranh giới vài chục mét.

Điểm ngoài biển hoặc ngoài Việt Nam thì sao?

Điểm cách bờ trong max_distance (mặc định 250 m) được gán xã gần nhất; xa hơn thì found là false, kèm xã gần nhất và khoảng cách.

API liên quan

{✓}

Toạ độ ra phường xã API

Tham số

Ví dụ

Kết quả trả về

Ứng dụng

Hỏi đáp

API liên quan

Kiểm tra JSON

Định dạng JSON

CSV sang JSON