Base Types

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

Bases: object

Province data type for pre-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.legacy.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.legacy.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 as whole words.

Parameters:

name – Part of a province name to search for

Returns:

Tuple of matching vietnam_provinces.legacy.Province objects

name: str

code: ProvinceCode

division_type: VietNamDivisionType

codename: str

phone_code: int

class District(name: str, code: DistrictCode, division_type: VietNamDivisionType, codename: str, province_code: ProvinceCode)

Bases: object

District data type for pre-2025 administrative divisions.

classmethod from_code(code: DistrictCode) → District

Look up a District from code.

Parameters:

code – The district code

Returns:

The corresponding vietnam_provinces.legacy.District object

Raises:

ValueError – If the district code is invalid

classmethod iter_all() → Iterator[District]

Get iterator over all districts.

Returns:

Iterator over all vietnam_provinces.legacy.District objects

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

Get iterator over districts belonging to a province.

Parameters:

code – The province code (vietnam_provinces.legacy.ProvinceCode)

Returns:

Iterator over vietnam_provinces.legacy.District objects belonging to the specified province

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

Search for districts by name.

This method searches for districts 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 as whole words.

Parameters:

name – Part of a district name to search for

Returns:

Tuple of matching vietnam_provinces.legacy.District objects

name: str

code: DistrictCode

division_type: VietNamDivisionType

codename: str

province_code: ProvinceCode

class Ward(name: str, code: WardCode, division_type: VietNamDivisionType, codename: str, district_code: DistrictCode)

Bases: object

Ward data type for pre-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.legacy.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.legacy.Ward objects

classmethod iter_by_district(code: DistrictCode) → Iterator[Ward]

Get iterator over wards belonging to a district.

Parameters:

code – The district code (vietnam_provinces.legacy.DistrictCode)

Returns:

Iterator over vietnam_provinces.legacy.Ward objects belonging to the specified district

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

Get iterator over wards belonging to a province.

Parameters:

code – The province code (vietnam_provinces.legacy.ProvinceCode)

Returns:

Iterator over vietnam_provinces.legacy.Ward objects belonging to the specified province

property province_code: ProvinceCode

Get the province code for this ward (via district).

Returns:

The province code (vietnam_provinces.legacy.ProvinceCode)

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 as whole words.

Parameters:

name – Part of a ward name to search for

Returns:

Tuple of matching vietnam_provinces.legacy.Ward objects

name: str

code: WardCode

division_type: VietNamDivisionType

codename: str

district_code: DistrictCode

enum VietNamDivisionType(value)

Bases: StrEnum

Division types for pre-2025 administrative units.

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'>

HUYEN = <VietNamDivisionType.HUYEN: 'huyện'>

QUAN = <VietNamDivisionType.QUAN: 'quận'>

THANH_PHO = <VietNamDivisionType.THANH_PHO: 'thành phố'>

THI_XA = <VietNamDivisionType.THI_XA: 'thị xã'>

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

THI_TRAN = <VietNamDivisionType.THI_TRAN: 'thị trấn'>

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