Vietnam Provinces & Wards Lookup 2025

All 34 provinces and 3,321 phường / xã / đặc khu of Vietnam after the 07/2025 reorganisation, with codes, postal codes, search and old → new unit conversion.

Result

Press “Run” to see the result.

Since 1 July 2025 Vietnam has 34 provinces and cities and no district level: each province is divided directly into phường (wards), xã (communes) and đặc khu (special zones). This API returns that structure with the official codes of the General Statistics Office, Vietnamese and English names, unit types and postal codes, ready to fill address forms and validate addresses. Later changes (for example communes upgraded to wards in 2026) are included; the response shows the dataset version and the latest resolution it covers.

GET /v1/vn-provinces lists the provinces with their number of units and what they were formed from; /v1/vn-provinces/{code} (or a name such as hcm, Hà Nội) returns one province with all its wards, filterable by type=ward|commune|special_zone. /v1/vn-provinces/wards/{code} returns one unit with the list of pre-2025 wards/communes it was formed from, including their old district and province.

To convert old addresses, old_ward={old code} tells you which new unit(s) an old ward or commune went to (a few were split), and q= searches names without accents (q=thu dau mot). When a name no longer exists, the search also looks in the old names and says where they went. Data comes from the GSO conversion table and the open dataset of github.com/ThangLeQuoc/vietnamese-provinces-database (MIT) and is refreshed when new resolutions are published.

Use this in your code

curl "https://apibox.io.vn/v1/vn-provinces?old_ward=00013" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-provinces?old_ward=00013', {
  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/vn-provinces?old_ward=00013",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-provinces?old_ward=00013');
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

How do I convert an old address?

If you have the old ward / commune code, call ?old_ward=00013: the response gives the new unit (Phường Ba Đình for the old Phường Quán Thánh). With only the name, call ?q=Quán Thánh&match_old=true and filter by province.

How up to date is the data?

It follows the official list after 1/7/2025 and later National Assembly Standing Committee resolutions; every response contains version, decree (the latest resolution included) and updated. We rebuild the data when the upstream dataset changes.

Why are there no districts?

The district level (quận, huyện, thị xã) was abolished on 1 July 2025. Old district names and codes still appear in formed_from, to help with conversion.