vietnamese-address-parser 0.1.9

No project description provided

vietnamese_address_parser is an experimental library for parsing and normalizing Vietnamese addresses, used in our search and data scraping tools.

---

Installation

pip install vietnamese_address_parser

---

⚠️ API Note

This parser integrates with the OpenStreetMap Nominatim API to enhance address accuracy through geolocation. Because of this, some lookups may take a few seconds to complete, depending on network speed and API rate limits.

---

Usage in Python

Import and use the parser in your Python code:

from vietnamese_address_parser import VietnameseAddressParser

parser = VietnameseAddressParser()
address = "Đường XVNT, P 17, Quận BT, TP. HCM, VN"
result = parser(address)
print(result)

result:

Đường Xô Viết Nghệ Tĩnh, Phường 17, Quận Bình Thạnh, Thành Phố Hồ Chí Minh, Việt Nam

---

General Notes

• Keep abbreviations to two segments or fewer for best search performance.
• Separate all address components with commas, in this order:
• Maximun field length is 6

{dia_chi}, {extra_field}, {phuong_xa}, {quan_huyen}, {tinh_thanh_pho}, {Việt Nam}

Valid address example

1. TP. VT, Tỉnh BR-VT
2. Đường XVNT, Quận Bình Thạnh, TP. HCM, VN
3. Đường Lê Lợi, P.1, Q.1, TP. HCM
4. 67 Trần Kế Xương, Q. PN, TP. HCM
5. 218 Trần Quý Cáp, X. TL, TP. PT, Tỉnh Bình Thuận
6. Phú Thạnh, Tân Phú, Hồ Chí Minh, Việt Nam
7. 218 Tran Quy Cap, Thanh pho Phan Thiet, Tinh Binh Thuan
8. 43/47 Cù Chính Lan, Thanh Khê Đông, TK, ĐN

---

CLI Usage

When you run the command:

vietnamese_address_parser

it will print:

Vietnamese Address Parser v0.1.7
Hello! Welcome to the Vietnamese Address Parser CLI.
Usage example:
    parser = VietnameseAddressParser()
    result = parser("54-55 Bàu Cát 4, Phường 14, Tân Bình, Hồ Chí Minh")
    print(result)
⚠️ NOTE:
This parser uses the OpenStreetMap Nominatim API for geolocation enhancement.
As a result, some lookups may take a few seconds due to network latency or rate limits

---

1. House Number & Street Name

Format

{house_number}\s{prefix?}\.?\s{street_name}

where {prefix} is one of:

• Đ.
• Đường

or just

{house_number}\s{street_name}

Valid Examples

• 123A/32 Trần Hưng Đạo
• 45A đường Nguyễn Huệ
• Đường Nam Kỳ Khởi Nghĩa
• Đ. XVNT

Invalid:

• Nam Kỳ Khởi Nghĩa (missing “Đường” prefix)

---

2. Phường / Xã

Format Options

{prefix}\.?\s{phuong_xa}

where {prefix} is one of:

• X.
• Xa
• P.
• Phuong
• TT.
• Thi tran

or just

{phuong_xa}

Valid Examples

• P. 7
• P. BN
• P. Bến Nghé
• Phường Bến Nghé

---

3. Quận / Huyện / Thị xã

Format Options

{prefix}\.?\s{quan_huyen}

where {prefix} is one of:

• Q.
• Quan
• H.
• Huyen
• TX.
• Thi xa

or just

{quan_huyen}

---

4. Tỉnh / Thành Phố

Format Options

{prefix}\.?\s{tinh_thanh_pho}

where {prefix} is one of:

• T.
• Tỉnh
• TP.
• Thanh pho

or just

{tinh_thanh_pho}

---

End of Guide.