geosub.lookup

geosub.lookup(country_code: str, postal_code: str, allow_empty_prefix: bool = False) → SubdivisionHierarchy | None

Retrieves the ISO 3166-2 subdivision information for a given country code and postal code.

This function searches an offline dataset to find the subdivision associated with the specified postal code within a given country. It uses this to retrieve the subdivision information from the pycountry library, based on the input parameters. If no matching information is found, the function returns None.

Parameters:

country_code (str): The ISO 3166-1 alpha-2 country code, a two-letter

string that uniquely identifies the country.

postal_code (str): The postal code for the specified location within

the country. The format and length can vary depending on the country. A prefix may be used. The shorter the prefix, the more potential geographic matches there could be. The first match will be used.

allow_empty_prefix (bool): Included for testing purposes and defaults to False.

Setting it to true will allow an empty postal_code to be passed, which will match any postal code.

Returns:

Optional[SubdivisionHierarchy]: The pycountry SubdivisionHierarchy object, if

one can be found.

Examples:

>>> geosub.lookup('US', '10001')
SubdivisionHierarchy(code='US-NY', country_code='US', name='New York', ..., type='State')

>>> geosub.lookup('CA', 'M5H 2N2')
SubdivisionHierarchy(code='CA-ON', country_code='CA', name='Ontario',..., type='Province')