Getting started

Installation

pip install timezonefinder

This builds a C extension for the point-in-polygon test. The optional numba extra swaps that extension for a JIT-compiled kernel, and takes precedence over it whenever it is installed - which is a dispatch rule and not a promise that it is faster. Check Point-in-Polygon Acceleration Paths for how the three compare on the workload you run before adding it (see also the performance chapter):

pip install timezonefinder[numba]

in case you are using pytz, also require it via its extra to avoid incompatibilities (e.g. due to updated timezone names):

pip install timezonefinder[pytz]

For installation within a Conda environment see instructions at conda-forge feedstock

Dependencies

Five runtime dependencies, each carrying part of the lookup:

  • numpy - the arrays the polygon data is read into

  • h3 - the hexagonal grid the shortcut index is built on

  • cffi - builds and binds the optional C extension

  • flatbuffers - reads the packaged binary data without unpacking it

  • timezonefinder-data - the boundary data itself

The list is deliberately short: the timezone data is installed with the package, so nothing is downloaded or looked up at runtime, and no geospatial stack is pulled in. numba is an extra rather than a dependency because it only makes the package faster, never more correct - see performance chapter.

timezonefinder-data is a distribution of this same project, published separately so that a new timezone-boundary-builder release ships without a timezonefinder release. pip install timezonefinder pulls it in automatically; pin it explicitly to hold a deployment to one dataset, choosing the version from its release history:

pip install timezonefinder "timezonefinder-data==<version>"

pyproject.toml remains the authoritative source for the supported version ranges.

Which numpy generations are supported follows the NumPy deprecation policy: a generation leaves this package’s floor once it leaves that schedule, and NumPy 1 did so in release 8.2.1.

An environment that has to keep NumPy 1 can constrain it and let the resolver fall back to the last release that accepts it. That is a stopgap rather than a destination, because the fallback carries the code and the boundary data of its own release:

pip install timezonefinder "numpy<2"

Where the clash is with a numpy installed by the system package manager, a virtual environment is the better answer: it leaves that installation untouched, and needs no fallback.

Basic Usage

All available features of this package are explained in the usage chapter.

Examples for common use cases can be found in the use case chapter.