timezonefinder

timezonefinder is a Python package that resolves the timezone name for any latitude/longitude coordinate entirely offline, with no network calls or API keys. It prioritizes accuracy around timezone borders by using the full, unsimplified polygon dataset, while keeping lookups fast through H3-based spatial shortcuts and optional native acceleration.

Designed for both convenience and performance, it exposes simple global helper functions for one-off queries and a reusable TimezoneFinder class for high-throughput workloads, with optional Numba or a clang-backed point-in-polygon routine for speed-critical use.

What You Get

• Offline timezone lookups for WGS84 coordinates with no network dependency
• The full timezone dataset with 440+ zone names for maximum border accuracy
• Simple global functions plus a reusable TimezoneFinder class for throughput
• Optional Numba or clang-backed acceleration for point-in-polygon performance
• A command-line interface and worked examples for common integration patterns

Common Use Cases

• Determining a user’s timezone from device GPS coordinates in an app backend
• Batch-annotating datasets of geographic points with their timezones
• Scheduling or converting timestamps based on a location’s local time

Under The Hood

Architecture - The public surface in timezonefinder/__init__.py re-exports the TimezoneFinder/TimezoneFinderL classes from timezonefinder.py and stateless helpers from global_functions.py. A query first hits an H3-based shortcut index (configs.py, utils.py) to select candidate polygons, then runs precise point-in-polygon tests against FlatBuffers-encoded boundary data loaded from the bundled data/ directory, optionally memory-mapped for lower footprint.

Tech Stack - Pure Python (>=3.11) with numpy>=2, h3>=4 for the spatial index, cffi and a clang-compiled inside_poly_extension for the hot point-in-polygon loop, and flatbuffers for compact zero-copy data access. Numba is an optional accelerator. Packaging uses pyproject.toml with a setuptools/CFFI build, and a data build/conversion pipeline lives under scripts/.

Code Quality - Extensive pytest suite under tests/ (property tests via hypothesis, integration, CLI, compatibility, and packaging-contents tests), pre-commit with mypy/ruff/isort, and a py.typed marker signalling shipped type hints. Development status is marked Production/Stable.

API Design - Ergonomics are a strength: from timezonefinder import timezone_at; timezone_at(lng=..., lat=...) works in one line, while a reusable TimezoneFinder(in_memory=True) instance serves high-throughput callers. Naming is consistent (timezone_at, certain_timezone_at, unique_timezone_at, get_geometry) and documentation on Read the Docs plus runnable examples/ keep the learning curve low.