Vietnam Provinces & Wards API

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.

GEThttps://apibox.io.vn/v1/vn-provinces

Data & JSON▶ Try it online

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.

Parameters

Name	In	Type	Required	Default
`code`	path	string	no		`/v1/vn-provinces/{code}`: 2-digit province code or name (`79`, `hcm`, `Hà Nội`). Alias: `province` query.
`ward`	query	string	no		Ward / commune code (5 digits), same as `/v1/vn-provinces/wards/{code}`.
`q`	query	string	no		Search provinces and wards by name, accents optional. Combine with `province` and `limit` (max 100).
`match_old`	query	boolean	no	`false`	With `q`: also search pre-2025 names (always done when nothing current matches).
`old_ward`	query	string	no		Pre-2025 ward / commune code → the new unit(s) it became part of.
`type`	query	string	no		Filter the wards of a province: `ward`, `commune` or `special_zone`.
`formed_from`	query	boolean	no	`false`	Include the old units each ward was formed from in lists and search results.

Example

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));

Response

{
  "version": "v5.2.0",
  "decree": "388/NQ-UBTVQH16",
  "updated": "2026-09-20",
  "old": {
    "code": "00013",
    "name": "Phường Quán Thánh",
    "change": "Nhập toàn bộ",
    "district": "Quận Ba Đình",
    "district_code": "001",
    "province": "Thành phố Hà Nội",
    "province_code": "01"
  },
  "split": false,
  "new": [
    {
      "code": "00004",
      "name": "Ba Đình",
      "full_name": "Phường Ba Đình",
      "name_en": "Ba Dinh",
      "type": "Phường",
      "type_en": "ward",
      "slug": "ba_dinh",
      "postal_code": "11120",
      "province_code": "01",
      "province": "Hà Nội",
      "change": "Nhập toàn bộ"
    }
  ]
}

Use cases

Province → ward dropdowns in checkout and sign-up forms
Convert customer addresses from the old 3-level to the new 2-level structure
Validate and normalise shipping addresses before sending to carriers
Show statistics or maps by the new provinces

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.

Related APIs

{✓}

Vietnam Provinces & Wards API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON