API documentation¶
TimezoneFinderL¶
-
class
timezonefinder.
TimezoneFinderL
(bin_file_location: Union[str, pathlib.Path, None] = None, in_memory: bool = False)[source]¶ 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][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
-
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)[source]¶ 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)[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.
-
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][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
-
coords_of
(polygon_nr: int = 0) → numpy.ndarray[source]¶ 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)[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
.- tz_name – one of the names in
-
get_polygon
(polygon_nr: int, coords_as_pairs: bool = False) → List[Union[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_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[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
-
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[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
-
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][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) → 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.