or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcore-lookup.mdgeometry.mdglobal-functions.mdindex.md
tile.json

tessl/pypi-timezonefinder

Python package for finding the timezone of any point on earth (coordinates) offline

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/timezonefinder@8.0.x

To install, run

npx @tessl/cli install tessl/pypi-timezonefinder@8.0.0

index.mddocs/

TimezoneFinder

A comprehensive Python library for finding timezone information from geographic coordinates entirely offline. TimezoneFinder provides both simple functional APIs and object-oriented interfaces for efficient timezone determination, with support for high-performance lookups through optional Numba integration and polygon-based geographic data processing.

Package Information

  • Package Name: timezonefinder
  • Language: Python
  • Installation: pip install timezonefinder or pip install timezonefinder[numba] for accelerated performance

Core Imports

from timezonefinder import TimezoneFinder, TimezoneFinderL

For convenience functions:

from timezonefinder import timezone_at, timezone_at_land, unique_timezone_at, certain_timezone_at, get_geometry

Basic Usage

from timezonefinder import timezone_at, TimezoneFinder

# Simple usage with global functions (not thread-safe)
tz = timezone_at(lng=13.358, lat=52.5061)  # 'Europe/Berlin'

# For thread safety and better performance, use instances
tf = TimezoneFinder(in_memory=True)  # load data into memory for faster queries

# Single lookup
tz = tf.timezone_at(lng=13.358, lat=52.5061)  # 'Europe/Berlin'

# Batch processing
query_points = [(13.358, 52.5061), (-74.0060, 40.7128), (139.6917, 35.6895)]
for lng, lat in query_points:
    tz = tf.timezone_at(lng=lng, lat=lat)
    print(f"({lat}, {lng}) -> {tz}")

# Land-only timezone lookup (excludes ocean timezones)
land_tz = tf.timezone_at_land(lng=13.358, lat=52.5061)  # 'Europe/Berlin'
ocean_tz = tf.timezone_at_land(lng=0.0, lat=0.0)  # None (ocean location)

Architecture

TimezoneFinder uses a hierarchical approach to timezone determination:

  • AbstractTimezoneFinder: Base class providing common functionality and coordinate validation
  • TimezoneFinder: Full-featured implementation with polygon-based precision checking
  • TimezoneFinderL: Lightweight version using shortcuts for fast approximations
  • Global Functions: Convenience functions using a singleton instance for simple use cases
  • Shortcut System: H3 hexagon-based spatial indexing for efficient polygon filtering
  • Polygon Data: Binary files containing boundary and hole geometry with FlatBuffer serialization

The design prioritizes performance through spatial indexing while maintaining accuracy through precise polygon-in-point testing, with optional acceleration via Numba JIT compilation or C extensions.

Capabilities

Core Timezone Lookup

Primary timezone determination classes and methods providing polygon-based precision checking and lightweight approximation modes. Includes both instance-based and singleton approaches for different use cases.

class TimezoneFinder:
    def __init__(self, bin_file_location: Optional[str] = None, in_memory: bool = False): ...
    def timezone_at(self, *, lng: float, lat: float) -> Optional[str]: ...
    def timezone_at_land(self, *, lng: float, lat: float) -> Optional[str]: ...

class TimezoneFinderL:
    def __init__(self, bin_file_location: Optional[Union[str, Path]] = None, in_memory: bool = False): ...
    def timezone_at(self, *, lng: float, lat: float) -> Optional[str]: ...
    def timezone_at_land(self, *, lng: float, lat: float) -> Optional[str]: ...

Core Timezone Lookup

Global Convenience Functions

Module-level functions that provide simple access to timezone lookup functionality using a global TimezoneFinder instance. These functions offer convenience but are not thread-safe.

def timezone_at(*, lng: float, lat: float) -> Optional[str]: ...
def timezone_at_land(*, lng: float, lat: float) -> Optional[str]: ...
def unique_timezone_at(*, lng: float, lat: float) -> Optional[str]: ...
def certain_timezone_at(*, lng: float, lat: float) -> Optional[str]: ...
def get_geometry(tz_name: Optional[str] = "", tz_id: Optional[int] = 0, use_id: bool = False, coords_as_pairs: bool = False) -> List[...]: ...

Global Functions

Geometry and Polygon Access

Advanced functionality for accessing timezone polygon geometry, boundary coordinates, and spatial relationships. Useful for applications requiring detailed geographic data or custom spatial analysis.

def get_geometry(tz_name: Optional[str] = "", tz_id: Optional[int] = 0, use_id: bool = False, coords_as_pairs: bool = False) -> List[...]: ...
def get_polygon(self, boundary_id: int, coords_as_pairs: bool = False) -> List[Union[CoordPairs, CoordLists]]: ...
def coords_of(self, boundary_id: int = 0) -> np.ndarray: ...

Geometry Access

Command Line Interface

Command-line utility for timezone lookups supporting multiple lookup methods and output formats. Provides direct access to library functionality from shell scripts and system integration.

timezonefinder <longitude> <latitude> [options]
# Options: -v (verbose), -f <function_id> (function selection)

Command Line Interface

Types

from typing import Dict, List, Optional, Tuple, Union
import numpy as np
from pathlib import Path

# Coordinate representation types
CoordPairs = List[Tuple[float, float]]
CoordLists = List[List[float]]

# Internal mapping types  
ShortcutMapping = Dict[int, np.ndarray]

# Base timezone finder interface
class AbstractTimezoneFinder:
    timezone_names: List[str]
    zone_ids: np.ndarray
    nr_of_zones: int