Usage

Note

Also check out the API documentation or the code.

Initialisation

Create a new instance of the TimezoneFinder class to be reused for multiple consequent timezone queries:

from timezonefinder import TimezoneFinder

tf = TimezoneFinder()  # reuse

Use the argument bin_file_location to use data files from another location (e.g. your own compiled files):

tf = TimezoneFinder(bin_file_location="path/to/files")

timezone_at()

This is the default function to check which timezone a point lies within. If no timezone has been matched, None is being returned.

tz = tf.timezone_at(lng=13.358, lat=52.5061)  # 'Europe/Berlin'
tz = tf.timezone_at(lng=1.0, lat=50.5)  # 'Etc/GMT'

Note

To reduce the risk of mixing up the coordinates, the arguments lng and lat have to be given as keyword arguments

Note

This function is optimized for speed: The last possible timezone in proximity is always returned (without checking if the point is really included).

timezone_at_land()

This package includes ocean timezones (Etc/GMT...). If you want to explicitly receive only “land” timezones use

tz = tf.timezone_at_land(lng=13.358, lat=52.5061)  # 'Europe/Berlin'
tz = tf.timezone_at_land(lng=1.0, lat=50.5)  # None

unique_timezone_at()

For fast execution timezonefinder internally uses precomputed “shortcuts” which store the possible zones in proximity. Call unique_timezone_at() if you want to compute an exact result without actually performing “point-in-polygon” tests (<- computationally expensive). This function will return None when the correct zone cannot be uniquely determined without further computation.

tf.unique_timezone_at(lng=longitude, lat=latitude)

Note

The “lightweight” class TimezoneFinderL, which is using only shortcuts, also supports just querying the most probable timezone.

certain_timezone_at()

Note

DEPRECATED: Due to the included ocean timezones one zone will always be matched. Use timezone_at() or timezone_at_land() instead.

This function is for making sure a point is really inside a timezone. It is slower, because all polygons (with shortcuts in that area) are being checked until one polygon is matched. None is being returned in the case of no match.

tz = tf.certain_timezone_at(lng=13.358, lat=52.5061)  # 'Europe/Berlin'

Note

Due to the “point-in-polygon-test” algorithm being used, the state of a point on the edge of a (timezone) polygon is undefined. For those kind of points the return values is hence uncertain and might be None. This applies for example for all points with lng=+-180.0, because the timezone polygons in the data set are being cropped at the 180 longitude border.

closest_timezone_at()

removed in version 6.0.0

get_geometry()

For querying a timezone for its geometric multi-polygon shape use get_geometry(). output format: [ [polygon1, hole1,...), [polygon2, ...], ...] and each polygon and hole is itself formated like: ([longitudes], [latitudes]) or [(lng1,lat1), (lng2,lat2),...] if coords_as_pairs=True.

tf.get_geometry(tz_name="Africa/Addis_Ababa", coords_as_pairs=True)
tf.get_geometry(tz_id=400, use_id=True)

TimezoneFinderL

TimezoneFinderL is a light version of the TimezoneFinder class. It is useful for quickly suggesting probable timezones without using as many computational resources (cf. speed tests). Instead of using timezone polygon data this class instantly returns the timezone just based on precomputed “shortcuts”.

Check the (API documentation) of TimezoneFinderL.

The most probable zone in proximity can be retrieved with timezone_at():

from timezonefinder import TimezoneFinderL

tf = TimezoneFinderL(in_memory=True)  # reuse

query_points = [(13.358, 52.5061), ...]
for lng, lat in query_points:
    tz = tf.timezone_at(lng=lng, lat=lat)  # 'Europe/Berlin'

Certain results can be retrieved with unique_timezone_at():

tf.unique_timezone_at(lng=13.358, lat=52.5061)  # 'Europe/Berlin'

Note

If you only use TimezoneFinderL, you may delete all data files except timezone_names.json, shortcuts.bin to obtain a truly lightweight installation.

Using vectorized input

Check numpy.vectorize and pandas.DataFrame.apply

Calling timezonefinder from the command line

A command line script is being installed as part of this package.

Command Line Syntax:

timezonefinder [-h] [-v] [-f {0,1,2,3,4,5}] lng lat

Example:

timezonefinder -f 4 40.5 11.7

With -v you get verbose output, without it only the timezone name is being printed. With the argument of the flag -f one can choose between the different functions to be called:

0: TimezoneFinder.timezone_at() = default
1: TimezoneFinder.certain_timezone_at()
2: removed
3: TimezoneFinderL.timezone_at()
4: TimezoneFinderL.timezone_at_land()
5: TimezoneFinder.timezone_at_land()

Note

This will be orders of magnitude slower than using the package directly from within python as a separate Timezonefinder() instance is being