Vietnamese Provinces Database

A complete SQL (and also non-SQL) databases of Vietnamese administrative units, includes all 34 Vietnamese provinces and associated districts, wards sub-divisions.
Data is updated as of the most recent effective decree: 388/NQ-UBTVQH16
Add-on includes:

• GIS Dataset
• Postal Code Dataset

If you find this repository helpful, please consider giving it a ⭐ — it helps us stay motivated to keep improving and delivering valuable tools for the community. Also, starring the repo makes it easier to stay updated with future releases.

Overview

The author(s) of this repository is not associated with the General Statistics Office of Vietnam, nor the Vietnamese government.
The data of provinces and wards are created base on the API province data provided by the General Statistics Office of Vietnam website.

This dataset also include additional information apart from the original provinces, wards data from the original data. Please see section Additional change make by this repository.

Dataset releases and Government issued decrees

The Vietnamese Government may issue decree from time to time to adjust the administrative unit structure. You can track the latest issued decrees here.

The following table contains a list of issued decrees and their effective dates, tracked from the earliest version of this dataset.

Issued Decree/Description	Issued on	Effect from	Release Version
39/2026/QH16, 388/NQ-UBTVQH16	04/08/2026	20/09/2026	v5.2.0
36/2026/QH16; dataset metadata table for all formats	24/08/2026	01/09/2026	v5.1.0
Postal codes for all formats; Ba Chẽ ward code correction	---	---	v5.0.0
Add GIS dataset for ElasticSearch, MongoDB	---	---	v4.2.0
Add GeoJSON GIS, patch name, patch GIS province data of Da Nang and Khanh Hoa	---	---	v4.1.0
Add GIS dataset	---	---	v4.0.0
30/2026/QH16, 237/NQ-UBTVQH16	14/04/2026	30/04/2026	v3.1.0
19/2025/QĐ-TTg	30/06/2025	01/07/2025	v3.0.2
Grammar-correction, data cutoff before 19/2025/QĐ-TTg	15/01/2025	01/03/2025	v2.4.1
1365/NQ-UBTVQH15	15/01/2025	01/03/2025	v2.4.0
1318/NQ-UBTVQH15	30/11/2024	01/01/2025	v2.3.0
1203/NQ-UBTVQH15	28/09/2024	01/11/2024	v2.2.0
1106/NQ-UBTVQH15	23/07/2024	01/09/2024	v2.1.0
1013/NQ-UBTVQH15	19/03/2024	01/05/2024	v2.0.1
939/NQ-UBTVQH15	13/12/2023	01/02/2024	v2.0.0
From 721/NQ-UBTVQH15 to 730/NQ-UBTVQH15	13/02/2023	10/04/2023	v1.0.4.1
569/NQ-UBTVQH15, 570/NQ-UBTVQH15	11/08/2022	01/10/2022	v1.0.3.1
510/NQ-UBTVQH15	12/05/2022	01/07/2022	v1.0.2
469/NQ-UBTVQH15	15/02/2022	10/04/2022	v1.0.1
387/NQ-UBTVQH15	22/09/2021	01/11/2021	v1.0.0

Additional Changes Made by This Repository

• Added administrative_regions table
• Added administrative_units table
• Assigned administrative units to province and ward data
• Generated English names for provinces and wards, offering both full and short forms
• Generated code names (slugs) for provinces and wards
• Add-on: Additional GIS dataset and Postal Codes

Download

You can download a ready-to-use archive for your database or format below. Each archive contains the complete dataset folder of the latest release.

Archives are published for the latest release tag. Older versions remain available under their own version path on the CDN.

Dataset	Format	Version	Size	Download
PostgreSQL / PostGIS	SQL	v5.2.0	41.82 MB	vn_provinces_postgresql_dataset_v5.2.0.zip
MySQL / MariaDB	SQL	v5.2.0	40.70 MB	vn_provinces_mysql_dataset_v5.2.0.zip
Microsoft SQL Server	SQL	v5.2.0	41.84 MB	vn_provinces_sqlserver_dataset_v5.2.0.zip
Oracle	SQL	v5.2.0	88.43 KB	vn_provinces_oracle_dataset_v5.2.0.zip
JSON	JSON	v5.2.0	96.18 MB	vn_provinces_json_dataset_v5.2.0.zip
MongoDB	NoSQL	v5.2.0	46.10 MB	vn_provinces_mongodb_dataset_v5.2.0.zip
Redis	NoSQL	v5.2.0	170.17 KB	vn_provinces_redis_dataset_v5.2.0.zip
Elasticsearch	NoSQL	v5.2.0	42.91 MB	vn_provinces_elasticsearch_dataset_v5.2.0.zip

Installation

Create a database (if applicable):

CREATE DATABASE vietnamese_administrative_units;

Then execute the following scripts in order:

1. CreateTable_vn_units.sql – creates the database schema.
2. ImportData_vn_units.sql – imports the dataset.

Choose the scripts from the corresponding database directory:

Database	Directory
PostgreSQL	postgresql/
MySQL / MariaDB	mysql/
Microsoft SQL Server	sqlserver/
Oracle	oracle/

Oracle users may use an existing database/schema, as database creation is environment-specific.

Tables Schema

administrative_regions table

The administrative_regions table contains the list of 8 Vietnamese geographical regions with the id increment following the region location from North to South.

Table definition

Column	Data type	Meaning	Constraint
id	integer	Id of the region	Primary Key
name	varchar(255)	Region name in Vietnamese
name_en	varchar(255)	Region name in English
code_name	varchar(255)	Code name, derived from Vietnamese name, written in lowercase, underscored
code_name_en	varchar(255)	Code name, derived from English name, written in lowercase, underscored

Data preview

id	name	name_en	code_name	code_name_en
1	Đông Bắc Bộ	Northeast	dong_bac_bo	northest
2	Tây Bắc Bộ	Northwest	tay_bac_bo	northwest
3	Đồng bằng sông Hồng	Red River Delta	dong_bang_song_hong	red_river_delta
4	Bắc Trung Bộ	North Central Coast	bac_trung_bo	north_central_coast
5	Duyên hải Nam Trung Bộ	South Central Coast	duyen_hai_nam_trung_bo	south_central_coast
6	Tây Nguyên	Central Highlands	tay_nguyen	central_highlands
7	Đông Nam Bộ	Southeast	dong_nam_bo	southeast
8	Đồng bằng sông Cửu Long	Mekong River Delta	dong_bang_song_cuu_long	southwest

administrative_units table

The administrative_units table contains a list of administrative units with id sorted by two tier levels.

Table definition

Column	Data type	Meaning	Constraint
id	integer	Id of the administrative unit	Primary Key
full_name	varchar(255)	Full name of the administrative unit in Vietnamese
full_name_en	varchar(255)	Full name of the administrative unit in English
short_name	varchar(255)	Short name of the administrative unit in Vietnamese
short_name_en	varchar(255)	Short name of the administrative unit in English
code_name	varchar(255)	Code name, derived from Vietnamese full_name, written in lowercase, underscored
code_name_en	varchar(255)	Code name, derived from English full_name_en, written in lowercase, underscored

Data preview

id	full_name	full_name_en	short_name	short_name_en	code_name	code_name_en
1	Thành phố trực thuộc trung ương	Municipality	Thành phố	City	thanh_pho_truc_thuoc_trung_uong	municipality
2	Tỉnh	Province	Tỉnh	Province	tinh	province
3	Phường	Ward	Phường	Ward	phuong	ward
4	Xã	Commune	Xã	Commune	xa	commune
5	Đặc khu tại hải đảo	Special administrative region	Đặc khu	Special administrative region	dac_khu	special_administrative_region

provinces table

The provinces table contains a list of first administrative tier - the provincial level units, includes 34 municipalities and provinces.

Table definition

Column	Data type	Meaning	Constraint
code	varchar(20)	The official unit code, defined by government	Primary Key
name	varchar(255)	Name in Vietnamese
name_en	varchar(255)	Name of in English
full_name	varchar(255)	Full name in Vietnamese, includes the administrative unit name
full_name_en	varchar(255)	Full name in English, includes the administrative unit name
code_name	varchar(255)	Code name, derived from name, written in lowercase, underscored
administrative_unit_id	integer	The administrative unit id of this record	Foreign Key, references to administrative_units.id

Data preview

code	name	name_en	full_name	full_name_en	code_name	administrative_unit_id
01	Hà Nội	Ha Noi	Thành phố Hà Nội	Ha Noi City	ha_noi	1
56	Khánh Hòa	Khanh Hoa	Tỉnh Khánh Hòa	Khanh Hoa Province	khanh_hoa	2
79	Hồ Chí Minh	Ho Chi Minh	Thành phố Hồ Chí Minh	Ho Chi Minh City	ho_chi_minh	1
96	Cà Mau	Ca Mau	Tỉnh Cà Mau	Ca Mau Province	ca_mau	2
..	...........	...........	.....................	................	...........	..

wards table

The wards table contains a list of second administrative tier - the commune level units, includes 3321 wards, communes and special administrative region.

Table definition

Column	Data type	Meaning	Constraint
code	varchar(20)	The official unit code, defined by government	Primary Key
name	varchar(255)	Name in Vietnamese
name_en	varchar(255)	Name of in English
full_name	varchar(255)	Full name in Vietnamese, includes the administrative unit name
full_name_en	varchar(255)	Full name in English, includes the administrative unit name
code_name	varchar(255)	Code name, derived from name, written in lowercase, underscored
province_code	varchar(20)	The province this record belongs to	Foreign Key, references to provinces.code
administrative_unit_id	integer	The administrative unit id of this record	Foreign Key, references to administrative_units.id

Data preview

code	name	name_en	full_name	full_name_en	code_name	province_code	administrative_unit_id
25920	Tân Hiệp	Tan Hiep	Phường Tân Hiệp	Tan Hiep Ward	tan_hiep	79	3
25942	Dĩ An	Di An	Phường Dĩ An	Di An Ward	di_an	79	3
25945	Tân Đông Hiệp	Tan Dong Hiep	Phường Tân Đông Hiệp	Tan Dong Hiep Ward	tan_dong_hiep	79	3
25951	Đông Hòa	Dong Hoa	Phường Đông Hòa	Dong Hoa Ward	dong_hoa	79	3
25966	Lái Thiêu	Lai Thieu	Phường Lái Thiêu	Lai Thieu Ward	lai_thieu	79	3
25969	Thuận Giao	Thuan Giao	Phường Thuận Giao	Thuan Giao Ward	thuan_giao	79	3
25975	An Phú	An Phu	Phường An Phú	An Phu Ward	an_phu	79	3

vn_provinces_metadata table

The vn_provinces_metadata table is a single-row table that describes which release of the dataset is installed, so applications can detect the current version and know when an update is available.

Table definition

Column	Data type	Meaning
dataset_version	varchar(50)	Dataset release version (e.g. v5.1.0)
latest_decree	varchar(100)	Latest government decree reflected in the data (e.g. 36/2026/QH16)
generated_at	timestamp	Dataset generation timestamp (UTC)

Data preview

dataset_version	latest_decree	generated_at
v5.1.0	36/2026/QH16	2026-09-12 07:42:08

The same metadata is exported for the non-SQL formats: vn_provinces_metadata.json (JSON), the vn_provinces_metadata collection (MongoDB), the vnProvincesMetadata hash (Redis), and the vn_provinces_metadata index (Elasticsearch).

Sample Queries

You can easily create query to get all the kind of data you need since the tables are clearly referenced between each others.
Here is some sample queries to start with:

Get all wards under a province

Get all wards under Khánh Hoà province

SELECT w.code, w."name" , w.full_name , w.full_name_en ,au.full_name as administrative_unit_name
FROM wards w 
INNER JOIN administrative_units au 
ON w.administrative_unit_id = au.id
WHERE w.province_code = '56' -- Khanh Hoa province code
ORDER BY w.code;

code	name	full_name	full_name_en	administrative_unit_name
22333	Bắc Nha Trang	Phường Bắc Nha Trang	Bac Nha Trang Ward	Phường
22366	Nha Trang	Phường Nha Trang	Nha Trang Ward	Phường
22390	Tây Nha Trang	Phường Tây Nha Trang	Tay Nha Trang Ward	Phường
22402	Nam Nha Trang	Phường Nam Nha Trang	Nam Nha Trang Ward	Phường
22411	Bắc Cam Ranh	Phường Bắc Cam Ranh	Bac Cam Ranh Ward	Phường
22420	Cam Ranh	Phường Cam Ranh	Cam Ranh Ward	Phường
22423	Ba Ngòi	Phường Ba Ngòi	Ba Ngoi Ward	Phường
22432	Cam Linh	Phường Cam Linh	Cam Linh Ward	Phường

Get the installed dataset version

SELECT dataset_version, latest_decree, generated_at FROM vn_provinces_metadata;

Non-SQL Formats

Along with traditional SQL dataset, the Vietnamese Provinces Database also comes with non-sql data format, this includes

• JSON format (feature full, simplified and vn_only_simplified versions)
• MongoDB
• Redis

Add-ons

In addition to the administrative units dataset, this repository also includes optional add-on data extend its functionality.

GIS Dataset

The GIS add-on provides administrative boundary geometries for Vietnamese administrative units and is available for

• GeoJSON
• PostgreSQL/PostGIS
• MySQL
• Microsoft SQL Server
• ElasticSearch
• MongoDB

See GIS Dataset

FAQ

What is the original data source that this repository develope from?

The data of provinces and wards are created base on the API province data provided by the General Statistics Office of Vietnam website.

GIS boundary data was derived from the Vietnam Administrative Units Reference Map, published by the Vietnam Natural Resources, Environment and Cartography Publishing House under the Ministry of Agriculture and Environment.

How are the primary keys defined?

Table	Primary Key
administrative_regions	Key: id. Starting from 1 to 8, follow the geographical location order from North to South
administrative_units	Key: id. Starting from 1 to 5, follow the tier order from biggest unit to smallest unit
provinces	Key: code. Officially referenced from government unit code
wards	Key: code. Officially referenced from government unit code

Why use this repository instead of another administrative dataset/API Provider on the market?

The official administrative codes are defined by the Vietnamese government, so datasets generated from the same official source are generally compatible with each other.

The main difference is transparency and maintainability. Many public datasets eventually become outdated because they only publish the generated data. This repository also includes the complete data generation pipeline (dataset-generation-scripts), allowing anyone to inspect how the dataset is collected, cleaned, normalized, and exported. Every step is transparent and reproducible, making it easy to verify the data, customize the output, regenerate the latest dataset from the official source, and continue maintaining the project even if the original maintainer is no longer active.

Released under the MIT License — just use it. No fees. No permission required.

The province - administrative region relationship is dropped from v3.0.0?

After the provinces merge down to 37 provinces, the new province e.g: Phú Thọ, which is formed from Vĩnh Phúc, Phú Thọ and Hoà Bình that previously span across 3 different regions, so it's no longer applicable to determine which region does the new province belongs to.

Can I use this dataset in commercial projects?

Yes. Absolutely.
This dataset is released under the MIT License, allowing you to use, modify, and distribute it freely in both personal and commercial projects. No registration, permission request, or licensing fee is required.

If you find the project useful, consider giving it a star ⭐ on GitHub or contributing improvements back to the community.

This repository is an independent community project and is not affiliated with the General Statistics Office of Vietnam or any Vietnamese government agency. The dataset is provided “as is” without warranty of any kind.

I saw some issues in the SQL patch?

If you see any improvement that can be made, please kindly Open a issue and write down your finding. Or even better by Create a Pull Request. Any contribution is welcomed.

Reference

Vietnam Map in the banner by vietcentertourist

Contributors

It has been a long run to reach for the ⭐

This project has been around since 2022 and is still actively maintained today.
The continued support from the community — shown through stars, issues, and contributions — has been a big motivation to keep improving it. Thank you for helping this project grow!