tzwhere

library3.0.3pypypi✓ verified 86d ago

tzwhere (also referred to as pytzwhere) is a Python library designed to look up the timezone for a given latitude and longitude entirely offline. The current version, 3.0.3, released in August 2017, focuses on improving how it handles 'holes' within timezone polygons. It is a mature library, but its data sources and development are not as current as some alternatives.

data

pip install tzwhere

github ↗package ↗

INSTALL

IMPORT

SIG · TZWHERE

tzwhere

datapythonv3.0.3

Install

5.9s avg

Import

326ms

Disk

125MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.3 · 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

glibc

py 3.10

✓ —

✓ 5.68s

py 3.11

✓ —

✓ 5.4s

py 3.12

✓ —

✓ 6.23s

py 3.13

✓ —

✓ 6.05s

py 3.9

✕ build_error

✓ 6.25s

125MB installed

● package 125MB

Code

Verified usage

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

tzwhere

✓ from tzwhere import tzwhere

✗ import tzwhere

The module and the main class share the same name. Importing the module directly and then attempting to instantiate 'tzwhere()' will result in an AttributeError, as the module itself is not callable.

Initialize the tzwhere object once to load timezone data. Then, use the `tzNameAt` method with latitude and longitude to find the corresponding IANA timezone name. The `forceTZ=True` parameter can be used to find the closest timezone even if the point falls outside strict polygon boundaries.

from tzwhere import tzwhere # Initialize the tzwhere object (loads data into memory) tz = tzwhere.tzwhere() # Look up timezone for specific coordinates (e.g., Chicago) latitude = 35.29 longitude = -89.66 tz_name = tz.tzNameAt(latitude, longitude) print(f"Timezone at ({latitude}, {longitude}): {tz_name}") # Example with a point outside a strict boundary, using forceTZ latitude_ocean = 53.68 longitude_ocean = -6.24 # Near Dublin, Ireland, possibly in water tz_name_forced = tz.tzNameAt(latitude_ocean, longitude_ocean, forceTZ=True) print(f"Timezone (forced) at ({latitude_ocean}, {longitude_ocean}): {tz_name_forced}")

Debug

Known issues

breakingVersion 2.0 introduced changes to the initialization function. Previous versions might have allowed direct instantiation or different parameters.

fix

Ensure you are importing the `tzwhere` class explicitly and instantiating it with `tz = tzwhere.tzwhere()` as documented in the quickstart.

affects: 2.0.x and later

gotchaThe `tzNameAt` method can return `None` if the given coordinates fall into 'holes' in the timezone data (e.g., small islands, open water, or points slightly outside polygon boundaries).

fix

To get the closest timezone name in such cases, use the `forceTZ=True` parameter: `tz.tzNameAt(latitude, longitude, forceTZ=True)`.

affects: All versions

gotchatzwhere loads all timezone boundary data into memory upon initialization, leading to significant memory consumption (around 60-250MB) and potentially slow startup times for applications.

fix

For applications with strict memory or startup performance requirements, consider alternative libraries like `timezonefinder` which are optimized for speed and memory usage, or `geodjango-tzwhere` if using a spatial database.

affects: All versions

deprecatedThe underlying timezone data (VMAP0) used by tzwhere is based on older sources (e.g., basemap updated 2015 for v2.3.1, PyPI 3.0.3 from 2017) and is not actively maintained. This may lead to inaccuracies for more recent timezone boundary changes.

fix

For the most up-to-date and accurate timezone data, it is recommended to use actively maintained alternatives like `timezonefinder` which regularly updates its data.

affects: All versions, especially 3.0.x

Errors

Common errors & fixes

AttributeError: 'module' object has no attribute 'tzwhere'

You've imported the `tzwhere` module directly (`import tzwhere`) and then tried to call `tzwhere()` on the module object itself. The `tzwhere` class, which needs to be instantiated, is nested within the module that shares its name.

fix

Change your import statement to `from tzwhere import tzwhere`. Then you can correctly instantiate the class with `tz = tzwhere()`.

tz.tzNameAt(lat, lng) returns None unexpectedly.

The provided latitude and longitude coordinates fall outside the strict boundaries of a defined timezone polygon or into a region not covered by the underlying VMAP0 data (e.g., open ocean, or small gaps).

fix

Pass the `forceTZ=True` argument to the `tzNameAt` method to find the closest timezone even if the point is not strictly within a polygon: `tz.tzNameAt(latitude, longitude, forceTZ=True)`.

MemoryError or application startup is very slow when initializing tzwhere.

The `tzwhere.tzwhere()` constructor loads all timezone geographical data into your application's memory. This dataset is large and can consume significant RAM, leading to slow initialization, especially on resource-constrained systems.

fix

If high memory usage or slow startup is a critical concern, consider migrating to alternative libraries like `timezonefinder` which offers optimizations for memory and speed, or `geodjango-tzwhere` for database-backed lookups.

Upgrade

Version history

3.0.3latest on PyPI · released Aug 24, 2017

Audit

Dependencies

numpyoptionalOptional dependency for performance improvements.

shapelyrequiredRequired for geometric operations on timezone polygons.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pegler/pytzwhere ↗

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