0
# TimezoneFinder
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: timezonefinder
7
- **Language**: Python
8
- **Installation**: `pip install timezonefinder` or `pip install timezonefinder[numba]` for accelerated performance
9

10
## Core Imports
11

12
```python
13
from timezonefinder import TimezoneFinder, TimezoneFinderL
14
```
15

16
For convenience functions:
17

18
```python
19
from timezonefinder import timezone_at, timezone_at_land, unique_timezone_at, certain_timezone_at, get_geometry
20
```
21

22
## Basic Usage
23

24
```python
25
from timezonefinder import timezone_at, TimezoneFinder
26

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

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

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

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

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

47
## Architecture
48

49
TimezoneFinder uses a hierarchical approach to timezone determination:
50

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

58
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.
59

60
## Capabilities
61

62
### Core Timezone Lookup
63

64
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.
65

66
```python { .api }
67
class TimezoneFinder:
68
    def __init__(self, bin_file_location: Optional[str] = None, in_memory: bool = False): ...
69
    def timezone_at(self, *, lng: float, lat: float) -> Optional[str]: ...
70
    def timezone_at_land(self, *, lng: float, lat: float) -> Optional[str]: ...
71

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

78
[Core Timezone Lookup](./core-lookup.md)
79

80
### Global Convenience Functions
81

82
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.
83

84
```python { .api }
85
def timezone_at(*, lng: float, lat: float) -> Optional[str]: ...
86
def timezone_at_land(*, lng: float, lat: float) -> Optional[str]: ...
87
def unique_timezone_at(*, lng: float, lat: float) -> Optional[str]: ...
88
def certain_timezone_at(*, lng: float, lat: float) -> Optional[str]: ...
89
def get_geometry(tz_name: Optional[str] = "", tz_id: Optional[int] = 0, use_id: bool = False, coords_as_pairs: bool = False) -> List[...]: ...
90
```
91

92
[Global Functions](./global-functions.md)
93

94
### Geometry and Polygon Access
95

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

98
```python { .api }
99
def get_geometry(tz_name: Optional[str] = "", tz_id: Optional[int] = 0, use_id: bool = False, coords_as_pairs: bool = False) -> List[...]: ...
100
def get_polygon(self, boundary_id: int, coords_as_pairs: bool = False) -> List[Union[CoordPairs, CoordLists]]: ...
101
def coords_of(self, boundary_id: int = 0) -> np.ndarray: ...
102
```
103

104
[Geometry Access](./geometry.md)
105

106
### Command Line Interface
107

108
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.
109

110
```bash { .api }
111
timezonefinder <longitude> <latitude> [options]
112
# Options: -v (verbose), -f <function_id> (function selection)
113
```
114

115
[Command Line Interface](./cli.md)
116

117
## Types
118

119
```python { .api }
120
from typing import Dict, List, Optional, Tuple, Union
121
import numpy as np
122
from pathlib import Path
123

124
# Coordinate representation types
125
CoordPairs = List[Tuple[float, float]]
126
CoordLists = List[List[float]]
127

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

131
# Base timezone finder interface
132
class AbstractTimezoneFinder:
133
    timezone_names: List[str]
134
    zone_ids: np.ndarray
135
    nr_of_zones: int
136
```