Classes

enum VietNamDivisionType(value)

Vietnamese administrative division types.

Member Type:

str

Valid values are as follows:

TINH = <VietNamDivisionType.TINH: 'tỉnh'>

THANH_PHO_TRUNG_UONG = <VietNamDivisionType.THANH_PHO_TRUNG_UONG: 'thành phố trung ương'>

XA = <VietNamDivisionType.XA: 'xã'>

PHUONG = <VietNamDivisionType.PHUONG: 'phường'>

DAC_KHU = <VietNamDivisionType.DAC_KHU: 'đặc khu'>

class Province(name: str, code: ProvinceCode, division_type: VietNamDivisionType, codename: str, phone_code: int)

Province data type for post-2025 administrative divisions.

classmethod from_code(code: ProvinceCode) → Province

Look up a Province from code.

Parameters:

code – The province code

Returns:

The corresponding vietnam_provinces.Province object

Raises:

ValueError – If the province code is invalid

classmethod iter_all() → Iterator[Province]

Get iterator over all provinces.

Returns:

Iterator over all vietnam_provinces.Province objects

classmethod search(name: str = '') → tuple[Province, ...]

Search for provinces by name.

This method searches for provinces matching the given name with priority: 1. Exact match (case-sensitive, with diacritics) 2. Exact match (case-insensitive, with diacritics) 3. Exact match (normalized, no diacritics) 4. Partial match (earlier position is better)

If the input contains multiple words, all words must match.

Parameters:

name – Part of a province name to search for

Returns:

Tuple of matching vietnam_provinces.Province objects

classmethod search_from_legacy(name: str = '', code: int = 0) → tuple[ProvinceWithLegacy, ...]

Given a legacy province code or part of a legacy province name, return all matching provinces.

This method searches for current (post-2025) provinces that were formed from legacy (pre-2025) provinces matching the given criteria.

Parameters:

• name – Part of a legacy province name to search for

• code – The legacy province code

Returns:

Tuple of matching vietnam_provinces.ProvinceWithLegacy objects, each containing the matched legacy province code and resulting new province

Example:

>>> # Search by legacy province code
>>> Province.search_from_legacy(code=77)  # Tỉnh Bà Rịa - Vũng Tàu (old)
(ProvinceWithLegacy(source_code=77, province=Province(name='Thành phố Hồ Chí Minh', ...)),)

get_legacy_sources() → tuple[LegacyProvince, ...]

Get the legacy (pre-2025) province sources that were merged to form this province.

This method returns the legacy provinces that were merged or reorganized to form the current (post-2025) province.

Returns:

Tuple of legacy vietnam_provinces.legacy.Province objects

Example:

>>> province = Province.from_code(79)  # Thành phố Hồ Chí Minh
>>> province.get_legacy_sources()
(Province(name='Tỉnh Bình Dương', ...), Province(name='Tỉnh Bà Rịa - Vũng Tàu', ...),
 Province(name='Thành phố Hồ Chí Minh', ...))

class Ward(name: str, code: WardCode, division_type: VietNamDivisionType, codename: str, province_code: ProvinceCode)

Ward data type for post-2025 administrative divisions.

classmethod from_code(code: WardCode) → Ward

Look up a Ward from code.

Parameters:

code – The ward code

Returns:

The corresponding vietnam_provinces.Ward object

Raises:

ValueError – If the ward code is invalid

classmethod iter_all() → Iterator[Ward]

Get iterator over all wards.

Returns:

Iterator over all vietnam_provinces.Ward objects

classmethod iter_by_province(code: ProvinceCode) → Iterator[Ward]

Get iterator over wards belonging to a province.

Parameters:

code – The province code

Returns:

Iterator over vietnam_provinces.Ward objects belonging to the specified province

classmethod search(name: str = '') → tuple[Ward, ...]

Search for wards by name.

This method searches for wards matching the given name with priority: 1. Exact match (case-sensitive, with diacritics) 2. Exact match (case-insensitive, with diacritics) 3. Exact match (normalized, no diacritics) 4. Partial match (earlier position is better)

If the input contains multiple words, all words must match.

Parameters:

name – Part of a ward name to search for

Returns:

Tuple of matching vietnam_provinces.Ward objects

static search_from_legacy(name: str = '', code: int = 0) → tuple[WardWithLegacy, ...]

Given a legacy ward code or part of a legacy ward name, return all matching wards.

This method searches for current (post-2025) wards that were formed from legacy (pre-2025) wards matching the given criteria.

Parameters:

• name – Part of a legacy ward name to search for

• code – The legacy ward code

Returns:

Tuple of matching vietnam_provinces.WardWithLegacy objects, each containing the matched legacy ward code and resulting new ward

Example:

>>> # Search by legacy ward name
>>> Ward.search_from_legacy(name='phu my')
(WardWithLegacy(source_code=26740, ward=Ward(name='Phường Phú Mỹ', ...)), ...)

>>> # Search by legacy ward code
>>> Ward.search_from_legacy(code=22855)  # Xã Tân Hải
(WardWithLegacy(source_code=22855, ward=Ward(name='Xã Tân Hải', ...)),)

static search_from_legacy_district(name: str = '', code: int = 0) → tuple[WardWithLegacy, ...]

Given a legacy district code or part of a legacy district name, return all new wards.

This method searches for current (post-2025) wards that were formed from legacy (pre-2025) districts matching the given criteria. Since districts were dissolved in the 2025 administrative rearrangement, this helps find which new wards now cover the area of an old district.

Parameters:

• name – Part of a legacy district name to search for

• code – The legacy district code

Returns:

Tuple of matching vietnam_provinces.WardWithLegacy objects, each containing one legacy ward code from the matched district and resulting new ward

Example:

>>> # Search by legacy district code
>>> Ward.search_from_legacy_district(code=748)  # Thành phố Bà Rịa (old)
(WardWithLegacy(source_code=26710, ward=Ward(name='Phường Bà Rịa', ...)), ...)

>>> # Search by legacy district name
>>> Ward.search_from_legacy_district(name='Bà Rịa')
(WardWithLegacy(source_code=26710, ward=Ward(name='Phường Bà Rịa', ...)), ...)

get_legacy_sources() → tuple[LegacyWard, ...]

Get the legacy (pre-2025) ward sources that were merged to form this ward.

This method returns the legacy wards that were merged or reorganized to form the current (post-2025) ward.

Returns:

Tuple of legacy vietnam_provinces.legacy.Ward objects

Example:

>>> ward = Ward.from_code(4)  # Phường Ba Đình
>>> ward.get_legacy_sources()
(Ward(name='Phường Trúc Bạch', ...), Ward(name='Phường Quán Thánh', ...), ...)

>>> ward = Ward.from_code(22861)  # Xã Tân Hải
>>> ward.get_legacy_sources()
(Ward(name='Xã Tân Hải', ...),)