API documentation
TimezoneFinderL
- class timezonefinder.TimezoneFinderL(bin_file_location: str | Path | None = None, in_memory: bool = False)[source]
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 [source]
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)[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
- 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)[source]
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 [source]
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]]] [source]
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)[source]
retrieves the geometry of a timezone polygon
- Parameters:
tz_name – one of the names in
timezone_names.json
orself.timezone_names
tz_id – the id of the timezone (=index in
self.timezone_names
)use_id – if
True
usestz_id
instead oftz_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),...]
ifcoords_as_pairs=True
.
- get_polygon_boundaries(poly_id: int) Tuple[int, int, int, int] [source]
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 [source]
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 [source]
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 [source]
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 [source]
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