AI SummaryThis Python library provides offline timezone lookups for WGS84 coordinates by combining preprocessed polygon data, H3-based spatial shortcuts, and optional acceleration via Numba or a clang-backed point-in-polygon routine. The package aims at maximum accuracy around timezone borders (no geometry s
Install
Copy this and paste it into Claude Code, Cursor, or any AI assistant:
I want to add the "timezonefinder — Cursor Rules" prompt rules to my project. Repository: https://github.com/jannikmi/timezonefinder Please read the repo to find the rules/prompt file, then: 1. Download it to the correct location (.cursorrules, .windsurfrules, .github/prompts/, or project root — based on the file type) 2. If there's an existing rules file, merge the new rules in rather than overwriting 3. Confirm what was added
Description
python package for finding the timezone of any point on earth (coordinates) offline
Project Overview
This Python library timezonefinder provides offline timezone lookups for WGS84 coordinates by combining preprocessed polygon data, H3-based spatial shortcuts, and optional acceleration via Numba or a clang-backed point-in-polygon routine. The package aims at maximum accuracy around timezone borders (no geometry simplifications) while offering fast lookup performance and compatibility with many (Python) runtime environments.
Development Environment
• Package Manager: Use uv for all dependency management • Python Commands: Always run via uv run (e.g., uv run pytest, uv run python script.py) • Installation: uv sync --all-groups to install all dependencies • Lockfile: Whenever dependencies or the set of officially supported/tested Python versions change, update uv.lock with make lock • Command Prefixes: Avoid redundant cd /Users/Jannik.Kissinger/github/timezonefinder in suggested commands; only add cd when running from a different subdirectory matters
Key Directories
• timezonefinder/: Core library with TimezoneFinder (full polygon search), TimezoneFinderL (shortcut-only heuristic), global helper functions, CLI entry point, and utilities • timezonefinder/data/: Packaged binary assets (FlatBuffers, NumPy arrays, zone names, shortcut index) consumed at runtime • scripts/: Tooling for regenerating data (file_converter.py, parse_data.sh), reporting, and helper configs • tests/: PyTest suite with unit tests and integration tests • docs/: Sphinx documentation; docs/data_format.rst is authoritative reference for binary layouts
Runtime Model
The primary lookup flow: • Converts query coordinates to scaled int32 values • Collects candidate polygon IDs via H3 shortcut map • Rejects polygons whose bbox rules them out • Checks holes first • Applies ray casting point-in-polygon test • Short-circuits when candidates share a timezone ID Ocean zones (Etc/GMT+/-XX) guarantee a timezone match for all possible input coordinates unless callers explicitly use timezone_at_land.
Discussion
Health Signals
My Fox Den
Community Rating
Sign in to rate this booster
Works With
Any AI assistant that accepts custom rules or system prompts