Vietnamese Address Parser API
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.
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.
Parameters
| Name | In | Type | Required | Default | |
|---|---|---|---|---|---|
address | body|query | string | yes | Free-text address (max 500 characters). | |
addresses | body | array | no | Up to 100 addresses at once (POST JSON). |
Example
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));Response
{
"version": "v5.2.0",
"decree": "388/NQ-UBTVQH16",
"updated": "2026-09-20",
"input": "123 Lê Lợi, P. Bến Thành, Q.1, TP.HCM",
"parsed": {
"house_number": "123",
"street": "Lê Lợi",
"ward": "P. Bến Thành",
"district": "Q.1",
"province": "TP.HCM"
},
"format": "old (before 07/2025)",
"matched": true,
"ambiguous": false,
"result": {
"ward": "Phường Bến Thành",
"ward_code": "26743",
"province": "Thành phố Hồ Chí Minh",
"province_code": "79",
"postal_code": "71009",
"full_address": "123 Lê Lợi, Phường Bến Thành, Thành phố Hồ Chí Minh",
"converted_from": {
"code": "26743",
"name": "Phường Bến Thành",
"change": "Nhập toàn bộ",
"district": "Quận 1",
"district_code": "760",
"province": "Thành phố Hồ Chí Minh",
"province_code": "79"
}
}
}Use cases
- Clean customer addresses in CRM and e-commerce databases
- Convert old addresses for shipping labels and invoices after the 2025 merger
- Fill province / ward dropdowns from a pasted address
- Group orders by the new provinces
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.
Related APIs
JSON Validator
Check JSON syntax with exact line and column of errors, and validate data against a JSON Schema (draft 4, 7, 2019-09 or 2020-12).
{ }JSON Formatter
Pretty print JSON with 0-8 spaces or tabs, minify it, or sort object keys recursively. Syntax errors are reported with line and column.
CSVCSV to JSON
Convert CSV into an array of JSON objects using the header row, with delimiter auto-detection, number and boolean typing, and row-level errors.