Vietnam Address Converter — old to new provinces and wards (2025 reform)

Vietnam Address Converter turns Vietnamese addresses written in the old 3-level format (63 provinces → district → ward) into the new 2-level administrative units in force since 1 July 2025 (34 provinces → ward/commune). Paste a list of addresses, call it from the API, or point it at any Apify dataset. You get back the new ward and province, official codes, coordinates, and a clear warning whenever an old ward was split between several new wards.

Chuyển đổi địa chỉ Việt Nam cũ (63 tỉnh, có quận/huyện) sang đơn vị hành chính mới từ 1/7/2025 (34 tỉnh thành, 2 cấp, bỏ cấp huyện). Hỗ trợ địa chỉ có dấu, không dấu, viết tắt (P., Q., TP HCM, Tx., TT., H.).

What does Vietnam Address Converter do?

On 1 July 2025 Vietnam merged its 63 provinces into 34 and abolished the district level. More than 10,000 old wards and communes were consolidated into 3,321 new ones. Every CRM, delivery database, KYC record and scraped dataset collected before that date now holds addresses that no longer match official units.

This Actor fixes them in bulk:

Old address	New address (from 1 July 2025)
123 Lê Lợi, P. Bến Nghé, Q.1, HCM	123 Lê Lợi, Phường Sài Gòn, Thành phố Hồ Chí Minh
phuong 9 quan 3 tp hcm	Phường Nhiêu Lộc, Thành phố Hồ Chí Minh
TT. Phùng, H. Đan Phượng, Hà Nội	Xã Đan Phượng, Thành phố Hà Nội
Thôn 3, Xã Ea Kao, TP Buôn Ma Thuột, Đắk Lắk	Thôn 3, Phường Ea Kao, Tỉnh Đắk Lắk
Bình Dương	Thành phố Hồ Chí Minh (province merged)

Why use it?

• ⚡ Fast and fully offline: 1,500–3,500 addresses per second. No calls to Google Maps or any geocoder, so results are deterministic and your data never leaves the run.
• 🎯 Measured accuracy: tested on every one of the 10,035 old wards: 100% recognised with diacritics, 99.6% without.
• 🧹 Messy input welcome: diacritics optional, abbreviations understood (P., Q.1, TP HCM, TP.HCM, Tx., TT., H.), house numbers, alleys and floors kept as the street part, postal codes and "Việt Nam" ignored.
• 🔀 Honest about ambiguity: 4.7% of old wards were split. Those rows come back with wardWasSplit: true, confidence: "medium" and every possible new ward in candidateNewWards, instead of a silent guess.
• 🗺️ District-only addresses: if only the old district is readable (KCN VSIP, Thuận An, Bình Dương), you get the province plus the list of new wards that district now spans.
• 🔁 Mixed datasets: addresses already in the new format are recognised (already_new) and standardised.
• 🔗 Chain with any scraper: feed the dataset of a Google Maps, real-estate or e-commerce scraper and keep the original item for joining back.
• 🔒 Limited permissions: the Actor only reads the dataset you pick. Nothing else in your account is touched.
• 💸 Pay only for results: addresses that cannot be recognised at all are free.

Who is it for?

• E-commerce and logistics teams updating shipping addresses and re-grouping orders, warehouses and delivery zones by the new provinces.
• CRM, sales and marketing ops cleaning customer and lead databases.
• Fintech, banking and insurance normalising KYC addresses.
• Data engineers and analysts standardising scraped Vietnamese business, property and job data before analysis.
• Developers and AI agents validating addresses in checkout or onboarding forms through the API or MCP.

How to use it

1. Click Try for free (or Start).
2. Paste addresses into Addresses, one per line, or pick a dataset in Or: dataset ID and set Address field (dotted paths such as location.address work).
3. Click Start. Results appear in the Output tab in seconds. Download them as Excel, CSV, JSON or XML, or fetch them via the API.

Input example

{
  "addresses": [
    "59 Nguyễn Thị Minh Khai, Phường Bến Thành, Quận 1, TP Hồ Chí Minh",
    "Số 10 ngõ 5 Láng Hạ, phường Thành Công, quận Ba Đình, Hà Nội"
  ]
}

Convert an existing dataset and keep each original item:

{ "datasetId": "YOUR_DATASET_ID", "addressField": "location.address", "includeSourceItem": true }

Field	Type	Description
addresses	array of strings	Addresses to convert.
datasetId	dataset	Dataset to convert instead of, or in addition to, addresses.
addressField	string	Field holding the address in the dataset. Default address.
includeSourceItem	boolean	Copy the original dataset item into sourceItem. Default false.
maxItems	integer	Stop after this many addresses. 0 means no limit.

Output

One row per input address, in the same order (index):

{
  "index": 1,
  "input": "Số 10 ngõ 5 Láng Hạ, phường Thành Công, quận Ba Đình, Hà Nội",
  "status": "converted",
  "confidence": "medium",
  "newAddress": "Số 10 Ngõ 5 Láng Hạ, Phường Giảng Võ, Thành phố Hà Nội",
  "street": "Số 10 Ngõ 5 Láng Hạ",
  "newWard": "Phường Giảng Võ",
  "newWardCode": "00025",
  "newProvince": "Thành phố Hà Nội",
  "newProvinceCode": "01",
  "latitude": 21.0275,
  "longitude": 105.814,
  "oldWard": "Phường Thành Công",
  "oldDistrict": "Quận Ba Đình",
  "oldProvince": "Thành phố Hà Nội",
  "oldWardCode": "00034",
  "oldDistrictCode": "001",
  "oldProvinceCode": "01",
  "wardWasSplit": true,
  "candidateNewWards": ["Phường Giảng Võ", "Phường Ô Chợ Dừa"],
  "error": null
}

status	Meaning	Charged
converted	Old ward found and mapped to its new ward. confidence is high, or medium if the old ward was split.	Yes
already_new	The address already uses the 2025 units; it was recognised and standardised.	Yes
province_only	Only the province could be determined. If the old district was readable, candidateNewWards lists the new wards it spans.	Yes
not_found	No Vietnamese administrative unit recognised.	No

latitude and longitude are the centre of the new ward, not the exact street location. A run summary with counts per status is saved under OUTPUT in the key-value store.

How much does it cost?

You pay $2 per 1,000 converted addresses ($0.002 each), and nothing for addresses that are not recognised. There is no extra platform-usage charge on top. Converting a 100,000-row customer table costs about $200 and finishes in a couple of minutes.

To cap spending, set Maximum cost per run in the run options. The Actor stops cleanly when the limit is reached and the results produced so far are kept.

Integrations and API

• API: call run-sync-get-dataset-items to convert addresses and get the results in one HTTP request. See the API tab for ready-made code in Python, JavaScript and cURL.
• No-code: use the Apify integrations for Make, n8n, Zapier, Google Sheets and webhooks.
• AI agents: available through the Apify MCP server, so Claude, ChatGPT, Cursor and other MCP clients can convert addresses on request.
• Scraper pipelines: run it after a Google Maps or real-estate scraper with an Apify integration, passing the scraper's dataset as datasetId.

FAQ

Which official data is used? The mapping is the open, MIT-licensed vietnamadminunits dataset, which follows the National Assembly and government resolutions on the 2025 reorganisation. Codes follow the official administrative unit codes.

What happens when an old ward was split? You get the official default new ward in newWard, confidence: "medium", and all possible new wards in candidateNewWards. Check the street if the exact ward matters, for example for legal documents.

Does it verify that the street or house number exists? No. The street part is kept exactly as written. The Actor converts the administrative units only.

Is my data stored or shared? No external service is called. Data stays in your own Apify run storage, under your account's retention settings.

Can I convert addresses that are already in the new format? Yes. They come back as already_new with standardised names and codes, so mixed old and new data can go through in a single run.

Limitations

• Split wards return the official default; see candidateNewWards for the alternatives.
• Very short or ambiguous inputs (only a ward name with no province) may not be resolvable and return province_only or not_found.
• Coordinates are ward centroids.

Feedback and support

Found an address that was converted wrongly? Open an issue in the Issues tab with the input text and the expected result. Fixes are usually released within a few days.

---

Built on the MIT-licensed vietnamadminunits dataset and parser by Hieu Tran.