Vietnam's 2025 Province Merger: Normalizing Old → New Addresses with an API

In 2025, Vietnam carried out its largest administrative reorganization in decades: from 63 provinces down to 34. For end users, this is an administrative matter. For developers, it's a data headache: millions of addresses in your database still carry the old province/district/ward names, while new systems, partners, and customers gradually switch to the new ones.

This post explains the background, the impact on software systems, and how to normalize old → new addresses with an API in a practical way.

Background: 63 → 34 provincial-level units

Under the 2025 resolution on reorganizing provincial-level administrative units (Resolution 202), passed by the National Assembly on 12 June 2025, the country now has 34 provincial-level units: 28 provinces and 6 centrally-governed cities. Of these, 23 were formed by merging and 11 remained unchanged (including Hà Nội, Huế, and provinces such as Cao Bằng, Điện Biên, Hà Tĩnh, Lạng Sơn, Nghệ An, Quảng Ninh, Thanh Hóa, Sơn La, Lai Châu).

The new provincial/city governments officially began operating on 1 July 2025. In parallel, many places are moving toward a two-tier model (province – ward/commune), which means thousands of wards/communes are being renamed and rearranged.

Key dates: passed 12 June 2025, operational 1 July 2025. Any address dataset created before this should be reviewed.

Why this is a developer's problem

If your system stores addresses as free-text strings or hard-codes province/district names, the merger causes a cascade of issues:

• Logistics & delivery: old addresses don't match new routes/zones → misdeliveries, delays, higher failed-delivery rate.
• E-commerce: checkout forms with old province/district dropdowns → customers can't find their address, carts get abandoned.
• CRM & analytics: province/district rollups skew when part of the data uses old names and part uses new ones.
• Reports & maps: boundary-based stats are wrong because the boundaries themselves changed.

The core fix: you need an up-to-date admin-boundary data source and a way to map addresses/coordinates to the new administrative units.

Two problems to solve

1. Old (text) address → new administrative unit. E.g. an old order says "District X, Province Y" while Y has merged into Province Z.
2. Coordinates (lat/lng) → current province/district. When you have a GPS point (customer, driver, warehouse) and need to know which new administrative unit it belongs to.

Problem (2) is especially powerful, because coordinates don't change when boundaries are renamed — you can always reverse-geocode a point to its current administrative unit, regardless of what the old address string says.

How to do it with GoGoDuk

GoGoDuk ships admin-boundary data (province + district) updated for the reorganization, plus reverse-geocode to map coordinates to the current province/district — free.

Step 1 — Get the current administrative catalog

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

Each province record ships useful metadata, including a note about the most recent reorganization:

{
  "admin_level_4": [
    {
      "name": "Tỉnh Lào Cai",
      "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ũ)",
      "centroid": [104.34738, 22.06048]
    }
  ]
}

The pre_merge_info field tells you which unit merged into which — handy for building an "old name → new name" lookup table.

Step 2 — Map coordinates to the current province/district

If your records have coordinates (or you geocode the address to coordinates first), reverse-geocode them:

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

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

The result always follows the current boundaries in the dataset, so this is the most reliable way to attach a point to the right new administrative unit.

Step 3 — For text-only addresses

If you only have an address string (no coordinates), geocode first to get coordinates, then reverse-geocode to the new unit:

# 1) Address -> suggestion + coordinates
curl -H "X-API-Key: gdk_live_..." \
  "https://api.gogoduk.com/v1/suggest?input=226+Van+Phuc+Ba+Dinh+Ha+Noi"

Take the lat/lng of the best match, then call /v1/reverse-geocode as in Step 2. This "go through coordinates" approach is more robust than string-matching old province/district names.

Address-normalization checklist for devs

• Split fields: don't store the address as a single free-text string — separate province/district/ward + street + house number.
• Store coordinates: geocode and save lat/lng for every address — this is the durable key when boundaries get renamed.
• Build a lookup table of old name → new name (use pre_merge_info) for text-only data.
• Update dropdowns for province/district/ward in your forms with the new catalog (/v1/admin-boundaries).
• Re-run reverse-geocode for historical data that has coordinates to attach the current administrative unit.
• Test edge cases: merged provinces/districts and ward/commune rename cases.

Frequently asked questions

How many provinces does Vietnam have after the 2025 merger? 34 provincial-level units: 28 provinces and 6 centrally-governed cities, officially operating since 1 July 2025.

How do I convert old addresses to new ones? The most durable way is to go through coordinates: geocode the address to lat/lng, then reverse-geocode to the current province/district. For text-only data, build an old → new lookup table.

Does GoGoDuk have the new ward/commune data yet? Today /v1/admin-boundaries provides updated province + district levels; ward/commune boundaries are on the roadmap. Watch the changelog.

Is it free? Yes. GoGoDuk's admin-boundary and reverse-geocode APIs are free — 100 requests/day per account, no card.

Get started

See the full admin-boundary dataset in Vietnam admin boundaries, or try it now:

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

It should print 34. Sign up for an API key or read the docs. Spot a wrong boundary after the merger? Email [email protected] with the unit name and we'll investigate.