Ranh giới hành chính Việt Nam: 34 tỉnh thành, 3.323 quận huyện và metadata phong phú

Việt Nam có ba cấp hành chính dưới cấp quốc gia: tỉnh / thành phố (tỉnh hoặc thành phố trực thuộc trung ương), huyện / quận (quận huyện), và xã / phường / thị trấn (phường hoặc xã). Nắm chính xác các cấp này chính là sự khác biệt giữa một địa chỉ geocode được và một địa chỉ thì không.

Hiện nay GoGoDuk cung cấp hai cấp trên thông qua /v1/admin-boundaries — 34 tỉnh thành và 3.323 quận huyện, lấy nguồn từ bando.com.vn và được làm sạch trong dataset riêng của chúng tôi. Cấp phường xã sắp ra mắt.

Những gì bạn nhận được hôm nay

Endpoint trả về geometry dạng polygon cho từng đơn vị hành chính, đánh khóa theo admin level của OSM:

curl -H "X-API-Key: gdk_live_..." \
  "https://api.gogoduk.com/v1/admin-boundaries?levels=4,8&format=geojson"

Cấu trúc response:

{
  "admin_level_4": [
    {
      "name": "Tỉnh Lào Cai",
      "province_name": "Tỉnh Lào Cai",
      "province_id": "diaphanhanhchinhcaptinh_sn.114",
      "population": 1778785,
      "area_km2": 13256.92,
      "pre_merge_info": "tỉnh Yên Bái và tỉnh Lào Cai",
      "admin_center": "Yên Bái (cũ)",
      "phone": "...",
      "website": "...",
      "centroid": [104.34738, 22.06048],
      "boundary": [[[103.97, 22.85], ...]]
    }
  ],
  "admin_level_8": [
    {
      "name": "Đống Đa",
      "province_name": "Hà Nội",
      "population": 401740,
      "area_km2": 9.96,
      "centroid": [105.83, 21.01],
      "boundary": [[[105.8, 21.0], ...]]
    }
  ]
}

Mọi trường ngoài name và boundary đều là tùy chọn — API chỉ xuất ra khi bản ghi gốc có giá trị. Nếu bạn đang nâng cấp từ phiên bản đầu tiên vốn chỉ trả về name + boundary, bạn không cần thay đổi code nào cả. TypeScript SDK cung cấp các trường này dưới dạng tùy chọn trong @gogoduk/[email protected].

Các polygon được lấy từ những nguồn GIS cấp tỉnh có thẩm quyền, sau đó chạy qua pipeline QA riêng của chúng tôi để bắt các khe hở mỏng (sliver gap) và geometry tự cắt nhau (self-intersecting) — những lỗi này phổ biến hơn bạn tưởng trong các dataset chính phủ công bố.

Vì sao cấp phường xã quan trọng — và những gì chúng tôi có hôm nay

Phần lớn địa chỉ Việt Nam được phân biệt ở cấp phường xã, chứ không phải ở tên đường. "Đường số 7" tồn tại ở hàng chục phường tại TP.HCM. Nếu không có ngữ cảnh phường xã, một bộ geocoder sẽ chọn nhầm.

Hiện tại, geometry cấp phường xã chưa được mở qua /v1/admin-boundaries. Nhưng bạn đã có thể reverse-geocode một điểm về tỉnh thành + quận huyện chứa nó thông qua endpoint liên quan:

curl -H "X-API-Key: gdk_live_..." \
  "https://api.gogoduk.com/v1/reverse-geocode?lat=21.03&lng=105.85"

Trả về:

{ "lat": 21.03, "lng": 105.85, "city": "Hà Nội", "district": "Đống Đa" }

Cả hai endpoint đều được hỗ trợ bởi cùng một truy vấn PostGIS ST_Contains trên bảng ranh giới của chúng tôi — cùng độ chính xác, chỉ khác hình thức.

Có gì trong mỗi bản ghi

Mỗi polygon giờ đây đi kèm metadata mà dataset đã mang theo từ đầu — không cần JOIN thủ công:

• province_name + province_id — tỉnh thành cha của quận huyện; trùng với name đối với chính các tỉnh thành
• population + area_km2 — hữu ích cho việc lập kế hoạch vùng phục vụ, tổng hợp mật độ và bản đồ choropleth mà không cần gọi API lần thứ hai
• admin_center — thành phố/thị trấn đặt trụ sở chính quyền của đơn vị
• phone + website — kênh liên hệ chính thức của chính quyền địa phương, khi có công bố
• pre_merge_info — ghi chú dễ đọc về lần sắp xếp lại gần nhất của đơn vị. Việt Nam đã sáp nhập tỉnh thành và quận huyện vào năm 2025; các địa chỉ cũ với tên trước đây vẫn còn lưu hành. Trường này cho bạn biết đơn vị nào đã sáp nhập vào đơn vị nào để bạn có thể đối chiếu.
• centroid — một điểm [lng, lat] duy nhất cho mỗi đơn vị. Hữu ích cho việc gắn nhãn trên bản đồ mà không cần tính centroid của polygon ở phía client.

Độ phủ trường dữ liệu đạt 100% cho cả hai cấp tại thời điểm viết bài (34/34 tỉnh thành, 3.323/3.323 quận huyện).

Vẫn còn trên lộ trình

Polygon cấp phường xã (admin_level=10) — Việt Nam có hơn 10.500 phường xã trên 3.323 quận huyện sau đợt sắp xếp lại năm 2025, và chúng tôi đang xử lý dần dataset. Theo dõi changelog để biết ngày ra mắt.

Thử ngay

curl -H "X-API-Key: gdk_live_..." \
  "https://api.gogoduk.com/v1/admin-boundaries?levels=4&tolerance=0.01" \
  | jq '.admin_level_4 | length'

Kết quả phải in ra 34. Nếu bạn gặp một polygon trông có vẻ sai — khe hở mỏng, thiếu quận huyện, ranh giới lỗi thời sau một lần sáp nhập gần đây — vui lòng email [email protected] kèm tên đơn vị và chúng tôi sẽ kiểm tra. Dataset được làm sạch thủ công, chứ không phải bằng phép màu.