Geo2tz

Geo2tz is a lightweight, self‑hosted microservice written in Go that resolves geographic coordinates to IANA time zone identifiers. It leverages the high‑resolution polygon data from evansiroky/timezone-boundary-builder and exposes a single HTTP endpoint (GET /tz/{lat}/{lon}) that returns JSON. The service is designed for performance, low memory footprint, and strict privacy guarantees—coordinates never leave the host.

Key Features

• Fast lookup: In‑memory spatial index (R‑tree) enables sub‑millisecond queries on a machine with 8 GB RAM.
• Updatable data: The database is bundled as a ZIP of GeoJSON files; new releases can be swapped by re‑initializing the container or restarting the binary.
• Error handling: Validates latitude/longitude ranges and returns descriptive HTTP 400 responses.
• Version endpoint: /tz/version exposes the underlying timezone boundary release and download URL for auditability.
• Optional token auth: Basic query‑string token protection (?token=…) for simple access control.

Technical Stack

The codebase is deliberately small (~2 k LOC) to keep the attack surface low and simplify maintenance.

Core Capabilities

• REST API: Single endpoint for time‑zone lookup; no authentication headers needed unless configured.
• Query Parameters: Optional token for simple bearer‑style protection; no OAuth or JWT support.
• Extensibility hooks: The binary exposes a main package that can be imported into larger Go applications; the lookup logic is encapsulated in a tz package with an interface that can be swapped for alternative data sources.
• Metrics: Exposes basic Prometheus metrics (request count, latency) via /metrics when the -prometheus flag is enabled.

Deployment & Infrastructure

Geo2tz is designed for self‑hosting in any environment that can run Docker or a native Go binary:

• Containerization: Official image is available on Docker Hub; can be run behind a reverse proxy (NGINX, Traefik) with TLS termination.
• Resource footprint: Requires < 100 MB RAM and a single CPU core for 99.9% of requests; the GeoJSON database (~50 MB uncompressed) is loaded into memory at startup.
• Scalability: Stateless, so horizontal scaling is trivial. Auto‑scaling can be orchestrated by Kubernetes or Docker Swarm.
• Persistence: No external database needed; all data is read‑only and stored in the container’s filesystem.

Integration & Extensibility

• API consumption: Any language can call the endpoint; Go clients are provided in the client submodule.
• Webhook: Not built‑in, but can be added by wrapping the service in a proxy that triggers downstream events on lookup.
• Plugin system: No plugin architecture; however, the tz package can be forked and extended to support custom polygon sources or caching layers.
• Custom data: Replace the GeoJSON ZIP with a locally modified file; rebuild the image or mount the data volume.

Developer Experience

• Documentation: Inline GoDoc is comprehensive; external README covers usage, CI status, and API examples.
• Testing: Unit tests cover boundary cases (invalid coordinates) and performance benchmarks; CI enforces code quality via golangci-lint.
• Community: Active GitHub repository with issue tracking; contributors can submit PRs for new features or bug fixes.
• Licensing: MIT license—free to use, modify, and redistribute in commercial or open‑source projects.

Use Cases

Advantages Over Alternatives

• Zero external dependencies: No reliance on third‑party APIs or paid services.
• Performance: In‑memory R‑tree lookup outperforms many RESTful alternatives by an order of magnitude.
• Transparency: Uses openly available boundary data; the source code is fully auditable.
• Simplicity: Single endpoint, no authentication overhead unless explicitly configured.
• Cost‑effective: Runs on a single low‑cost VM or container; no recurring service fees.

Geo2tz offers developers a robust, privacy‑centric solution for