API documentation

TimezoneFinderL

class timezonefinder.TimezoneFinderL(bin_file_location: Union[str, pathlib.Path, None] = None, in_memory: bool = False)

Bases: timezonefinder.timezonefinder.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

__init__(bin_file_location: Union[str, pathlib.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.

bin_file_location

binary_data_attributes = ['poly_zone_ids']

get_shortcut_polys(*, lng: float, lat: float) → numpy.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) → Optional[int]

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.

nr_of_zones

Get the number of timezones.

Return type:int

poly_zone_ids

shortcut_mapping

timezone_at(*, lng: float, lat: float) → Optional[str]

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

timezone_at_land(*, lng: float, lat: float) → Optional[str]

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) → Optional[str]

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) → Optional[int]

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: numpy.ndarray) → numpy.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: Optional[str] = None, in_memory: bool = False)

Bases: timezonefinder.timezonefinder.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

__init__(bin_file_location: Optional[str] = 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.

bin_file_location

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

certain_timezone_at(*, lng: float, lat: float) → Optional[str]

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

coords_of(polygon_nr: int = 0) → numpy.ndarray

Get the coordinates of a polygon.

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

get_geometry(tz_name: Optional[str] = '', tz_id: Optional[int] = 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(polygon_nr: int, coords_as_pairs: bool = False) → List[Union[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_shortcut_polys(*, lng: float, lat: float) → numpy.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.

hole_adr2data

hole_coord_amount

hole_data

hole_registry

in_memory

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

most_common_zone_id(*, lng: float, lat: float) → Optional[int]

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.

nr_of_polygons

Get the number of polygons.

Returns:The number of polygons.

nr_of_zones

Get the number of timezones.

Return type:int

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

poly_adr2data

poly_bounds

poly_coord_amount

poly_data

poly_nr2zone_id

poly_zone_ids

shortcut_mapping

timezone_at(*, lng: float, lat: float) → Optional[str]

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) → Optional[str]

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) → Optional[str]

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) → Optional[int]

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: numpy.ndarray) → numpy.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.