API documentation

TimezoneFinderL

class timezonefinder.TimezoneFinderL(bin_file_location: Optional[str] = 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: Optional[str] = None, in_memory: bool = False)

Initialize self. See help(type(self)) for accurate signature.

bin_file_location
binary_data_attributes = ['shortcuts_direct_id']
in_memory
shortcuts_direct_id
timezone_at(*, lng: float, lat: float) → Optional[str][source]

instantly returns the name of the most common zone within a 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 most common zone or None if there are no timezone polygons in this shortcut

timezone_names
static using_numba()

tests if Numba is being used or not

Returns:True if the import of the JIT compiled algorithms worked. False otherwise

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.

Opens the required timezone polygon data in binary files to enable fast access. Currently per half degree of latitude and per degree of longitude the set of all candidate polygons are stored. Because of these so called ‘shortcuts’ not all timezone polygons have to be tested during a query. 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 self. See help(type(self)) for accurate signature.

bin_file_location
binary_data_attributes = ['poly_zone_ids', 'poly_coord_amount', 'poly_adr2data', 'poly_max_values', 'poly_data', 'poly_nr2zone_id', 'hole_coord_amount', 'hole_adr2data', 'hole_data', 'shortcuts_entry_amount', 'shortcuts_adr2data', 'shortcuts_data', 'shortcuts_unique_id']
certain_timezone_at(*, lng: float, lat: float) → Optional[str][source]

looks up in which polygon the point certainly is included in

Note

this is much slower 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

closest_timezone_at(*, lng: float, lat: float, delta_degree: int = 1, exact_computation: bool = False, return_distances: bool = False, force_evaluation: bool = False)[source]

Searches for the closest polygon in the surrounding shortcuts

Computes the (approximate) distance to all the polygons within delta_degree degree lng and lat Make sure that the point does not lie within a polygon

Note

the algorithm won’t find the closest polygon when it’s on the ‘other end of earth’ (it can’t search beyond the 180 deg lng border!)

Note

x degrees lat are not the same distance apart than x degree lng! This is also the reason why there could still be a closer polygon even though you got a result already. In order to make sure to get the closest polygon, you should increase the search radius until you get a result and then increase it once more (and take that result). This should however only make a difference in rare cases.

Parameters:
  • lng – longitude in degree
  • lat – latitude in degree
  • delta_degree – the ‘search radius’ in degree. determines the polygons to be checked (shortcuts to include)
  • exact_computation – when enabled the distance to every polygon edge is computed (=computationally more expensive!), instead of only evaluating the distances to all the vertices. NOTE: This only makes a real difference when polygons are very close.
  • return_distances – when enabled the output looks like this: ( 'tz_name_of_the_closest_polygon',[ distances to all polygons in km], [tz_names of all polygons])
  • force_evaluation – whether all distances should be computed in any case
Returns:

the timezone name of the closest found polygon, the list of distances or None

compile_id_list(polygon_id_list, nr_of_polygons)[source]

sorts the polygons_id list from least to most occurrences of the zone ids (->speed up)

only 4.8% of all shortcuts include polygons from more than one zone but only for about 0.4% sorting would be beneficial (zones have different frequencies) in most of those cases there are only two types of zones (= entries in counted_zones) and one of them has only one entry. the polygon lists of all single shortcut are already sorted (during compilation of the binary files) sorting should be used for closest_timezone_at(), because only in that use case the polygon lists are quite long (multiple shortcuts are being checked simultaneously).

Parameters:
  • polygon_id_list – input list of polygon
  • nr_of_polygons – length of polygon_id_list
Returns:

sorted list of polygon_ids, sorted list of zone_ids, boolean: do all entries belong to the same zone

coords_of(polygon_nr: int = 0)[source]
get_geometry(tz_name='', tz_id=0, use_id=False, coords_as_pairs=False)[source]

retrieves the geometry of a timezone polygon

Parameters:
  • tz_name – one of the names in getattr(self, TIMEZONE_NAMES)
  • tz_id – the id of the timezone (=index in getattr(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)[source]
hole_adr2data
hole_coord_amount
hole_data
hole_registry
id_list(polygon_id_list, nr_of_polygons)[source]
Parameters:
  • polygon_id_list
  • nr_of_polygons – length of polygon_id_list
Returns:

(list of zone_ids, boolean: do all entries belong to the same zone)

id_of(polygon_nr: int = 0)[source]
ids_of(iterable)[source]
in_memory
poly_adr2data
poly_coord_amount
poly_data
poly_max_values
poly_nr2zone_id
poly_zone_ids
polygon_ids_of_shortcut(x: int = 0, y: int = 0)[source]
shortcuts_adr2data
shortcuts_data
shortcuts_entry_amount
shortcuts_unique_id
timezone_at(*, lng: float, lat: float) → Optional[str][source]

looks up in which timezone the given coordinate is possibly included in

to speed things up there are shortcuts being used (stored in a binary file) especially for large polygons it is expensive to check if a point is really included, so certain simplifications are made and even when you get a hit the point might actually not be inside the polygon (for example when there is only one timezone nearby) if you want to make sure a point is really inside a timezone use certain_timezone_at()

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

timezone_names
static using_numba()

tests if Numba is being used or not

Returns:True if the import of the JIT compiled algorithms worked. False otherwise