localtimezone

README

github.com/albertyw/localtimezone

Provides timezone lookup for geographic coordinates. Based on github.com/ugjka/go-tz.

Installation

go get github.com/albertyw/localtimezone/v3

Usage / Example

import localtimezone "github.com/albertyw/localtimezone/v3"

// Loading Zone for Line Islands, Kiritimati
tz, err := localtimezone.NewLocalTimeZone()
if err != nil {
    panic(err)
}
zone, err := tz.GetZone(localtimezone.Point{
    Lon: -157.21328, Lat: 1.74294,
})
if err != nil {
    panic(err)
}
fmt.Println(zone[0])

Note: GetZone() may return an error only for out-of-range coordinates; it returns the nearest timezone for all valid locations.

Uses simplified shapefile from timezone-boundary-builder

Built with orb for high-performance geometry handling and WKB serialization.

Features

• The timezone shapefile is embedded in the build binary
• GetZone() returns all timezones at a location; GetOneZone() returns a single result
• You can load a custom GeoJSON shapefile for alternative data sources
• Thread-safe for concurrent lookups
• Lookups are purely in-memory. Uses ~8MB of RAM.

Benchmarks

go test -bench=. -benchmem
goos: linux
goarch: amd64
pkg: github.com/albertyw/localtimezone/v3
cpu: AMD Ryzen 9 7900X 12-Core Processor
BenchmarkGetZone/GetZone_on_large_cities-24                41272             29076 ns/op              16 B/op          1 allocs/op
BenchmarkGetZone/GetOneZone_on_large_cities-24             54379             21986 ns/op              16 B/op          1 allocs/op
BenchmarkZones/polygon_centers-24                          75387             15807 ns/op              16 B/op          1 allocs/op
BenchmarkZones/test_cases-24                              170304              6982 ns/op              18 B/op          1 allocs/op
BenchmarkClientInit/main_client-24                           153           7821843 ns/op         7265567 B/op       9161 allocs/op
BenchmarkClientInit/mock_client-24                        113492             10889 ns/op           37880 B/op         30 allocs/op
PASS
ok      github.com/albertyw/localtimezone/v3    7.312s

Lookups take ~6-30 microseconds depending on location complexity; client initialization takes ~14ms.

Limitations

• Shapefile uses simplified geometries (Visvalingam simplification with ~89m threshold) that may have reduced accuracy near borders
• Points in international waters or disputed territories return the nearest timezone

Updating data

To update to the latest timezone data:

make generate

The data comes from timezone-boundary-builder. Check the releases page for the latest version.

Licenses

The code used to lookup the timezone for a location is licensed under the MIT License.

The data in timezone shapefile is licensed under the Open Data Commons Open Database License (ODbL).

Documentation

Overview

Package localtimezone provides timezone lookup for a given location

Features

* The timezone shapefile is embedded in the build binary using //go:embed

* Supports overlapping zones

* You can load your own geojson shapefile if you want

* Sub millisecond lookup even on old hardware

Problems

* The shapefile is simplified using a lossy method so it may be innacurate along the borders

* This is purely in-memory. Uses ~50MB of ram

Index

• Constants
• Variables
• type LocalTimeZone
  • func NewLocalTimeZone() (LocalTimeZone, error)
  • func NewMockLocalTimeZone() LocalTimeZone
• type Point

Constants

const MockTimeZone = "America/Los_Angeles"

MockTimeZone is the timezone that is always returned from the NewMockLocalTimeZone client

const TZBoundaryVersion = "2026b"

TZBoundaryVersion is the version of tzdata that was used to generate timezone boundaries

const TZCount = 444

TZCount is the number of tzdata timezones supported

Variables

var ErrNoTimeZone = errors.New("no timezone found")

ErrNoTimeZone is returned when no matching timezone is found This error should never be returned because the client will attempt to return the nearest zone

var ErrOutOfRange = errors.New("point's coordinates out of range")

ErrOutOfRange is returned when latitude exceeds 90 degrees or longitude exceeds 180 degrees

var MockTZShapeFile []byte

MockTZShapeFile is similar to TZShapeFile but maps the entire world to the timezone America/Los_Angeles. This data is WKB binary format compressed with gzip. It is meant for testing.

var TZNames = []string{}/* 444 elements not displayed */

TZNames is an array of possible timezone names that may be returned by this library

var TZShapeFile []byte

TZShapeFile is the data containing geographic shapes for timezone borders. This data is WKB binary format compressed with gzip.

Types

type LocalTimeZone

type LocalTimeZone interface {
	GetZone(p Point) (tzids []string, err error)
	GetOneZone(p Point) (tzid string, err error)
	LoadGeoJSON(io.Reader) error
}

LocalTimeZone is a client for looking up time zones by Points

func NewLocalTimeZone

func NewLocalTimeZone() (LocalTimeZone, error)

NewLocalTimeZone creates a new LocalTimeZone with real timezone data The client is threadsafe

func NewMockLocalTimeZone

func NewMockLocalTimeZone() LocalTimeZone

NewMockLocalTimeZone creates a new LocalTimeZone that always returns America/Los_Angeles as the timezone The client is threadsafe

type Point

type Point struct {
	Lon float64
	Lat float64
}

Point describes a location by Latitude and Longitude