vietnam-address-converter 1.0.2

Convert Vietnamese administrative addresses from the old district-based format to the 2025 normalized structure.

Vietnam Administrative Address Converter

Convert Vietnamese administrative addresses from the old province / district / ward structure to the 2025 normalized province / ward structure.

---

Features

• Parse free-form Vietnamese addresses in the old administrative format.
• Convert old province/district/ward references into the new province/ward format.
• Normalize large CSV datasets in streaming mode.
• Reuse an in-memory converter with caching for better batch performance.

---

Package Name

• PyPI distribution: vietnam-address-converter
• Python import: vietnam_address_converter
• CLI command: vietnam-address-converter

---

Installation

From source

git clone https://github.com/trng28/address-converter.git
cd address-converter

python -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

pip install -e .

From PyPI

pip install vietnam-address-converter

Development-only test dependencies

pip install -r requirements.txt

---

CLI Usage

Convert one address

vietnam-address-converter --address "Đường Trần Não, Phường Thảo Điền, TP Thủ Đức, Thành phố Hồ Chí Minh"

Run as a module

python -m vietnam_address_converter --address "Đường Trần Não, Phường Thảo Điền, TP Thủ Đức, Thành phố Hồ Chí Minh"

Convert a CSV file

vietnam-address-converter \
  --input-csv data/vietnam_full_address.csv \
  --output-csv data/vietnam_full_address.converted.csv \
  --address-column full_address \
  --cache-size 4096

Output schema:

index,full_address,street,ward,district,city,full_address_new

---

Python API

from vietnam_address_converter import auto_convert_address, create_converter

result = auto_convert_address(
    "Đường Trần Não, Phường Thảo Điền, TP Thủ Đức, Thành phố Hồ Chí Minh"
)

converter = create_converter()
batch_result = converter.auto_convert_address(
    "Quốc lộ 91C, Xã Đa Phước, Huyện An Phú, Tỉnh An Giang"
)

---

Dataset

This project uses the public dataset:

• trucmtnguyen/vietnam-address-collection

Download example:

pip install huggingface_hub
python -c "
from huggingface_hub import hf_hub_download
hf_hub_download(
    repo_id='trucmtnguyen/vietnam-address-collection',
    filename='vietnam_full_address.csv',
    repo_type='dataset',
    local_dir='data/'
)
"

---

Performance

Validated on 79,931 real addresses from the full dataset.

---

Project Structure

address-converter/
├── .github/
│   └── workflows/
├── data/
├── docs/
│   └── assets/
├── src/
│   ├── vietnam_address_converter/  # installable Python package
│   ├── batch.py                    # compatibility wrappers for old imports
│   ├── converter.py
│   └── ...
├── tests/
├── pyproject.toml
├── main.py
├── README.md
└── requirements.txt

---

Release Flow

• CI runs on every push and pull request.
• Create a tag like v0.1.0 to trigger the release workflow.
• Release artifacts include both .whl and .tar.gz.

---

License

Apache 2.0 © trng28