API documentation

Global Functions

timezonefinder.timezone_at(*, lng: float, lat: float) → str | None[source]

Look up the timezone for a geographic coordinate using the global singleton.

Parameters:

lng – Longitude of the point in degrees (-180.0 to 180.0)
lat – Latitude of the point in degrees (-90.0 to 90.0)

Returns:

The timezone name of a matching polygon, or None if no match found

Thread Safety:

This function is thread-safe for concurrent calls. The underlying global TimezoneFinder instance uses a thread-safe singleton pattern. However, for performance-critical parallel workloads, create separate TimezoneFinder instances per thread to avoid singleton overhead.

Example:

>>> timezone_at(lng=13.4, lat=52.5)
'Europe/Berlin'

timezonefinder.timezone_at_land(*, lng: float, lat: float) → str | None[source]

Look up the land timezone for a geographic coordinate using the global singleton.

Returns None for ocean coordinates (which have fixed-offset timezones like Etc/GMT±XX).

Parameters:

lng – Longitude of the point in degrees (-180.0 to 180.0)
lat – Latitude of the point in degrees (-90.0 to 90.0)

Returns:

The timezone name for land locations, or None for ocean areas

Thread Safety:: This function is thread-safe for concurrent calls. The underlying global TimezoneFinder instance uses a thread-safe singleton pattern. However, for performance-critical parallel workloads, create separate TimezoneFinder instances per thread to avoid singleton overhead.

timezonefinder.unique_timezone_at(*, lng: float, lat: float) → str | None[source]

Get the timezone for a coordinate if the shortcut zone is unambiguous.

Returns None if the H3 shortcut cell contains multiple timezones or no zones.

Parameters:

lng – Longitude of the point in degrees (-180.0 to 180.0)
lat – Latitude of the point in degrees (-90.0 to 90.0)

Returns:

The timezone name if the shortcut contains exactly one zone, None otherwise

Thread Safety:: This function is thread-safe for concurrent calls. The underlying global TimezoneFinder instance uses a thread-safe singleton pattern. However, for performance-critical parallel workloads, create separate TimezoneFinder instances per thread to avoid singleton overhead.
Note:: This is faster than timezone_at() but may return None even for valid coordinates if the H3 cell spans multiple timezones.

timezonefinder.certain_timezone_at(*, lng: float, lat: float) → str | None[source]

Get the timezone for a coordinate with certainty (tests all polygons).

This function checks if a point is contained in ANY timezone polygon. It is slower than timezone_at() but useful when you have custom timezone data with areas of no coverage.

Parameters:

lng – Longitude of the point in degrees (-180.0 to 180.0)
lat – Latitude of the point in degrees (-90.0 to 90.0)

Returns:

The timezone name if definitely matched, None if not in any polygon

Thread Safety:: This function is thread-safe for concurrent calls. The underlying global TimezoneFinder instance uses a thread-safe singleton pattern. However, for performance-critical parallel workloads, create separate TimezoneFinder instances per thread to avoid singleton overhead.
Note:: For the standard global dataset, this is equivalent to timezone_at() since all earth locations are covered by polygons (including ocean zones). This is primarily useful with custom timezone data.

timezonefinder.get_geometry(tz_name: str | None = '', tz_id: int | None = 0, use_id: bool = False, coords_as_pairs: bool = False) → list[list[list[tuple[float, float]] | list[list[float]]]][source]

Retrieves the geometry of a timezone polygon. Uses the global TimezoneFinder instance.

Note: This function is not thread-safe. For multi-threaded environments, create separate TimezoneFinder instances.

Parameters:

tz_name – one of the names in timezone_names.json or self.timezone_names
tz_id – the id of the timezone (=index in self.timezone_names)
use_id – if True uses tz_id instead of tz_name
coords_as_pairs – determines the structure of the polygon representation

Returns:

a data structure representing the multipolygon of this timezone output format: [ [polygon1, hole1, hole2...], [polygon2, ...], ...] and each polygon and hole is itself formatted like: ([longitudes], [latitudes]) or [(lng1,lat1), (lng2,lat2),...] if coords_as_pairs=True.

TimezoneFinderL

class timezonefinder.TimezoneFinderL(bin_file_location: str | Path | None = None, in_memory: bool = False)[source]

Bases: AbstractTimezoneFinder

A lightweight version of TimezoneFinder for quick timezone suggestions.

Instead of using timezone polygon data like TimezoneFinder, this class only uses a precomputed ‘shortcut’ to suggest a probable result: the most common zone in a rectangle of a half degree of latitude and one degree of longitude.

Thread Safety:: Each thread that performs timezone lookups must create its own independent TimezoneFinderL instance. Do not share a single instance across threads.

__init__(bin_file_location: str | Path | None = None, in_memory: bool = False)[source]

Initialize the AbstractTimezoneFinder.

Loads timezone data from binary files, including shortcuts and polygon information.

Parameters:

bin_file_location – Path to the directory containing binary timezone data. If None, uses the bundled package data directory.
in_memory – Ignored for polygon coordinate data (always uses memory-mapped file access). Kept for API compatibility.

Raises:

FileNotFoundError – If timezone data files cannot be found at the specified location
ValueError – If timezone data files are corrupted or in an invalid format

timezone_at(*, lng: float, lat: float) → str | None[source]

instantly returns the name of the most common zone within the corresponding shortcut

Note: ‘most common’ in this context means that the boundary polygons with the most coordinates in sum: occurring in the corresponding shortcut belong to this zone.

Parameters:

lng – longitude of the point in degree (-180.0 to 180.0)
lat – latitude in degree (90.0 to -90.0)

Returns:

the timezone name of the most common zone or None if there are no timezone polygons in this shortcut

data_location: Path

shortcut_mapping: dict[int, int | ndarray]: List of attribute names that store opened binary data files.

in_memory

timezone_names

zone_ids: ndarray

holes_dir

boundaries_dir

boundaries

holes

cleanup() → None: Clean up resources. Override in subclasses as needed.

property nr_of_zones: int

Get the number of timezones.

Return type:: int

timezone_at_land(*, lng: float, lat: float) → str | None

computes in which land timezone a point is included in

Especially for large polygons it is expensive to check if a point is really included. To speed things up there are “shortcuts” being used (stored in a binary file), which have been precomputed and store which timezone polygons have to be checked.

Parameters:

lng – longitude of the point in degree (-180.0 to 180.0)
lat – latitude in degree (90.0 to -90.0)

Returns:

the timezone name of a matching polygon or None when an ocean timezone (“Etc/GMT+-XX”) has been matched.

unique_timezone_at(*, lng: float, lat: float) → str | None

returns the name of a unique zone within the corresponding shortcut

Parameters:

lng – longitude of the point in degree (-180.0 to 180.0)
lat – latitude in degree (90.0 to -90.0)

Returns:

the timezone name of the unique zone or None if there are no or multiple zones in this shortcut

static using_clang_pip() → bool

Returns:: True if the compiled C implementation of the point in polygon algorithm is being used

static using_numba() → bool

Check if Numba is being used.

Return type:: bool
Returns:: True if Numba is being used to JIT compile helper functions

zone_id_of(boundary_id: int | integer) → int

Get the timezone ID for a specific boundary polygon.

Parameters:

boundary_id – The numeric identifier of the boundary polygon

Returns:

The timezone ID (index into timezone_names)

Raises:

ValueError – If zone_ids are not available or boundary_id is invalid
TypeError – If boundary_id cannot be converted to an integer

zone_ids_of(boundary_ids: ndarray) → ndarray

Get the zone IDs of multiple boundary polygons.

Parameters:: boundary_ids – An array of boundary polygon IDs.
Returns:: array of corresponding timezone IDs.

zone_name_from_boundary_id(boundary_id: int | integer) → str

Get the zone name from a boundary polygon ID.

Parameters:: boundary_id – The ID of the boundary polygon.
Returns:: The name of the zone.

zone_name_from_id(zone_id: int) → str

Get the timezone name corresponding to a zone ID.

Parameters:

zone_id – The numeric ID of the timezone (0-based index)

Returns:

The IANA timezone name (e.g., ‘Europe/Berlin’)

Raises:

ValueError – If zone_id is out of range for the loaded dataset
IndexError – If the zone_id index is invalid

Example:

>>> tf = TimezoneFinder()
>>> tf.zone_name_from_id(0)
'Africa/Abidjan'

TimezoneFinder

class timezonefinder.TimezoneFinder(bin_file_location: str | Path | None = None, in_memory: bool = False)[source]

Bases: AbstractTimezoneFinder

Class for quickly finding the timezone of a point on earth offline.

Because of indexing (“shortcuts”), not all timezone polygons have to be tested during a query.

Opens the required timezone polygon data in binary files to enable fast access. For a detailed documentation of data management please refer to the code documentation of file_converter.py

Thread Safety:

Each thread that performs timezone lookups must create its own independent TimezoneFinder instance. Do not share a single instance across threads, as this can lead to race conditions and incorrect results. Example:

import threading from timezonefinder import TimezoneFinder

def lookup_in_thread(lng, lat):
# Each thread creates its own instance tf = TimezoneFinder(in_memory=True) return tf.timezone_at(lng=lng, lat=lat)

Parameters:

param bin_file_location:: path to the binary data files to use, None if native package data should be used
param in_memory:: Whether to completely read and keep the coordinate data in memory as numpy arrays.

__init__(bin_file_location: str | Path | None = None, in_memory: bool = False)[source]

Initialize the AbstractTimezoneFinder.

Loads timezone data from binary files, including shortcuts and polygon information.

Parameters:

bin_file_location – Path to the directory containing binary timezone data. If None, uses the bundled package data directory.
in_memory – Ignored for polygon coordinate data (always uses memory-mapped file access). Kept for API compatibility.

Raises:

FileNotFoundError – If timezone data files cannot be found at the specified location
ValueError – If timezone data files are corrupted or in an invalid format

holes_dir

boundaries_dir

boundaries

holes

hole_registry

property nr_of_polygons: int

property nr_of_holes: int

coords_of(boundary_id: int | integer = 0) → ndarray[source]

Get the coordinates of a boundary polygon from the FlatBuffers collection.

Parameters:: boundary_id – The index of the polygon.
Returns:: Array of coordinates.

get_polygon(boundary_id: int | integer, coords_as_pairs: bool = False) → list[list[tuple[float, float]] | list[list[float]]][source]

Get the polygon coordinates of a given boundary polygon including its holes.

Parameters:

boundary_id – ID of the boundary polygon
coords_as_pairs – If True, returns coordinates as pairs (lng, lat). If False, returns coordinates as separate lists of longitudes and latitudes.

Returns:

List of polygon coordinates

get_geometry(tz_name: str | None = '', tz_id: int | None = 0, use_id: bool = False, coords_as_pairs: bool = False) → list[list[list[tuple[float, float]] | list[list[float]]]][source]

retrieves the geometry of a timezone: multiple boundary polygons with holes

Parameters:

tz_name – one of the names in timezone_names.json or self.timezone_names
tz_id – the id of the timezone (=index in self.timezone_names)
use_id – if True uses tz_id instead of tz_name
coords_as_pairs – determines the structure of the polygon representation

Returns:

a data structure representing the multipolygon of this timezone output format: [ [polygon1, hole1, hole2...], [polygon2, ...], ...] and each polygon and hole is itself formatted like: ([longitudes], [latitudes]) or [(lng1,lat1), (lng2,lat2),...] if coords_as_pairs=True.

cleanup() → None: Clean up resources. Override in subclasses as needed.

data_location: Path

in_memory

inside_of_polygon(boundary_id: int | integer, x: int, y: int) → bool[source]

Check if a point is inside a boundary polygon.

Parameters:

boundary_id – boundary polygon ID
x – X-coordinate of the point
y – Y-coordinate of the point

Returns:

True if the point lies inside the boundary polygon, False if outside or in a hole.

property nr_of_zones: int

Get the number of timezones.

Return type:: int

shortcut_mapping: dict[int, int | ndarray]: List of attribute names that store opened binary data files.

timezone_at_land(*, lng: float, lat: float) → str | None

computes in which land timezone a point is included in

Especially for large polygons it is expensive to check if a point is really included. To speed things up there are “shortcuts” being used (stored in a binary file), which have been precomputed and store which timezone polygons have to be checked.

Parameters:

lng – longitude of the point in degree (-180.0 to 180.0)
lat – latitude in degree (90.0 to -90.0)

Returns:

the timezone name of a matching polygon or None when an ocean timezone (“Etc/GMT+-XX”) has been matched.

timezone_names

unique_timezone_at(*, lng: float, lat: float) → str | None

returns the name of a unique zone within the corresponding shortcut

Parameters:

lng – longitude of the point in degree (-180.0 to 180.0)
lat – latitude in degree (90.0 to -90.0)

Returns:

the timezone name of the unique zone or None if there are no or multiple zones in this shortcut

static using_clang_pip() → bool

Returns:: True if the compiled C implementation of the point in polygon algorithm is being used

static using_numba() → bool

Check if Numba is being used.

Return type:: bool
Returns:: True if Numba is being used to JIT compile helper functions

zone_id_of(boundary_id: int | integer) → int

Get the timezone ID for a specific boundary polygon.

Parameters:

boundary_id – The numeric identifier of the boundary polygon

Returns:

The timezone ID (index into timezone_names)

Raises:

ValueError – If zone_ids are not available or boundary_id is invalid
TypeError – If boundary_id cannot be converted to an integer

zone_ids: ndarray

zone_ids_of(boundary_ids: ndarray) → ndarray

Get the zone IDs of multiple boundary polygons.

Parameters:: boundary_ids – An array of boundary polygon IDs.
Returns:: array of corresponding timezone IDs.

zone_name_from_boundary_id(boundary_id: int | integer) → str

Get the zone name from a boundary polygon ID.

Parameters:: boundary_id – The ID of the boundary polygon.
Returns:: The name of the zone.

zone_name_from_id(zone_id: int) → str

Get the timezone name corresponding to a zone ID.

Parameters:

zone_id – The numeric ID of the timezone (0-based index)

Returns:

The IANA timezone name (e.g., ‘Europe/Berlin’)

Raises:

ValueError – If zone_id is out of range for the loaded dataset
IndexError – If the zone_id index is invalid

Example:

>>> tf = TimezoneFinder()
>>> tf.zone_name_from_id(0)
'Africa/Abidjan'

timezone_at(*, lng: float, lat: float) → str | None[source]

Find the timezone for a given point using hybrid shortcuts, considering both land and ocean timezones.

Uses precomputed hybrid shortcuts to reduce the number of polygons checked. Returns the timezone name of the matched polygon, which may be an ocean timezone (“Etc/GMT+-XX”) if applicable.

Since ocean timezones span the whole globe, some timezone will always be matched! None can only be returned when using custom timezone data without such ocean timezones.

Parameters:

lng – longitude of the point in degrees (-180.0 to 180.0)
lat – latitude of the point in degrees (90.0 to -90.0)

Returns:

the timezone name of the matched polygon, or None if no match is found.

certain_timezone_at(*, lng: float, lat: float) → str | None[source]

checks in which timezone polygon the point is certainly included in using hybrid shortcuts

Note

this is only meaningful when you have compiled your own timezone data where there are areas without timezone polygon coverage. Otherwise, some timezone will always be matched and the functionality is equal to using .timezone_at() -> useless to actually test all polygons.

Note

using this function is less performant than .timezone_at()

Parameters:

lng – longitude of the point in degree
lat – latitude of the point in degree

Returns:

the timezone name of the polygon the point is included in or None