geotz.lookup

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

Retrieves the IANA time zone string for a given country code and postal code.

This function searches an offline dataset to find the time zone associated with the specified postal code within a given country. It is designed to return the time zone name, such as ‘America/New_York’, based on the input parameters. If no matching time zone 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[str]: The IANA time zone identifier for the location, if found. Returns

None if no time zone could be identified for the provided country and postal code combination.

Examples:

>>> geotz.lookup('US', '10001')
'America/New_York'

>>> geotz.lookup('GB', 'SW1A 0AA')
'Europe/London'

>>> print(geotz.lookup('CN', '999999'))
None