Vietnam Address Converter: old 63-province addresses to the new 34-province format

On 1 July 2025 Vietnam merged its 63 provinces into 34 and removed the district level. Every address written before that date is now out of date. This Actor converts old addresses to the new format in bulk, so you can fix a customer list, a CRM export or a shipping database without writing code.

What you get for each address

• The new address, new ward and new province, with correct Vietnamese accents
• Ward and province codes, plus ward coordinates
• The old ward, district and province it was matched to, so you can audit the result
• A needsReview flag on every row that is not a clean one-to-one conversion

Example

Input:

{
  "addresses": [
    "720A Điện Biên Phủ, Phường 22, Quận Bình Thạnh, TP.HCM",
    "so 1 Dai Co Viet, P. Bach Khoa, Q. Hai Ba Trung, Ha Noi",
    "12 Đường A, Xã Hòa Liên, Huyện Hòa Vang, Đà Nẵng"
  ]
}

Output (shortened):

[
  {
    "input": "720A Điện Biên Phủ, Phường 22, Quận Bình Thạnh, TP.HCM",
    "status": "converted",
    "newAddress": "720A Điện Biên Phủ, Phường Thạnh Mỹ Tây, Thành phố Hồ Chí Minh",
    "newWard": "Phường Thạnh Mỹ Tây",
    "newProvince": "Thành phố Hồ Chí Minh",
    "newWardCode": "26956",
    "newProvinceCode": "79",
    "oldWard": "Phường 22",
    "oldDistrict": "Quận Bình Thạnh",
    "needsReview": false
  },
  {
    "input": "so 1 Dai Co Viet, P. Bach Khoa, Q. Hai Ba Trung, Ha Noi",
    "status": "converted",
    "newAddress": "So 1 Dai Co Viet, Phường Bạch Mai, Thành phố Hà Nội",
    "needsReview": false
  },
  {
    "input": "12 Đường A, Xã Hòa Liên, Huyện Hòa Vang, Đà Nẵng",
    "status": "converted",
    "newWard": "Phường Liên Chiểu",
    "wardWasSplit": true,
    "candidateWards": ["Phường Hải Vân", "Phường Liên Chiểu"],
    "needsReview": true
  }
]

Who uses this

• E-commerce and logistics teams updating delivery addresses so couriers accept them
• CRM and ERP owners cleaning customer, supplier and branch records
• Data and AI teams that need one consistent address key to join datasets
• AI agents that need to normalise a Vietnamese address inside a workflow (works through the Apify MCP server)

It handles messy input

• Missing accents: Phuong Ben Nghe, Quan 1, Ho Chi Minh
• Abbreviations: P., Q., TP.HCM, TX., TT.
• Province only: Bình Dương becomes Thành phố Hồ Chí Minh, marked province_only
• Input that is not an address: returned as not_found, never a crash, and not charged

Honest about uncertainty

About 470 old wards were split across two or more new wards. The street alone cannot tell you which one is right, so the Actor picks a default, sets wardWasSplit: true, lists every possibility in candidateWards, and sets needsReview: true. Filter on needsReview to get the short list a person should check.

Addresses are processed inside the Actor. Nothing is sent to an external geocoding service.

Input

Field	Type	Description
addresses	array of strings	One address per item, smallest unit first: street, ward, district, province
mode	convert or standardize	convert (default) for old-format addresses. standardize for addresses already in the new format that only need cleaning and codes

Output fields

Field	Description
index	Position of the address in your input
status	converted, province_only or not_found
newAddress	Full address in the new format
street	Street part, kept as you wrote it
newWard, newProvince	New administrative units
newWardCode, newProvinceCode	Administrative unit codes
latitude, longitude	Approximate centre of the new ward (not of the street address)
oldWard, oldDistrict, oldProvince	What the input was matched to
wardWasSplit, candidateWards	Set when the old ward maps to several new wards
needsReview	true when a person should check the row
note	Plain-language reason when review is needed

A run summary with counts per status is saved in the key-value store under SUMMARY.

Pricing

Pay per result: you pay only for addresses that were recognised. Rows returned as not_found are free.

Coverage and limits

• Tested against all 10,040 pre-merger ward names: every one was matched when written with accents, and 99.6% when written without accents (a few unaccented names are ambiguous and fall back to province_only).
• That test measures whether an address is recognised. The old-to-new mapping itself comes from the open-source vietnamadminunits dataset (MIT licence). Treat results as a strong starting point and review flagged rows before using them for legal or official documents.
• Write addresses from smallest to largest unit. Reversed order is not supported.
• Coordinates are ward centres, not rooftop geocodes.

FAQ

Does it work on addresses that are already in the new format? Use mode: "standardize".

Can I run it from code? Yes, through the Apify API, the Python or JavaScript client, Make, Zapier, n8n, or the Apify MCP server.

I found a wrong result. Open an issue on the Issues tab with the input address.

This is an independent tool and is not affiliated with any government body.