Vietnam admin boundaries: 34 provinces, 3,323 districts, and rich metadata

Vietnam has three administrative levels below the country: tỉnh / thành phố (province or centrally-governed city), huyện / quận (district), and xã / phường / thị trấn (ward or commune). Knowing them precisely is the difference between an address that geocodes and one that doesn't.

GoGoDuk ships the upper two levels today via /v1/admin-boundaries — 34 provinces and 3,323 districts, sourced from bando.com.vn and cleaned in our own dataset. Wards are coming.

What you get today

The endpoint returns polygon geometry per administrative unit, keyed by OSM admin level:

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

Response shape:

{
  "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], ...]]
    }
  ]
}

Every field besides name and boundary is optional — the API only emits them when the underlying record has a value. If you're upgrading from the original release that only returned name + boundary, no code changes are needed. The TypeScript SDK ships these as optional fields in @gogoduk/[email protected].

Polygons are derived from authoritative provincial GIS sources, then run through our own QA pipeline to catch sliver gaps and self-intersecting geometries (more common than you'd think in published government datasets).

Why ward-level matters — and what we have today

Most Vietnamese addresses disambiguate at the ward, not the street. "Đường số 7" (Street No. 7) exists in dozens of HCMC wards. Without ward context, a geocoder picks the wrong one.

For now, ward-level geometry isn't exposed through /v1/admin-boundaries. But you can already reverse-geocode a point to its containing province + district via the related endpoint:

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

Returns:

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

Both endpoints are backed by the same PostGIS ST_Contains query against our boundary table — same accuracy, different shape.

What's in every record

Each polygon now ships with the metadata the dataset has carried all along — no JOIN by hand needed:

• province_name + province_id — parent province for districts; matches name for provinces themselves
• population + area_km2 — useful for service-area planning, density rollups, and choropleth maps without a second API call
• admin_center — the seat-of-government city/town for the unit
• phone + website — official contact channels for the local administration, where published
• pre_merge_info — human-readable note about the unit's most recent reorganisation. Vietnam consolidated provinces and districts in 2025; old addresses with the previous names still circulate. This field tells you what merged into what so you can cross-reference.
• centroid — a single [lng, lat] point per unit. Useful for labelling on maps without measuring polygon centroids client-side.

Field coverage is 100% for both levels at the time of writing (34/34 provinces, 3,323/3,323 districts).

Still on the roadmap

Ward-level polygons (admin_level=10) — Vietnam has 10,500+ wards across its 3,323 districts after the 2025 reorganization, and we're working through the dataset. Watch the changelog for the ship.

Try it

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

Should print 34. If you hit a polygon that looks wrong — sliver gap, missing district, outdated boundary after a recent merge — please email [email protected] with the unit name and we'll investigate. The dataset is hand-cleaned, not magical.