timezoneLookup

README

Timezone lookup

Is a timezone lookup API for GPS Coordinates to Timezone based on GeoJSON Polygon and Multipolygon files.

Source Data

Source files can be obtained at https://github.com/evansiroky/timezone-boundary-builder

Performance

Performance is significantly improved between release v1 and release v2 due to the underlying data structure. Timezone database is approxiamtely 50mb in size and lookups range between 50 - 200 microseconds. Recent verion uses an RTree as well as a Memory mapped timezone database for reduced latency and increased throughput.

[]Benchmarks still need to be written.

Authors

Appreciate all who have contributed with Pull Requests and Issues. We eagerly welcome suggestions and PRs.

Rtree source design by Josh Backer tidwall

Example

Build program

go build -o timezone cmd/main.go 

Download datasource and build timezone database ~50mb

./timezone -build

Test query for San Fransisco, United States (Etc/GMT+8)

./timezone -search -lat=37.7749 -lng=-122.4194

Release V2.0 and forward

Based on custom backing that loads data as memory mapped data.

package main

import (
	"fmt"

	timezone "github.com/evanoberholster/timezoneLookup@v2.0.0"
)

func main() {
	var tzc timezone.Timezonecache
	f, err := os.Open("timzone.data")
	if err != nil {
		return timezone.Result{}, err
	}
	defer f.Close()
	if err = tzc.Load(f); err != nil {
		return timezone.Result{}, err
	}
	defer tzc.Close()

	lat := 37.7749
	lng := -122.4194

	result := tzc.Search(lat, lng)
	fmt.Println(result)
}

Release V1.0 and prior

Based on JSON, MsgPack, Protobuf or Cap'n'Proto encodings with boltDB backend

Intructions for V1.0

1. Download data from: https://github.com/evansiroky/timezone-boundary-builder/releases
2. go get github.com/evanoberholster/timezoneLookup@v1.0.0
3. go build github.com/evanoberholster/timezoneLookup/cmd/timezone.go
4. timezone -json "jsonfilename" -db=timezone -type=(memory or boltdb)
5. go run example.go

package main
import (
	"fmt"
	timezone "github.com/evanoberholster/timezoneLookup@v1.0.0"
)
var tz timezone.TimezoneInterface

func main() {
	tz, err := timezone.LoadTimezones(timezone.Config{
		DatabaseType:"boltdb", // memory or boltdb
		DatabaseName:"timezone", // Name without suffix
		Snappy: true,
		Encoding: "msgpack", // json or msgpack
	})
	if err != nil {
		fmt.Println(err)
	}

	res, err := tz.Query(timezone.Coord{
			Lat: 5.261417, Lon: -3.925778,})
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println("Query Result: ", res)

	tz.Close()
}

Documentation

Index

• Constants
• Variables
• func ImportZipFile(cache string, url string, iter func(tz Timezone) error) (err error)
• func Verbose(v bool)
• type GeoJSONFeature
• type Result
• type Timezone
• type Timezonecache
  • func (tzc *Timezonecache) AddTimezone(tz Timezone)
  • func (tzc *Timezonecache) BuildRtree()
  • func (tzc *Timezonecache) Close() error
  • func (tzc *Timezonecache) Load(f *os.File) (err error)
  • func (tzc *Timezonecache) Save(filename string) error
  • func (tzc *Timezonecache) Search(lat, lng float64) (Result, error)

Constants

const (
	DefaultURL = "https://github.com/evansiroky/timezone-boundary-builder/releases/download/2020d/timezones-with-oceans.geojson.zip"
)

Variables

var (
	ErrCoordinatesNotValid = errors.New("Latitude and/or Longitude are not valid")
)

Functions

func ImportZipFile

func ImportZipFile(cache string, url string, iter func(tz Timezone) error) (err error)

ImportZipFile imports a url and saves it with the following filename. The iter function is run on the zip file.

func Verbose

func Verbose(v bool)

Verbose sets the import function to verbose

Types

type GeoJSONFeature

type GeoJSONFeature struct {
	Type       string `json:"type"`
	Properties struct {
		Tzid string `json:"tzid"`
	} `json:"properties"`
	Geometry struct {
		Item        string        `json:"type"`
		Coordinates []interface{} `json:"coordinates"`
	} `json:"geometry"`
}

GeoJSONFeature

type Result

type Result struct {
	Name        string
	Coordinates geo.LatLng
	Elapsed     time.Duration
}

Result is a timezone lookup result

type Timezone

type Timezone struct {
	Name     string
	Polygons []geo.Polygon `json:"polygons"`
}

Timezone

type Timezonecache

type Timezonecache struct {
	// contains filtered or unexported fields
}

func (*Timezonecache) AddTimezone

func (tzc *Timezonecache) AddTimezone(tz Timezone)

func (*Timezonecache) BuildRtree

func (tzc *Timezonecache) BuildRtree()

func (*Timezonecache) Close

func (tzc *Timezonecache) Close() error

func (*Timezonecache) Load

func (tzc *Timezonecache) Load(f *os.File) (err error)

func (*Timezonecache) Save

func (tzc *Timezonecache) Save(filename string) error

func (*Timezonecache) Search

func (tzc *Timezonecache) Search(lat, lng float64) (Result, error)