Vietnam Postcode Lookup

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.

Result

Press “Run” to see the result.

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.

Use this in your code

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

API documentation → Get a free API key

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.