Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ The following table contains a list of issued decrees and their effective dates,

|Issued Decree/Description|Issued on |Effect from|Release Version|
|-------------|-----------|-------------|---------------|
|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][decree 30/2026/QH16], [237/NQ-UBTVQH16][decree 237/NQ-UBTVQH16]|14/04/2026|30/04/2026|v3.1.0|
|[19/2025/QĐ-TTg][decree 19/2025/QĐ-TTg]|30/06/2025|01/07/2025|v3.0.2|
Expand Down Expand Up @@ -266,6 +267,14 @@ GIS boundary data was derived from the [Vietnam Administrative Units Reference M
|`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.
Expand Down
9 changes: 9 additions & 0 deletions README_vi.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ Bảng dưới thông kê các nghị định đã được ban hành, cùng th

|Nghị định/Mô tả|Ngày ban hành|Ngày có hiệu lực|Phiên bản|
|-------------|-----------|-------------|---------------|
|Thêm định dạng GIS GeoJSON, vá tên tiếng Anh, vá dữ liệu GIS của tỉnh Đà Nẵng và Khánh Hòa|---|---|v4.1.0|
|Thêm dữ liệu GIS|---|---|v4.0.0|
|[30/2026/QH16][decree 30/2026/QH16], [237/NQ-UBTVQH16][decree 237/NQ-UBTVQH16]|14/04/2026|30/04/2026|v3.1.0|
|[19/2025/QĐ-TTg][decree 19/2025/QĐ-TTg]|30/06/2025|01/07/2025|v3.0.2|
Expand Down Expand Up @@ -263,6 +264,14 @@ Dữ liệu ranh giới GIS được xây dựng dựa trên dữ liệu từ [B
|`provinces`|Khoá chính: `code`. Được quy ước theo đối tượng **Tỉnh thành** do chính phủ ban hành
|`wards`|Khoá chính: `code`. Được quy ước theo đối tượng **Phường xã** do chính phủ ban hành

### Sao không dùng API từ nhà cung cấp khác, hay dataset khác trên thị trường?

Mã đơn vị hành chính được Chính phủ Việt Nam quy định thống nhất, vì vậy các bộ dữ liệu được xây dựng từ cùng một nguồn dữ liệu chính thức nhìn chung đều tương thích với nhau.

Điểm khác biệt lớn nhất của repository này là tính minh bạch của mã nguồn và khả năng duy trì lâu dài. Nhiều bộ dữ liệu công khai khác dần trở nên lỗi thời theo thời gian vì chỉ phát hành dữ liệu đã được sinh sẵn. Repository này công khai toàn bộ quy trình sinh dữ liệu (dataset-generation-scripts), giúp mọi người có thể xem chính xác cách dữ liệu được thu thập, làm sạch, chuẩn hóa và xuất ra. Mọi bước đều minh bạch và có thể tái tạo, giúp bạn dễ dàng kiểm chứng dữ liệu, tùy biến theo nhu cầu, tạo lại dataset mới nhất từ nguồn dữ liệu chính thức, hoặc tiếp tục duy trì dự án ngay cả khi tác giả ban đầu không còn hoạt động nữa.

Repository được phát hành theo MIT License — cứ clone về dùng thôi. Bạn không mất phí, và không cần phải xin phép ai để sử dụng.

### Tại sao mối quan hệ giữa tỉnh và vùng hành chính (region) bị loại bỏ từ phiên bản v3.0.0?

Sau khi số lượng tỉnh được sáp nhập còn 37, các tỉnh mới — chẳng hạn như Phú Thọ, được hình thành từ Vĩnh Phúc, Phú Thọ và Hòa Bình — hiện nay trải dài trên nhiều vùng hành chính trước đây. Do các tỉnh cũ thuộc các vùng khác nhau, nên việc xác định vùng hành chính cho tỉnh mới không còn chính xác nữa.
Expand Down
19 changes: 10 additions & 9 deletions docs/gis/gis_readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,13 @@
|PostgreSQL/PostGIS|[Download raw GIS Dataset for PostgreSQL][gis_dataset_postgresql_bucket_url]|~152.07 MB|
|MySQL|[Download raw GIS Dataset for MySQL][gis_dataset_mysql_bucket_url]|~150.44 MB|
|Microsoft SQL Server|[Download raw GIS Dataset for SQL Server][gis_dataset_sqlserver_bucket_url]|~152.13 MB|
|GeoJSON| Access the geojson data in the `json/geojson/` folder of this repository | - |

## Table of Contents

1. [Introduction](#introduction)
2. [Dataset Coverage](#dataset-coverage)
3. [GeoJSON Export](#geojson-export)
3. [GeoJSON](#geojson)
4. [Installation](#installation)
5. [Database Schema](#database-schema)
6. [Query Optimization Tips](#query-optimization-tips)
Expand Down Expand Up @@ -408,11 +409,11 @@ Typical workflow:

**A**: Yes. The following tools work well with the GIS dataset:

|Tool Type Recommendation
|------|--------|---------------|
|DBeaver| Database Client| Recommended for most users. Supports PostgreSQL, MySQL, and SQL Server, and can preview geometry data directly on an OpenStreetMap-based map viewer.
|QGIS| Desktop GIS| Best for advanced GIS analysis, spatial editing, and cartographic visualization.
|geojson.io| Web Viewer| Lightweight online tool for visualizing and debugging the published GeoJSON export.
| Tool | Type | Recommendation |
|------|------|---------------|
| DBeaver | Database Client | Recommended for most users. Supports PostgreSQL, MySQL, and SQL Server, and can preview geometry data directly on an OpenStreetMap-based map viewer. |
| QGIS | Desktop GIS | Best for advanced GIS analysis, spatial editing, and cartographic visualization. |
| geojson.io | Web Viewer | Lightweight online tool for visualizing and debugging the published GeoJSON export. |

Example: Visualize Geometry in DBeaver
[![image.png](https://i.postimg.cc/dVmQJSFg/image.png)](https://postimg.cc/k2GPcsBy)
Expand Down Expand Up @@ -449,6 +450,6 @@ If you find issues with the GIS dataset or have suggestions for improvements, pl

**Last Updated:** June 20, 2026

[gis_dataset_postgresql_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.0.0/GISDataSet/postgresql_ImportData_gis_2026-06-20__12_32_01.sql
[gis_dataset_mysql_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.0.0/GISDataSet/mysql_ImportData_gis_2026-06-20__12_32_01.sql
[gis_dataset_sqlserver_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.0.0/GISDataSet/mssql_ImportData_gis_2026-06-20__12_32_02.sql
[gis_dataset_postgresql_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.1.0/GISDataSet/postgresql_ImportData_gis_2026-07-12__19_50_50.sql
[gis_dataset_mysql_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.1.0/GISDataSet/mysql_ImportData_gis_2026-07-12__19_50_50.sql
[gis_dataset_sqlserver_bucket_url]: https://vn-provinces-ds.thanglequoc.xyz/v4.1.0/GISDataSet/mssql_ImportData_gis_2026-07-12__19_50_51.sql
Loading
Loading