PHPackages                             nguyenary/vietnam-address-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. nguyenary/vietnam-address-api

ActiveLibrary[Utility & Helpers](/categories/utility)

nguyenary/vietnam-address-api
=============================

Một thư viện được viết bằng PHP để lấy thông tin các đơn vị hành chính Việt Nam (Tỉnh, Thành Phố, Quận, Huyện, Xã, Phường, Thị Trấn...)

v2.1(4y ago)253017MITPHPPHP >=7.2

Since Aug 21Pushed 3y ago1 watchersCompare

[ Source](https://github.com/nguyenary/VietnamAddressAPI)[ Packagist](https://packagist.org/packages/nguyenary/vietnam-address-api)[ RSS](/packages/nguyenary-vietnam-address-api/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (4)Dependencies (3)Versions (7)Used By (0)

Đơn Vị Hành Chính Việt Nam
==========================

[](#đơn-vị-hành-chính-việt-nam)

> Thư viện được viết bằng PHP để lấy thông tin các đơn vị hành chính Việt Nam (Tỉnh, Thành Phố, Quận, Huyện, Xã, Phường, Thị Trấn...)

Installation
------------

[](#installation)

Install sử dụng `composer`

```
composer require nguyenary/vietnam-address-api
```

Usage
-----

[](#usage)

### **1. Cách Update Data Đơn Vị Hành Chính Việt Nam (*nếu có thay đổi*)**

[](#1-cách-update-data-đơn-vị-hành-chính-việt-nam-nếu-có-thay-đổi)

Nếu trong tương lai dữ liệu ***Đơn Vị Hành Chính Việt Nam*** có thay đổi thông tin (Quận, Huyện, Xã, Phường..v..v) bạn có thể chủ động update lại dữ liệu bằng cách dưới đây.

Dữ liệu được xuất từ các file `excel` tải từ địa chỉ: [https://danhmuchanhchinh.gso.gov.vn/](https://danhmuchanhchinh.gso.gov.vn)

**Cách để tải file `excel`**

Ví dụ dưới đây là cách tải file `excel` đơn vị hành chính của thành phố Hà Nội

[![Cách tải file excel](screenshot/screenshot_2.gif)](screenshot/screenshot_2.gif)

**Cách để tải file `excel` tất cả các địa danh bằng `script`**

Hãy copy code trong file `download-script.js` và truy cập vào địa chỉ trên. Nhấn `Ctrl + Shift + I` để mở `console` và paste đoạn code vào đây rồi enter kết quả sẽ như hình.

[![Cách tải file excel](screenshot/screenshot_1.gif)](screenshot/screenshot_1.gif)

File `excel` được lưu trong folder `excel_files`

Để update dữ liệu mới cho Đơn Vị Hành Chính hãy bỏ file `excel` đã tải vào folder này và tiến hành chạy lệnh:

```
cd vendor/nguyenary/vietnam-address-api
php export.php
```

Sẽ được kết quả như sau:

[![Chạy lệnh php export.php](screenshot/screenshot_3.gif)](screenshot/screenshot_3.gif)

Vậy là bạn đã tự update lại dữ liệu Đơn Vị Hành Chính thành công!

> Hoặc bạn có thể tạo `issues` trong project để báo cáo vấn đề về dữ liệu đang gặp phải hoặc chủ động tạo `pull requests` để đóng góp bản cập nhật dữ liệu mới cho project này.

### **2. Cách Sử Dụng Trong Dự Án**

[](#2-cách-sử-dụng-trong-dự-án)

```
require 'vendor/autoload.php';

use NguyenAry\VietnamAddressAPI\Address;
```

Xem ví dụ cụ thể tham khảo file `example.php`

#### ***`Address::getProvinces()`***

[](#addressgetprovinces)

> Lấy tất cả Tỉnh / Thành Phố của Việt Nam

- Option:
    - province\_ids (array) : Mảng chứa danh sách province\_id muốn lấy

#### ***`Address::getProvince()`***

[](#addressgetprovince)

> Lấy thông tin của một Tỉnh, Thành Phố theo `province_id`

- Require:
    - province\_id (string) : province\_id của Tỉnh / Thành Phố muốn lấy thông tin

#### ***`Address::getDistrictsByProvinceId()`***

[](#addressgetdistrictsbyprovinceid)

> Lấy danh sách Quận / Huyện của một Tỉnh / Thành Phố bằng `province_id`

- Require:
    - province\_id (string) : province\_id của Tỉnh / Thành Phố để lấy danh sách các Quận / Huyện của nó

#### ***`Address::getDistrict()`***

[](#addressgetdistrict)

> Lấy thông tin của Quận / Huyện bằng `district_id`

- Require:
    - district\_id (string) : district\_id của Quận / Huyện cần lấy thông tin

#### ***`Address::getWardsByDistrictId()`***

[](#addressgetwardsbydistrictid)

> Lấy danh sách Xã / Phường / Thị Trấn của một Quận / Huyện bằng `district_id`

- Require:
    - district\_id (string) : district\_id của Quận / Huyện để lấy danh sách Xã / Phường / Thị Trấn của nó

#### ***`Address::getWard()`***

[](#addressgetward)

> Lấy thông tin Xã / Phường / Thị Trấn bằng `distric_id` và `ward_id`

- Require:
    - district\_id (string) : district\_id của Quận / Huyện chứa Xã / Phường / Thị Trấn cần lấy thông tin
    - ward\_id (string) : ward\_id của Xã / Phường / Thị Trấn cần lấy thông tin

#### ***`Address::setSchema()`***

[](#addresssetschema)

> Định dạng lại các trường sẽ trả về. Gọi hàm này trước khi gọi các phương thức `get` ở trên (Mặc định sẽ trả về tất cả)

- Option:
    - schema (array) : Mảng chứa danh sách các trường cần lấy (Vd: name, type, code,...v..v)

#### Project này có tái sử dụng code từ: [madnh/hanhchinhvn](https://github.com/madnh/hanhchinhvn)

[](#project-này-có-tái-sử-dụng-code-từ-madnhhanhchinhvn)

###  Health Score

29

—

LowBetter than 57% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity23

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 95.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

4

Last Release

1765d ago

Major Versions

v1.1 → v2.02021-08-25

### Community

Maintainers

![](https://www.gravatar.com/avatar/072424c6d388b6a9f8d429a4157691c205704fcf34c5410c4d5123ca7ff73207?d=identicon)[nguyenary](/maintainers/nguyenary)

---

Top Contributors

[![nguyenary](https://avatars.githubusercontent.com/u/7163751?v=4)](https://github.com/nguyenary "nguyenary (23 commits)")[![harrycode99](https://avatars.githubusercontent.com/u/110017702?v=4)](https://github.com/harrycode99 "harrycode99 (1 commits)")

---

Tags

administrative-unit-of-vietnamhanhchinhvnvietnam-addressvietnam-address-apivietnam-administration-division

### Embed Badge

![Health badge](/badges/nguyenary-vietnam-address-api/health.svg)

```
[![Health](https://phpackages.com/badges/nguyenary-vietnam-address-api/health.svg)](https://phpackages.com/packages/nguyenary-vietnam-address-api)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M2.9k](/packages/craftcms-cms)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

749284.3k35](/packages/civicrm-civicrm-core)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[cognesy/instructor-php

The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control

318117.1k1](/packages/cognesy-instructor-php)[terminal42/contao-mp_forms

An extension for Contao Open Source CMS to create multi steps forms using the form generator

2534.7k6](/packages/terminal42-contao-mp-forms)[cpsit/project-builder

Composer package to create new projects from project templates

2538.4k2](/packages/cpsit-project-builder)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)