API documentation

TimezoneFinderL

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

Bases: AbstractTimezoneFinder

a ‘light’ version of the TimezoneFinder class for quickly suggesting a timezone for a point on earth

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

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

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

Note: ‘most common’ in this context means that the 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

bin_file_location: Path

shortcut_mapping

in_memory

timezone_names

poly_zone_ids

__init__(bin_file_location: str | Path | None = None, in_memory: bool = False)

Initialize the AbstractTimezoneFinder. :param bin_file_location: The path to the binary data files to use. If None, uses native package data. :param in_memory: Whether to completely read and keep the binary files in memory.

binary_data_attributes: List[str] = ['poly_zone_ids']

List of attribute names that store opened binary data files.

get_shortcut_polys(*, lng: float, lat: float) → ndarray

Get the polygon IDs in the shortcut corresponding to the given coordinates.

Parameters:

• lng – The longitude of the point in degrees (-180.0 to 180.0).

• lat – The latitude of the point in degrees (90.0 to -90.0).

Returns:

An array of polygon IDs.

most_common_zone_id(*, lng: float, lat: float) → int | None

Get the most common zone ID in the shortcut corresponding to the given coordinates.

Parameters:

• lng – The longitude of the point in degrees (-180.0 to 180.0).

• lat – The latitude of the point in degrees (90.0 to -90.0).

Returns:

The most common zone ID or None if no polygons exist in the shortcut.

property nr_of_zones

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

unique_zone_id(*, lng: float, lat: float) → int | None

Get the unique zone ID in the shortcut corresponding to the given coordinates.

Parameters:

• lng – The longitude of the point in degrees (-180.0 to 180.0).

• lat – The latitude of the point in degrees (90.0 to -90.0).

Returns:

The unique zone ID or None if no polygons exist in the 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(poly_id: int) → int

Get the zone ID of a polygon.

Parameters:

poly_id (int) – The ID of the polygon.

Return type:

int

zone_ids_of(poly_ids: ndarray) → ndarray

Get the zone IDs of multiple polygons.

Parameters:

poly_ids – An array of polygon IDs.

Returns:

An array of zone IDs corresponding to the given polygon IDs.

zone_name_from_id(zone_id: int) → str

Get the zone name from a zone ID.

Parameters:

zone_id – The ID of the zone.

Returns:

The name of the zone.

Raises:

ValueError – If the timezone could not be found.

zone_name_from_poly_id(poly_id: int) → str

Get the zone name from a polygon ID.

Parameters:

poly_id – The ID of the polygon.

Returns:

The name of the zone.

TimezoneFinder

class timezonefinder.TimezoneFinder(bin_file_location: str | None = None, in_memory: bool = False)

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

Variables:

binary_data_attributes – the names of all attributes which store the opened binary data files

Parameters:

• bin_file_location – path to the binary data files to use, None if native package data should be used

• in_memory – whether to completely read and keep the binary files in memory

binary_data_attributes: List[str] = ['poly_zone_ids', 'poly_coord_amount', 'poly_adr2data', 'poly_bounds', 'poly_data', 'poly_nr2zone_id', 'hole_coord_amount', 'hole_adr2data', 'hole_data']

List of attribute names that store opened binary data files.

__init__(bin_file_location: str | None = None, in_memory: bool = False)

Initialize the AbstractTimezoneFinder. :param bin_file_location: The path to the binary data files to use. If None, uses native package data. :param in_memory: Whether to completely read and keep the binary files in memory.

property nr_of_polygons: int

Get the number of polygons.

Returns:

The number of polygons.

coords_of(polygon_nr: int = 0) → ndarray

Get the coordinates of a polygon.

Parameters:

polygon_nr – The index of the polygon.

Returns:

Array of coordinates.

get_polygon(polygon_nr: int, coords_as_pairs: bool = False) → List[List[Tuple[float, float]] | List[List[float]]]

Get the polygon coordinates of a given polygon number.

Parameters:

• polygon_nr – Polygon number

• coords_as_pairs – Determines the structure of the polygon representation

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)

retrieves the geometry of a timezone polygon

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.

get_polygon_boundaries(poly_id: int) → Tuple[int, int, int, int]

returns the boundaries of the polygon = (lng_max, lng_min, lat_max, lat_min) converted to int32

outside_the_boundaries_of(poly_id: int, x: int, y: int) → bool

Check if a point is outside the boundaries of a polygon.

Parameters:

• poly_id – Polygon ID

• x – X-coordinate of the point

• y – Y-coordinate of the point

Returns:

True if the point is outside the boundaries, False otherwise

inside_of_polygon(poly_id: int, x: int, y: int) → bool

Check if a point is inside a polygon.

Parameters:

• poly_id – Polygon ID

• x – X-coordinate of the point

• y – Y-coordinate of the point

Returns:

True if the point is inside the polygon, False otherwise

poly_zone_ids

poly_coord_amount

poly_adr2data

poly_bounds

poly_data

poly_nr2zone_id

hole_coord_amount

hole_adr2data

hole_data

hole_registry

bin_file_location: Path

get_shortcut_polys(*, lng: float, lat: float) → ndarray

Get the polygon IDs in the shortcut corresponding to the given coordinates.

Parameters:

• lng – The longitude of the point in degrees (-180.0 to 180.0).

• lat – The latitude of the point in degrees (90.0 to -90.0).

Returns:

An array of polygon IDs.

in_memory

most_common_zone_id(*, lng: float, lat: float) → int | None

Get the most common zone ID in the shortcut corresponding to the given coordinates.

Parameters:

• lng – The longitude of the point in degrees (-180.0 to 180.0).

• lat – The latitude of the point in degrees (90.0 to -90.0).

Returns:

The most common zone ID or None if no polygons exist in the shortcut.

property nr_of_zones

Get the number of timezones.

Return type:

int

shortcut_mapping

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

computes in which ocean OR land timezone a point is included in

Especially for large polygons it is expensive to check if a point is really included. In case there is only one possible zone (left), this zone will instantly be returned without actually checking if the query point is included in this polygon.

To speed things up there are “shortcuts” being used

which have been precomputed and store which timezone polygons have to be checked.

Note

Since ocean timezones span the whole globe, some timezone will always be matched! None can only be returned when you have compiled timezone data without such “full coverage”.

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 matched timezone polygon. possibly “Etc/GMT+-XX” in case of an ocean timezone.

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

unique_zone_id(*, lng: float, lat: float) → int | None

Get the unique zone ID in the shortcut corresponding to the given coordinates.

Parameters:

• lng – The longitude of the point in degrees (-180.0 to 180.0).

• lat – The latitude of the point in degrees (90.0 to -90.0).

Returns:

The unique zone ID or None if no polygons exist in the 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(poly_id: int) → int

Get the zone ID of a polygon.

Parameters:

poly_id (int) – The ID of the polygon.

Return type:

int

zone_ids_of(poly_ids: ndarray) → ndarray

Get the zone IDs of multiple polygons.

Parameters:

poly_ids – An array of polygon IDs.

Returns:

An array of zone IDs corresponding to the given polygon IDs.

zone_name_from_id(zone_id: int) → str

Get the zone name from a zone ID.

Parameters:

zone_id – The ID of the zone.

Returns:

The name of the zone.

Raises:

ValueError – If the timezone could not be found.

zone_name_from_poly_id(poly_id: int) → str

Get the zone name from a polygon ID.

Parameters:

poly_id – The ID of the polygon.

Returns:

The name of the zone.

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

checks in which timezone polygon the point is certainly included in

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 in degree

Returns:

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