Registry / data / timezonefinder

timezonefinder

library8.3.0pypypi✓ verified 25d ago

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.

data

pip install timezonefinder

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · TIMEZONEFINDER

timezonefinder

datapythonv8.3.0

Install

5.1s avg

Import

484ms

Disk

157MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.483s · 156.2MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 5.1s · import 0.485s · 152MB

157MB installed

● package 157MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TimezoneFinder

✓ from timezonefinder import TimezoneFinder

✗ from timezonefinder import TimezoneFinderL

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

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}")

timezonefinder --version

Debug

Known issues

breakingThe 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.

affects: >=8.0.0

breakingThe `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.

affects: >=8.0.0

breakingThe `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)`.

affects: >=8.0.0

gotchaCoordinate 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.

affects: All versions

gotchaThe `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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'timezonefinder'

The timezonefinder package has not been installed in the current Python environment or is not accessible on the Python path.

fix

Install the timezonefinder package using pip.
```bash
pip install timezonefinder
```

ImportError: cannot import name 'timezone_at' from 'timezonefinder'

`timezone_at` is a method of the `TimezoneFinder` class, not a direct function available for import from the `timezonefinder` module.

fix

Import the `TimezoneFinder` class, instantiate it, and then call the `timezone_at()` method on the instance.
```python
from timezonefinder import TimezoneFinder
tf = TimezoneFinder()
timezone = tf.timezone_at(lng=5.0, lat=50.0)
```

TypeError: TimezoneFinder.__init__() takes 1 positional argument but 3 were given

Users mistakenly pass longitude and latitude coordinates directly to the `TimezoneFinder` class constructor instead of to the `timezone_at()` method.

fix

Initialize the `TimezoneFinder` object without coordinates and then call `timezone_at()` with the desired longitude and latitude.
```python
from timezonefinder import TimezoneFinder
tf = TimezoneFinder()
tz = tf.timezone_at(lng=5.0, lat=50.0)
```

AttributeError: module 'timezonefinder' has no attribute 'timezone_at_land'

The function `timezone_at_land` was removed in `timezonefinder` v8.0.0 (and newer) and replaced by the unified `timezone_at()` method of the `TimezoneFinder` class.

fix

Instantiate the `TimezoneFinder` class and use its `timezone_at()` method, which handles both land and sea coordinates.
```python
from timezonefinder import TimezoneFinder
tf = TimezoneFinder()
tz = tf.timezone_at(lng=5.0, lat=50.0)
```

FileNotFoundError: [Errno 2] No such file or directory: '.../timezonefinder/data/timezonefinder.bin.zip'

The required data files for `timezonefinder` are either missing, corrupted, or not accessible at the expected location, often due to an incomplete or failed installation.

fix

Reinstall `timezonefinder` to ensure all data files are correctly downloaded and placed. If running in a custom environment, verify that the `timezonefinder/data` directory exists within your `site-packages`.
```bash
pip uninstall timezonefinder
pip install timezonefinder
```

Upgrade

Version history

8.3.0latest on PyPI · released Aug 19, 2026

Audit

Dependencies

scipyoptionalOptional dependency. Installing 'scipy' (via `pip install timezonefinder[full]`) enables a faster timezone lookup algorithm ('L' version) which `TimezoneFinder` automatically utilizes.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jannikmi/timezonefinder ↗

packagehttps://pypi.org/project/timezonefinder/ ↗

homepagehttps://timezonefinder.michelfe.it/gui ↗

docshttps://timezonefinder.readthedocs.io/en/latest/ ↗