tzf

README

TZF: a timezone finder for Go.

graph TD
    C[H3 Based Approximation file]
    D[Probuf based Bin file]
    H[Polygon search component]
    D --> |Reduce via cmd/reducePolygon|D
    A[Raw timezone boundary JSON file] --> |Convert via cmd/tzjson2pb|D
    D --> |Uber H3 Polyfill|C
    D --> H
    C --> GetTimezone
    H --> GetTimezone

Quick Start

package main

import (
	"fmt"

	"github.com/ringsaturn/tzf"
	tzfrel "github.com/ringsaturn/tzf-rel"
	"github.com/ringsaturn/tzf/pb"
	"google.golang.org/protobuf/proto"
)

func main() {
	input := &pb.Timezones{}

	// Lite data, about 16.7MB
	dataFile := tzfrel.LiteData

	// Full data, about 83.5MB
	// dataFile := tzfrel.FullData

	if err := proto.Unmarshal(dataFile, input); err != nil {
		panic(err)
	}
	finder, _ := tzf.NewFinderFromPB(input)
	fmt.Println(finder.GetTimezoneName(111.8674, 34.4200))
	fmt.Println(finder.GetTimezoneName(-97.8674, 34.4200))
	fmt.Println(finder.GetTimezoneName(121.3547, 31.1139))
	fmt.Println(finder.GetTimezoneName(139.4382, 36.4432))
	fmt.Println(finder.GetTimezoneName(24.5212, 50.2506))
	fmt.Println(finder.GetTimezoneName(-0.9671, 52.0152))
	fmt.Println(finder.GetTimezoneName(-4.5706, 46.2747))
	fmt.Println(finder.GetTimezoneName(111.9781, 45.0182))
	fmt.Println(finder.GetTimezoneName(-73.7729, 38.3530))
}

Output:

Asia/Shanghai
America/Chicago
Asia/Shanghai
Asia/Tokyo
Europe/Kiev
Europe/London
Etc/GMT
Asia/Shanghai
Etc/GMT+5

Data

Original data download from https://github.com/evansiroky/timezone-boundary-builder.

Preprocessed probuf data can get from https://github.com/ringsaturn/tzf-rel which has Go's embed support.

TODO

• POC: polygon search based
• Reduce Polygon size option
  • Reduce float precise
  • Reduce line numbers
• H3 Based Approximation, something like Placekey

Thanks

• https://github.com/tidwall/geometry
• https://github.com/jannikmi/timezonefinder
• https://github.com/evansiroky/timezone-boundary-builder

Documentation

Overview

Package tzf is a package convert (lng,lat) to timezone.

Inspired by timezonefinder https://github.com/jannikmi/timezonefinder, fast python package for finding the timezone of any point on earth (coordinates) offline.

Index

• type Finder
  • func NewFinderFromPB(input *pb.Timezones) (*Finder, error)
  • func NewFinderFromRawJSON(input *convert.BoundaryFile) (*Finder, error)
  • func (f *Finder) GetTimezone(lng float64, lat float64) (*pb.Timezone, error)
  • func (f *Finder) GetTimezoneLoc(lng float64, lat float64) (*time.Location, error)
  • func (f *Finder) GetTimezoneName(lng float64, lat float64) string

Examples

• Finder.GetTimezoneLoc
• Finder.GetTimezoneName

Types

type Finder

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

func NewFinderFromPB

func NewFinderFromPB(input *pb.Timezones) (*Finder, error)

func NewFinderFromRawJSON

func NewFinderFromRawJSON(input *convert.BoundaryFile) (*Finder, error)

func (*Finder) GetTimezone

func (f *Finder) GetTimezone(lng float64, lat float64) (*pb.Timezone, error)

func (*Finder) GetTimezoneLoc

func (f *Finder) GetTimezoneLoc(lng float64, lat float64) (*time.Location, error)

Example

package main

import (
	"fmt"

	"github.com/ringsaturn/tzf"
	tzfrel "github.com/ringsaturn/tzf-rel"
	"github.com/ringsaturn/tzf/pb"
	"google.golang.org/protobuf/proto"
)

func main() {
	input := &pb.Timezones{}

	// Lite data, about 16.7MB
	dataFile := tzfrel.LiteData

	// Full data, about 83.5MB
	// dataFile := tzfrel.FullData

	if err := proto.Unmarshal(dataFile, input); err != nil {
		panic(err)
	}
	finder, _ := tzf.NewFinderFromPB(input)
	fmt.Println(finder.GetTimezoneLoc(116.6386, 40.0786))
}

Output:

Asia/Shanghai <nil>

func (*Finder) GetTimezoneName

func (f *Finder) GetTimezoneName(lng float64, lat float64) string

Example

package main

import (
	"fmt"

	"github.com/ringsaturn/tzf"
	tzfrel "github.com/ringsaturn/tzf-rel"
	"github.com/ringsaturn/tzf/pb"
	"google.golang.org/protobuf/proto"
)

func main() {
	input := &pb.Timezones{}

	// Lite data, about 16.7MB
	dataFile := tzfrel.LiteData

	// Full data, about 83.5MB
	// dataFile := tzfrel.FullData

	if err := proto.Unmarshal(dataFile, input); err != nil {
		panic(err)
	}
	finder, _ := tzf.NewFinderFromPB(input)
	fmt.Println(finder.GetTimezoneName(116.6386, 40.0786))
}

Output:

Asia/Shanghai