timezonefinder Documentation

timezonefinder is a Python package used to look up the corresponding timezone for given latitude/longitude coordinates on Earth. The package works entirely offline.

Internally, timezones are represented as polygons. The membership of a specific point (lat/lng pair) is determined using a Point in Polygon (PIP) check. The library includes optimizations to avoid expensive PIP checks whenever possible.

The timezonefinder library uses highly optimized binary data structures to enable fast and memory-efficient timezone lookups. The data is organized into several specialized files:

• Polygon Coordinates: Stored in FlatBuffers binary files (coordinates.fbs) for boundary polygons and holes.
• Hybrid Shortcut Index: A spatial index using H3 hexagons (hybrid_shortcuts_uint8.fbs or hybrid_shortcuts_uint16.fbs) that stores either direct zone IDs or lists of polygon IDs.
• Numpy Arrays: .npy files storing polygon information, such as zone_ids.npy, zone_positions.npy, and bounding boxes (xmin.npy, xmax.npy, ymin.npy, ymax.npy).
• Zone Names: A timezone_names.txt file listing all timezone names.
• Hole Registry: A mapping from polygon IDs to the amount and position of its holes.

The TimezoneFinderL class is a lightweight version of TimezoneFinder. Instead of using polygon data, it uses only precomputed "shortcuts" to instantly suggest the most probable timezone. This is ideal for resource-constrained environments or when high-speed proximity suggestions are sufficient.

Optimization Tip: If you only use TimezoneFinderL, you can delete the data/boundaries and data/holes folders to create a very small installation (a few MB).

from timezonefinder import TimezoneFinderL

tf = TimezoneFinderL(in_memory=True)

tz = tf.timezone_at(lng=13.358, lat=52.5061)  # 'Europe/Paris'

# Or for certain results via shortcuts
tz_unique = tf.unique_timezone_at(lng=13.358, lat=52.5061)

The library uses Uber's H3 library to divide the Earth's surface into a grid of hexagons (using resolution 3, totaling ~41k hexagons). This acts as a spatial index to drastically reduce the number of polygons that need to be checked during a lookup.

The Hybrid Storage Approach

For each hexagon cell, the library uses one of two storage methods:

1. Unique zones: If all polygons in a hexagon belong to the same timezone, the zone ID is stored directly. This allows for immediate results without polygon testing.
2. Multiple zones: If a hexagon contains polygons from different timezones, an array of polygon IDs is stored. The library then only tests those specific polygons to find the match.

This approach balances precision, memory efficiency, and lookup speed.

You can install the base package using pip. For improved performance, it is recommended to install the optional numba dependency. If your project also uses pytz, you should install the pytz extra to ensure compatibility and avoid issues with updated timezone names.

# Standard installation
pip install timezonefinder

# Installation with numba for improved speed
pip install timezonefinder[numba]

# Installation with pytz support to avoid incompatibilities
pip install timezonefinder[pytz]

For single-threaded, simple use cases, timezonefinder provides global functions that use a thread-safe singleton instance. Note that the first call will be slower due to lazy initialization.

Warning: While the singleton initialization is thread-safe, the shared instance itself is NOT safe for concurrent reads. For parallel workloads (threading, asyncio, multiprocessing), you must create separate TimezoneFinder instances for each thread/process.

from timezonefinder import timezone_at

tz = timezone_at(lng=13.358, lat=52.5061)  # 'Europe/Paris'

You can significantly increase performance by installing the optional numba dependency. This allows utility functions to be JIT compiled.

Note on priority: If Numba is available, the JIT-compiled Python version of the point-in-polygon algorithm will be used instead of the C extension, as it is even faster.

It is highly recommended to install numba if a C compiler was not available during the initial build process.

To install with Numba support:

pip install timezonefinder[numba]

To check if Numba is being used:

TimezoneFinder.using_numba()  # returns True or False

During installation, timezonefinder attempts to compile a C extension to implement the time-critical point-in-polygon check algorithm. This requires a Clang compiler to be installed on your system.

If compilation fails (e.g., due to a missing C compiler or broken cffi installation), the library silently falls back to a pure Python implementation, which is approximately 400x slower.

You can verify if the compiled C implementation is active using TimezoneFinder.using_clang_pip().

# Returns True if the compiled C implementation is being used
TimezoneFinder.using_clang_pip()