timezonefinder

This is a python package providing offline timezone lookups for WGS84 coordinates. In comparison to other alternatives this package aims at maximum accuracy around timezone borders (no geometry simplifications) while offering fast lookup performance and compatibility with many (Python) runtime environments. It combines preprocessed polygon data, H3-based spatial shortcuts, and optional acceleration via Numba or a clang-backed point-in-polygon routine.

How it works

A lookup scales the coordinates to 32-bit integers (x 10⁷, ~1 cm resolution), finds the point’s H3 hexagon at resolution 4 (~288k cells worldwide), and reads a precomputed shortcut for that cell. Most cells are covered by a single timezone, so the answer is returned immediately with no geometry touched at all. Only an ambiguous cell falls through to the polygons it lists: bounding-box rejection first, then a ray-casting point-in-polygon test - holes before the outer ring, since holes are smaller and can reject the polygon outright. Architecture walks through the full pipeline; Data Format documents the binary layouts.

The central trade-off: the boundary polygons are never simplified, so border accuracy is limited only by the source dataset. The H3 index is what makes carrying full-resolution geometry affordable, and Benchmarking Methodology describes how the resulting numbers are measured.

Since the dataset includes ocean zones, every coordinate on earth matches some timezone - timezone_at() therefore effectively never returns None; use timezone_at_land() when you need to tell land from sea.

References

• Documentation

• PyPI

• conda-forge feedstock

• download stats

• online GUI and API

• benchmark trend chart

• GUI repository

• ruby port

Using it

• Getting Started
  • Installation
  • Dependencies
  • Basic Usage
• Usage
  • Global Functions
  • Instance Initialisation
  • timezone_at()
  • timezone_ids_at() and timezone_names_at()
  • timezone_at_land()
  • unique_timezone_at()
  • certain_timezone_at()
  • closest_timezone_at()
  • get_geometry()
  • TimezoneFinderL
  • Using vectorized input
  • Calling timezonefinder from the command line
  • Looking up many coordinates at once
• Use Cases
  • Creating aware datetime objects
  • Getting a location’s time zone offset
  • Django
  • Use other data
• API
  • Global Functions
  • TimezoneFinderL
  • TimezoneFinder

Design

• Architecture
  • The lookup pipeline
  • Module map
  • Three point-in-polygon backends, chosen once
  • Two accuracy tiers, two memory modes
  • Tests that protect guarantees, not behaviour
  • How it ships
  • Non-goals and deliberate ceilings
• Data Format
  • Data Source
  • Alternative Dataset Options
  • Data Structure Overview
  • Data Files
  • Holes as Boundary References
  • FlatBuffers Schema
  • Spatial Indexing with H3 Hexagons
  • Design Rationales
  • Advantages
• Data Report
  • Data Statistics
  • Shortcut Mapping Statistics
  • Binary File Sizes
• Alternatives
  • The position in one paragraph
  • Alternative python packages
  • Comparison to tzfpy
  • When to choose which package
  • Comparison to pytzwhere

Performance

• Overview
  • Benchmark Results
  • C extension
  • Numba
  • In memory mode
• Benchmarking Methodology
  • The Workload
  • ubuntu-latest does not pin the CPU
  • Consequences for the measurement design
  • The tracked estimator: min, not mean
  • What CI measures
  • Thresholds derived from measured noise
  • Comparing two implementations of one stage
  • What a stage’s share does and does not bound
  • Memory is measured the same way
  • Names are join keys
  • Comparing against another package
• Timezone Finding Benchmarks
  • System Status
• Point-in-Polygon Benchmarks
  • System Status
• Initialization Benchmarks
  • System Status
• Memory Benchmarks
  • System Status
• Comparison against tzfpy
  • System Status

Project

• About
  • References
  • LICENSE
  • Alternative python packages
  • Contact
  • Acknowledgements
• Contributing
• Changelog
  • X.X.X (unreleased)
  • 8.3.0 (2026-08-19)
  • 8.2.5 (2026-07-11)
  • 8.2.4 (2026-05-01)
  • 8.2.3 (2026-04-30)
  • 8.2.2 (2026-03-26)
  • 8.2.1 (2026-01-10)
  • 8.2.0 (2025-12-23)
  • 8.1.0 (2025-09-22)
  • 8.0.0 (2025-08-11)
  • 7.0.2 (2025-08-06)
  • 7.0.1 (2025-07-24)
  • 7.0.0 (2025-07-21)
  • 6.6.3 (2025-07-21)
  • 6.6.2 (2025-07-19)
  • 6.6.1 (2025-07-18)
  • 6.6.0 (2025-07-17)
  • 6.5.9 (2025-03-25)
  • 6.5.8 (2025-01-21)
  • 6.5.7 (2024-12-02)
  • 6.5.6 (2024-12-02)
  • 6.5.5 (2024-11-20)
  • 6.5.4 (2024-10-22)
  • 6.5.3 (2024-09-16)
  • 6.5.2 (2024-06-17)
  • 6.5.1 (2024-06-14)
  • 6.5.0 (2024-03-14)
  • 6.4.1 (2024-02-08)
  • 6.4.0 (2024-02-02)
  • 6.3.0 (2024-02-01)
  • 6.2.0 (2023-03-26)
  • 6.1.10 (2023-03-22)
  • 6.1.9 (2022-12-06)
  • 6.1.8 (2022-11-25)
  • 6.1.7 (2022-11-20)
  • 6.1.6 (2022-10-30)
  • 6.1.5 (2022-10-25)
  • 6.1.4 (2022-10-23)
  • 6.1.3 (2022-09-23)
  • 6.1.2 (2022-09-13)
  • 6.1.1 (2022-08-18)
  • 6.1.0 (2022-08-15)
  • 6.0.2 (2022-07-08)
  • 6.0.1 (2022-05-20)
  • 6.0.0 (2022-05-09)
  • 5.2.0 (2021-02-09)
  • 5.1.1 (2021-02-03)
  • 5.1.0 (2021-01-14)
  • 5.0.0 (2020-12-23)
  • 4.5.0 (2020-11-06)
  • 4.4.1 (2020-08-04)
  • 4.4.0 (2020-05-14)
  • 4.3.1 (2020-04-29)
  • 4.3.0 (2020-04-28)
  • 4.2.0 (2019-12-15)
  • 4.1.0 (2019-07-07)
  • 4.0.3 (2019-06-23)
  • 4.0.2 (2019-04-01)
  • 4.0.1 (2019-03-12)
  • 4.0.0 (2019-03-12)
  • 3.4.2 (2019-01-15)
  • 3.4.1 (2019-01-13)
  • 3.4.0 (2019-01-06)
  • 3.3.0 (2018-11-17)
  • 3.2.1 (2018-10-30)
  • 3.2.0 (2018-10-23)
  • 3.1.0 (2018-09-27)
  • 3.0.2 (2018-09-26)
  • 3.0.1 (2018-05-30)
  • 3.0.0 (2018-05-17)
  • 2.1.2 (2017-11-20)
  • 2.1.1 (2017-11-20)
  • 2.1.0 (2017-05-19)
  • 2.0.1 (2017-04-08)
  • 2.0.0 (2017-04-07)
  • 1.5.7 (2016-07-21)
  • 1.5.6 (2016-06-16)
  • 1.5.5 (2016-06-03)
  • 1.5.4 (2016-04-26)
  • 1.5.3 (2016-04-23)
  • 1.5.2 (2016-04-20)
  • 1.5.1 (2016-04-18)
  • 1.5.0 (2016-04-12)
  • 1.4.0 (2016-04-07)

Indices and tables

• Index

• Module Index

• Search Page