Convert Old Vietnamese Addresses to the New 2025 Format

Split a free-text Vietnamese address into street, ward and province, and convert old 3-level addresses (with district) to the new 2-level units of 2025.

Result

Press “Run” to see the result.

The address parser reads addresses as people type them: 123 Lê Lợi, P. Bến Thành, Q.1, TP.HCM, 45/2 Nguyễn Trãi, Phường 2, Quận 5, thon 3, xa ea tieu, huyen cu kuin, dak lak (without accents) or the new form Số 5 ngõ 10 phố Huế, Phường Hai Bà Trưng, Hà Nội. It recognises abbreviations (P., Q., TX., TT., TP., P3, Q10), old and new province names and aliases such as HCM or Sài Gòn, and splits the house number from the street.

The result is the current unit: since 1 July 2025 there are no districts, so an old address is converted through the official conversion table of the General Statistics Office: Phường 2, Quận 5 becomes Phường Chợ Quán, TP. Hồ Chí Minh; Phường Phú Cường, TP. Thủ Dầu Một, Bình Dương becomes Phường Thủ Dầu Một, TP. Hồ Chí Minh. The response gives the new ward and province with their codes and postal code, a ready-to-print full_address and, for converted addresses, the old unit in converted_from.

When an old ward was split between several new units, ambiguous is true and candidates lists them. Send up to 100 addresses at once with POST { "addresses": [...] }. The data is the same as the Vietnam provinces API and follows later resolutions.

Use this in your code

curl "https://apibox.io.vn/v1/address-parse?address=123 Lê Lợi, P. Bến Thành, Q.1, TP.HCM" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/address-parse?address=123 Lê Lợi, P. Bến Thành, Q.1, TP.HCM', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/address-parse?address=123 Lê Lợi, P. Bến Thành, Q.1, TP.HCM",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/address-parse?address=123 Lê Lợi, P. Bến Thành, Q.1, TP.HCM');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

API documentation → Get a free API key

FAQ

Does it work without accents?

Yes: names, prefixes and abbreviations are matched without accents or case, e.g. "p3, q10, hcm" or "xa ea tieu, huyen cu kuin, dak lak".

What if the old ward no longer exists?

Some wards were merged before 2025 or split in 2025. matched is false when nothing fits, and ambiguous with candidates when several new units are possible; the street decides.

Does it check that the street exists?

No. The street and house number are kept as written; only the administrative units are validated and converted.