Go (tzf)

Install

tzf v2 is a new major version, so the module path carries the /v2 suffix:

go get github.com/ringsaturn/tzf/v2

import "github.com/ringsaturn/tzf/v2"

The package name is still tzf. v2 is protobuf-free: boundary data ships as.tzb (compact transport profile) and .tzm (memory-image profile) files fromringsaturn/tzf-dist, embedded withgo:embed. See Embedded Binary Format for the file format itself.

The five constructors

Every constructor returns the F interface. The package exports no finder types and no options.

Measured on an Apple M3 Max against the 2026c dataset.

The package documentation names NewDefaultFinder() as the general-purpose finder. Choosing a Finder covers the remaining cases: no-filesystem targets, cgroup-quota pods, and distribution size.

Finder reuse

Construction is expensive relative to a query: it opens the file, builds the query structures, and, for the expanded finders, decodes every polygon. A finder is safe for concurrent use, so a process builds one and reuses it. A package-level variable is one way to do that:

package main

import (
	"fmt"

	"github.com/ringsaturn/tzf/v2"
)

var f tzf.F

func init() {
	var err error
	f, err = tzf.NewDefaultFinder()
	if err != nil {
		panic(err)
	}
}

func main() {
	// Coordinates are in (longitude, latitude) order.
	fmt.Println(f.GetTimezoneName(116.3883, 39.9289))
	fmt.Println(f.GetTimezoneName(-73.935242, 40.730610))
}

The F interface

type F interface {
	GetTimezoneName(lng float64, lat float64) string
	GetTimezoneNames(lng float64, lat float64) ([]string, error)
	TimezoneNames() []string
	DataVersion() string
}

• GetTimezoneName: fuzzy-first. Every tzf-dist artifact carries a FUZZY preindex section, so a tile lookup answers most queries with no point-in-polygon work; near a border the finder falls back to ray casting. The method returns the empty string when nothing matches.
• GetTimezoneNames: polygon-exact in every finder. It does not consult the preindex, and it applies when a point may belong to more than one timezone. Results are sorted lexicographically, and the method returnstzf.ErrNoTimezoneFound when nothing matches.
• A point on a shared border belongs to every touching polygon. Nautical zone borders lie on whole meridians such as 7.5° and 22.5°.

names, err := f.GetTimezoneNames(87.4160, 44.0400)
// names == []string{"Asia/Shanghai", "Asia/Urumqi"}

GeoJSON export

GeoJSONer is kept out of F so that test doubles and third-party F implementations need not produce geometry. Every finder this package builds satisfies it, so assert the interface on the value the constructor returned:

finder, err := tzf.NewDefaultFinder()
if err != nil {
	panic(err)
}

g := finder.(tzf.GeoJSONer)

world := g.GetGeoJSON()                          // []byte, all timezones
tokyo, err := g.GetTZGeoJSON("Asia/Tokyo")       // []byte, one timezone
tiles, err := g.GetTZPreindexGeoJSON("Asia/Tokyo") // FUZZY tiles for one timezone
all, err := g.GetPreindexGeoJSON()               // the whole FUZZY preindex

All four methods return serialized GeoJSON bytes; the boundary-file types are internal to the module. The preindex exports cover the area whereGetTimezoneName answers from the preindex without falling back to point-in-polygon. A file without a FUZZY section returnstzf.ErrNoFuzzySection.

Bring your own bytes

Read a file from disk, an object store, or your own go:embed, then pick the constructor that matches the profile:

data, err := os.ReadFile("lite.tzb")
if err != nil {
	panic(err)
}
finder, err := tzf.NewFinderFromTZB(data) // expanded; data may be released

data, err := os.ReadFile("lite.tzm")
if err != nil {
	panic(err)
}
finder, err := tzf.NewFinderFromTZM(data) // aliased in place; data must stay live

A .tzm finder’s ring slices alias the source bytes, which must stay live and unmodified for the finder’s lifetime.

The M profile is generated on the host that uses it, from the .tzb file:

# usage: tzb2tzm [-o output] input.tzb
go run github.com/ringsaturn/tzf/v2/cmd/tzb2tzm@latest lite.tzb

In-place queries over caller-owned bytes

x.NewFinderFromTZBReaderAt queries a .tzb through an io.ReaderAt — a file, an mmap’d region, an embedded flash adapter, or a bytes.Reader over bytes you already hold. Queries are allocation-free and the heap cost stays under 1 KB:

import (
	"bytes"

	"github.com/ringsaturn/tzf/v2/x"
)

finder, err := x.NewFinderFromTZBReaderAt(bytes.NewReader(data), int64(len(data)))
if err != nil {
	panic(err)
}
fmt.Println(finder.GetTimezoneName(151.2093, -33.8688))

The x package is exempt from the module’s semantic-versioning promise: a minor version bump may change or remove its API. The root package changes incompatibly only at a major version.

Migrating from v1

v1 (github.com/ringsaturn/tzf, latest v1.2.x) remains available. It is frozen at its final protobuf data release: tzf-dist stops publishing the .bin artifacts once the v2 set ships.

The four F methods are unchanged, so code that only callsGetTimezoneName / GetTimezoneNames / TimezoneNames / DataVersion needs nothing beyond the import-path change.

Boundary semantics

v2 answers on-edge queries the same way v1 does aftertzf#216: a point on a shared border belongs to every touching polygon, with exterior rings allowing on-edge containment and hole rings not. Code pinned to an earlier v1 patch release will see border points that previously returned no result return a name.