Timezone Finder

8.2.2 · active · verified Thu Apr 09

timezonefinder is a Python package for efficiently determining the timezone of any geographic point on Earth (given its coordinates) entirely offline. It uses a custom database of timezone polygons. The current stable version is 8.2.2. The library is actively maintained, with significant updates and breaking changes occurring with major version releases, such as v8.0.0 in early 2024.

Warnings

breaking The separate `TimezoneFinderL` class (accessed via `from timezonefinder import TimezoneFinderL`) has been removed. Users should now always import `TimezoneFinder`. If `scipy` is installed, `TimezoneFinder` will automatically use the faster 'L' algorithm.
Fix: Change `from timezonefinder import TimezoneFinderL` to `from timezonefinder import TimezoneFinder`. Ensure 'scipy' is installed (`pip install timezonefinder[full]`) if the faster algorithm is desired.
breaking The `force_reload` parameter in the `TimezoneFinder` constructor (`__init__`) has been removed. Data reloading is now handled internally and not exposed via this parameter.
Fix: Remove the `force_reload` parameter from your `TimezoneFinder` initialization calls. The library manages data loading automatically.
breaking The `in_memory` parameter in the `TimezoneFinder` constructor (`__init__`) has been renamed to `in_memory_threshold`.
Fix: If you were using `in_memory`, rename the parameter to `in_memory_threshold` in your `TimezoneFinder` initialization. For example, `TimezoneFinder(in_memory=True)` becomes `TimezoneFinder(in_memory_threshold=1)`.
gotcha Coordinate order is consistently `(longitude, latitude)` or `(lng, lat)`. It's a common mistake to swap these, especially with other geospatial libraries. The `timezone_at` method specifically uses `lng=` and `lat=` named arguments.
Fix: Always use named arguments `lng=` and `lat=` (e.g., `tf.timezone_at(lng=10.0, lat=50.0)`) to ensure correct coordinate order and improve code readability.
gotcha The `TimezoneFinder` object loads its ~100MB data file into memory upon initialization. This can cause a noticeable delay (several seconds) on first startup and consume significant RAM. Subsequent lookups are very fast.
Fix: Initialize `TimezoneFinder()` once and reuse the instance throughout your application's lifecycle. Avoid initializing it repeatedly within loops or request handlers.

Install

pip install timezonefinder Install stable version
pip install timezonefinder[full] Install with scipy for faster results

Imports

TimezoneFinder
```
from timezonefinder import TimezoneFinder
```
As of v8.0.0, `TimezoneFinderL` has been removed. The standard `TimezoneFinder` class will automatically use the faster, 'L' algorithm if 'scipy' is installed.

Quickstart

This quickstart demonstrates how to initialize `TimezoneFinder` and use `timezone_at` to find the timezone for specific geographic coordinates. It highlights the use of named arguments for longitude and latitude to avoid common coordinate order mistakes.

from timezonefinder import TimezoneFinder

tf = TimezoneFinder()

# Example coordinates: Berlin, Germany
longitude = 13.4050
latitude = 52.5200

# Find the timezone at the given coordinates
timezone_str = tf.timezone_at(lng=longitude, lat=latitude)

print(f"The timezone at ({latitude}, {longitude}) is: {timezone_str}")

# Example where no timezone is found (e.g., open ocean)
longitude_ocean = 0.0
latitude_ocean = 0.0
empty_timezone_str = tf.timezone_at(lng=longitude_ocean, lat=latitude_ocean)

print(f"The timezone at ({latitude_ocean}, {longitude_ocean}) is: {empty_timezone_str}")

view raw JSON →