tzfpy

1.1.3 · active · verified Thu Apr 09

tzfpy is a high-performance Python package for converting longitude and latitude coordinates to timezone names. Rewritten in Rust (using PyO3), it aims for speed over absolute precision, leveraging simplified polygon data. The current version is 1.1.3, and it maintains an active release cadence with frequent updates.

Warnings

gotcha tzfpy uses simplified polygon data for speed, which means its accuracy may be reduced, especially around timezone borders. For applications requiring extremely high precision near boundaries, alternatives like `timezonefinder` might be more suitable, though potentially slower.
Fix: Be aware of this trade-off. For higher precision, consider `timezonefinder`. For general use, `tzfpy` provides excellent performance.
gotcha The underlying Rust implementation uses lazy initialization. This means the very first call to `get_tz` or `get_tzs` will be slower than subsequent calls as the data structures are loaded into memory.
Fix: If latency on the very first call is critical, consider making a dummy call during application startup to pre-load the data (e.g., `get_tz(0, 0)`).
gotcha The library utilizes approximately 40MB of memory for its internal data structures. While efficient for its task, this should be considered in memory-constrained environments.
Fix: Factor the 40MB memory footprint into your application's resource planning.
gotcha New timezone names added to `tzfpy` might be incompatible with older versions of timezone packages like `pytz` or system `tzdata`. The recommended approach is to install `tzfpy` with the `[tzdata]` extra and use Python's built-in `zoneinfo` module.
Fix: Always install `tzfpy` using `pip install "tzfpy[tzdata]"` and utilize `from zoneinfo import ZoneInfo` for robust timezone handling.

Install

pip install tzfpy Basic Installation
pip install "tzfpy[tzdata]" Recommended Installation (with tzdata extra)

Imports

get_tz
```
from tzfpy import get_tz
```
Primary function to get a single timezone name for coordinates.
get_tzs
```
from tzfpy import get_tzs
```
Function to get all possible timezone names for coordinates, useful near borders.
get_tz_polygon_geojson
```
from tzfpy import get_tz_polygon_geojson
```
For data visualization, retrieves GeoJSON polygon data for a given timezone.
get_tz_index_geojson
```
from tzfpy import get_tz_index_geojson
```
For data visualization, retrieves GeoJSON index data for a given timezone.

Quickstart

This quickstart demonstrates how to retrieve a timezone name for given coordinates using `tzfpy.get_tz` and then apply it to a `datetime` object using Python's standard `zoneinfo` module. It is recommended to install `tzfpy` with the `tzdata` extra for optimal `zoneinfo` compatibility.

from datetime import datetime, timezone
from zoneinfo import ZoneInfo
from tzfpy import get_tz

# Example coordinates for Tokyo, Japan
longitude = 139.7744
latitude = 35.6812

# Get the timezone name from coordinates
tz_name = get_tz(longitude, latitude)
print(f"Timezone for ({longitude}, {latitude}): {tz_name}")

# Use the timezone name with Python's built-in zoneinfo for datetime objects
if tz_name:
    try:
        tokyo_tz = ZoneInfo(tz_name)
        now_utc = datetime.now(timezone.utc)
        now_local = now_utc.replace(tzinfo=tokyo_tz)
        print(f"Current UTC time: {now_utc}")
        print(f"Current local time in {tz_name}: {now_local}")
    except Exception as e:
        print(f"Error creating ZoneInfo object for '{tz_name}': {e}")
else:
    print(f"Could not determine timezone for ({longitude}, {latitude})")

view raw JSON →