Vietnam Postcodes API

Find the 5-digit Vietnamese postcode of any new phường / xã (QĐ 2334/QĐ-BKHCN, 2025), list a province's codes, or check which ward a code belongs to.

GEThttps://apibox.io.vn/v1/vn-postcode/{code}

Data & JSON▶ Try it online

The postcode API covers the national postcode system (Mã bưu chính quốc gia, Quyết định 2475/QĐ-BTTTT) as amended for the 2025 reorganisation by Quyết định 2334/QĐ-BKHCN of 24 August 2025: 34 provinces and about 3,300 phường, xã and đặc khu, each with its own 5-digit code. Send a code (/v1/vn-postcode/11120) to see whether it is assigned to a ward and which province owns its range, a prefix (711) to list the codes under it, a ward name with q (accents optional, ben thanh), optionally with province, or province alone to list every ward code of a province.

A valid code that no ward uses is reported with assigned_to_ward: false (post offices and large customers have their own codes); 6-digit codes from before 2018 are rejected. Names and ward codes follow our administrative-units data (/v1/vn-provinces), rebuilt weekly from official sources.

Parameters

Name	In	Type	Required	Default
`code`	path\|query	string	no		5-digit postcode, or a 2–4 digit prefix.
`q`	query	string	no		Ward / commune name, accents optional.
`province`	query	string	no		Province name or 2-digit code (`79`, `Hà Nội`, `hcm`).
`limit`	query	number	no	`50`	Maximum wards returned (1–500).

Example

curl "https://apibox.io.vn/v1/vn-postcode/11120" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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

{
  "code": "11120",
  "valid_format": true,
  "assigned_to_ward": true,
  "province": {
    "code": "01",
    "name": "Thành phố Hà Nội",
    "postcode_prefixes": [
      "10",
      "11",
      "12",
      "13",
      "14"
    ]
  },
  "wards": [
    {
      "postal_code": "11120",
      "ward": "Phường Ba Đình",
      "ward_code": "00004",
      "province": "Thành phố Hà Nội",
      "province_code": "01"
    }
  ],
  "note": null,
  "decision": "2475/QĐ-BTTTT",
  "decision_date": "2017-12-29",
  "amended_by": "2334/QĐ-BKHCN",
  "amended_on": "2025-08-24",
  "effective_from": "2025-08-24",
  "structure": "NNXXX: 5 digits. NN = province (some provinces own several 2-digit ranges after the 2025 merger); the full 5 digits = a phường / xã / đặc khu, or a post office / special customer.",
  "reviewed": "2026-11-11"
}

Use cases

Fill the ZIP field of international checkout forms
Validate postcodes in shipping and logistics systems
Suggest the postcode after the user picks a ward
Clean addresses in CRM or bank onboarding data

FAQ

Are these the codes after the 2025 merger?

Yes: the ward-level codes of Decision 2334/QD-BKHCN (24/08/2025) for the new phường / xã / đặc khu.

Why does a province have several 2-digit prefixes?

Merged provinces kept the ranges of the provinces they were formed from, e.g. Hồ Chí Minh City uses 70–75 and 78.

Can a code be valid but not belong to a ward?

Yes: post offices, government bodies and large customers get their own codes inside the province range; the API says assigned_to_ward: false.

Related APIs

{✓}

Vietnam Postcodes API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON