tzf: a fast timezone finder for Go.

• Released documentation: https://pkg.go.dev/github.com/ringsaturn/tzf/v2
• Try it online: tzf-web

[!NOTE]

Version 2 is protobuf-free. The data source is the TZF embedded binary format (.tzb) and its memory-image profile (.tzm), shipped by tzf-dist, and the public surface is five constructors that all return tzf.F. See Migrating from v1.

Quick Start

Install via:

go get github.com/ringsaturn/tzf/v2

[!NOTE]

NewDefaultFinder uses simplified shape data so it is not entirely accurate around the border, but the error is small and bounded: every simplified boundary stays within ~111 m of the full-precision border. See Accuracy for measured numbers.

It's expensive to init a tzf finder, please consider reusing it or creating it as a global var. Below is a global var example:

package main

import (
	"fmt"

	tzf "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() {
	// In longitude-latitude order
	fmt.Println(f.GetTimezoneName(116.3883, 39.9289))
	fmt.Println(f.GetTimezoneName(-73.935242, 40.730610))
}

Every finder is safe for concurrent use.

Finders

v2 exposes exactly five constructors, all returning the same tzf.F interface (GetTimezoneName, GetTimezoneNames, TimezoneNames, DataVersion); the mechanism behind a finder is not part of the API. All bundled artifacts carry the same dataset (2026c, 444 timezone names); the mechanism and the precision differ between them.

Measured on Apple M3 Max with the 2026c dataset (make bench, make bench-memory); "memory" is retained heap after GC, so the rodata the go:embeded artifact occupies is listed separately.

GetTimezoneName is fuzzy-first: every bundled artifact carries a FUZZY preindex section, so most queries resolve from a tile lookup without any point-in-polygon work, and near a border the query falls through to exact ray casting.

GetTimezoneNames runs the polygon scan in every finder. It is the call to use when a point can belong to more than one timezone, which happens at the nautical zone meridians and at disputed borders. Results are sorted lexicographically, and a point exactly on a shared border belongs to every touching polygon.

Full-precision lookups with NewFullFinder

If you require a query result that is 100% accurate, use the full-precision finder (reuse it when possible):

package main

import (
	"fmt"

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

func main() {
	finder, err := tzf.NewFullFinder()
	if err != nil {
		panic(err)
	}

	fmt.Println(finder.GetTimezoneName(139.6917, 35.6895))
}

NewFullFinder() is more expensive to init and uses much more memory than NewDefaultFinder(), but it provides 100% accuracy. See Performance for details.

Best practices and deployment matrix

The choice between constructors is governed by memory and startup cost. On a random city, median query latency is 208 ns for both NewDefaultFinder and NewFullFinder (Apple M3 Max, 2026c); the two differ on the 0.41% of boundary length the simplification displaces by more than 100 m (see Accuracy) and in retained heap.

Open times on Apple M3 Max with the 2026c dataset (16 cores / 1 core, the single-core figure modelling a cgroup-quota pod):

Deriving a .tzm locally

.tzb is the transport format. .tzm holds the same data in the layout the query path uses directly, which makes the file larger; tzf-dist ships a lite.tzm for NewDefaultFinder, and no full-precision .tzm is distributed. Derive one locally to use the memory-image mechanism over your own data:

go run github.com/ringsaturn/tzf/v2/cmd/tzb2tzm@latest -o lite.tzm lite.tzb

The transcode is protobuf-free and its output is byte-identical to building the .tzm from source, so the compact .tzb can be shipped and the memory image produced at deploy time or during the image build.

The two byte constructors differ in their contract for data: NewFinderFromTZB releases it once loading is done. NewFinderFromTZM uses it as live polygon storage, so the bytes must stay live and unmodified for the finder's lifetime. Aliasing also requires the slice to be 8-byte aligned; a misaligned or big-endian host falls back to a one-time decoded copy, which produces the same results and does not reduce memory.

Advanced Usage: export GeoJSON

F covers the four query methods only, so GeoJSONer is a separate interface and test doubles and third-party F implementations need not produce geometry. Constructors return F, so assert the behavior:

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

exporter, ok := finder.(tzf.GeoJSONer)
if !ok {
	panic("finder cannot export geometry")
}

// Serialized GeoJSON FeatureCollection bytes.
tokyo, err := exporter.GetTZGeoJSON("Asia/Tokyo")
world := exporter.GetGeoJSON()

// The preindex tiles GetTimezoneName answers from directly — useful for
// visualizing where the fast path applies.
tiles, err := exporter.GetTZPreindexGeoJSON("Asia/Tokyo")
allTiles, err := exporter.GetPreindexGeoJSON()

Every finder this package constructs satisfies GeoJSONer, including NewEmbeddedFinder, which decodes only the requested timezone's rings from the file on demand. Output is byte-identical across mechanisms.

[!NOTE]

This feature is designed for data visualization purposes. Please do proper performance tests before using it in a high-performance production path, for example by caching the exported GeoJSON or pushing it to a CDN.

The x package

github.com/ringsaturn/tzf/v2/x holds experimental surface: useful in production, and exempt from the module's semantic-versioning promise. Within v2.y.z, a bump of y may change or remove anything in x; only z bumps are guaranteed not to. The root package keeps the normal promise: breaking changes only at v3. The convention follows golang.org/x/...; pin an exact version if you depend on x and cannot absorb a break at a minor release.

It holds one entry point, for in-place queries over any io.ReaderAt: a file, an mmap'd region, an embedded flash adapter, or a bytes.Reader over bytes already in memory.

import (
	"bytes"

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

// In-place over caller-owned bytes (v2 has no InPlace() option):
finder, err := x.NewFinderFromTZBReaderAt(bytes.NewReader(data), int64(len(data)))

// Or straight off a file, without reading it into memory:
file, err := os.Open("lite.tzb")
info, err := file.Stat()
finder, err := x.NewFinderFromTZBReaderAt(file, info.Size())

Semantics match NewEmbeddedFinder, including the FUZZY fast path, and the result satisfies tzf.GeoJSONer. Queries are allocation-free in steady state and scale with core count: each decodes through a pooled fixed-size workspace (a sync.Pool, refilled with one small allocation after a GC cycle), so the only serialization is whatever the io.ReaderAt source itself imposes (an os.File uses pread and needs none).

CLI Tool

In addition to using tzf as a library in your Go projects, you can also use the tzf command-line interface (CLI) tool to quickly get the timezone name for a set of coordinates. To use the CLI tool, you first need to install it using the following command:

go install github.com/ringsaturn/tzf/v2/cmd/tzf@latest

Once installed, you can use the tzf command followed by the latitude and longitude values to get the timezone name:

tzf -lng 116.3883 -lat 39.9289

Alternatively if you want to look up multiple coordinates efficiently you can specify the ordering and pipe them to the tzf command one pair of coordinates per line:

echo -e "116.3883 39.9289\n116.3883, 39.9289" | tzf -stdin-order lng-lat

Data

You can download the original data from https://github.com/evansiroky/timezone-boundary-builder.

The preprocessed binary data can be obtained from https://github.com/ringsaturn/tzf-dist, which has Go's embed support. The artifact set is:

All three carry the same data_version, and every file bundles its FUZZY preindex section, so there is no separate preindex artifact to keep in sync. The .tzb container is a sectioned little-endian format with a CRC32 footer; .tzm holds the same content in the profile whose sections are already the query-time structures.

The data pipeline for tzf can be illustrated as follows. It runs directly from the upstream raw GeoJSON, with no protobuf step at any stage; the gob intermediates are build-internal and are never distributed:

graph TD
    Raw[GeoJSON from evansiroky/timezone-boundary-builder]
    Full[Timezones .gob, full precision]
    Simplified[Timezones .topology.gob<br/>topology-aware simplified]
    SimplifiedTopo[TopoTimezones .topology.topo.gob]
    FullTopo[TopoTimezones .topo.gob]
    SimplifiedCompressTopo[CompressedTopoTimezones<br/>.topology.compress.topo.gob]
    FullCompressTopo[CompressedTopoTimezones<br/>.compress.topo.gob]
    Preindex[PreindexTimezones<br/>.topology.preindex.gob]
    LiteTZB[lite.tzb ~4MB]
    LiteTZM[lite.tzm ~10MB]
    FullTZB[full.tzb ~14MB]

    Raw --> |cmd/geojson2tzpb|Full
    Full --> |cmd/reducetzpb -topology|Simplified
    Full --> |cmd/deduplicatetzpb|FullTopo
    FullTopo --> |cmd/compresstopotzpb|FullCompressTopo
    Simplified --> |cmd/deduplicatetzpb|SimplifiedTopo
    SimplifiedTopo --> |cmd/compresstopotzpb|SimplifiedCompressTopo
    Simplified --> |cmd/preindextzpb|Preindex

    SimplifiedCompressTopo --> |cmd/topo2embed -profile e -preindex|LiteTZB
    Preindex --> |cmd/topo2embed -preindex|LiteTZB
    LiteTZB --> |cmd/tzb2tzm|LiteTZM
    FullCompressTopo --> |cmd/topo2embed -profile e -preindex|FullTZB
    Preindex --> |cmd/topo2embed -preindex|FullTZB

    LiteTZM --> |tzf.NewDefaultFinder|D[DefaultFinder]
    LiteTZB --> |tzf.NewEmbeddedFinder|E[EmbeddedFinder]
    FullTZB --> |tzf.NewFullFinder|F[FullFinder]

full.tzb preserves full geometric precision with shared-edge deduplication and polyline compression. lite.tzb / lite.tzm apply topology-aware Douglas-Peucker simplification (~85% point reduction) first, so they may not be perfectly accurate at some border areas; the deviation is bounded to ~111 m (see Accuracy).

I have written an article about the history of tzf, its Rust port, and its Rust port's Python binding; you can view it here.

Accuracy

The Douglas-Peucker simplification uses an epsilon of 0.001 degrees, which caps boundary displacement at roughly 111 m by construction. Measured against the full-precision 2026c dataset with internal/cmd/borderchange (spherical model, certified via Lipschitz interval subdivision):

In other words, only queries that land within ~111 m of a timezone border can ever differ from the full-precision result, and most of that band is far narrower. If your use case is sensitive inside that band, use NewFullFinder().

Verify the accuracy yourself by running the following commands:

# Runs the pipeline from the upstream raw GeoJSON; the gob intermediates
# land in tmp/tzf-dist-dev.
./scripts/build-tzf-dist-dev.sh

go run ./internal/cmd/topodecode \
  tmp/tzf-dist-dev/combined-with-oceans.compress.topo.gob \
  combined-with-oceans.dist.gob

go run ./internal/cmd/borderchange \
  -epsilon 0.001 \
  -certification-tolerance-m 0.5 \
  -top-pairs 20 \
  combined-with-oceans.dist.gob > BORDER_CHANGE.md

More details: BORDER_CHANGE.md.

Performance

The tzf package is intended for high-performance geospatial query backend services, such as weather forecasting APIs. Median query latency is 208 ns on random world cities and 542 ns on border cases for NewDefaultFinder (Apple M3 Max, 2026c).

Here is what has been done to improve performance:

1. Using the simplified dataset by default.
2. Using the pre-index carried in the file's FUZZY section to handle most queries without any point-in-polygon work.
3. Using the internal geom package (fork of geojson) with a YStripes index (inspired by Josh Baker's tg) to verify whether a polygon contains a point. Also a dense 1°×1° grid index carried by the file to quickly find candidate polygons, inspired by Aaron Roney's rtz.
4. Storing ring coordinates as 1e5-scaled int32 pairs (8 bytes per point). In the .tzm profile these are aliased directly from the embedded bytes, so no geometry is copied onto the heap at load.

That's all. There are no black magic tricks inside the tzf package.

Below is a benchmark run on my MacBook Pro with Apple M3 Max, 2026c dataset (make bench, make bench-memory). Memory is retained heap after GC, so the in-place finders report 0.00: their storage is the embedded read-only data.

• https://ringsaturn.github.io/tz-benchmark/ displays a continuous benchmark comparison with other packages.

Migrating from v1

v1 loaded protobuf artifacts (CompressedTopoTimezones, PreindexTimezones); those artifacts are no longer published, and v2 removes every protobuf-typed API. The v1 line is frozen at its last data release; updated boundaries require moving to v2.

Update the import path (github.com/ringsaturn/tzf → github.com/ringsaturn/tzf/v2), then map the call sites:

Behavior changes:

• GetTZGeoJSON / GetGeoJSON return serialized GeoJSON bytes; the *convert.BoundaryFile return type is gone and the boundary-file types are internal. Unmarshal into your own struct, or into map[string]any, when the parsed tree is needed.
• GetTimezoneNames results are sorted lexicographically.
• A point exactly on a shared border belongs to every touching polygon (exterior rings allow on-edge, hole rings do not).
• New: NewEmbeddedFinder, an in-place low-memory mechanism (~4 MB total).

Related Repos

See Project tzf for more information.

Thanks

• https://github.com/paulmach/orb (used via the ringsaturn/orb fork, which drops the BSON/mongo-driver dependency)
• https://github.com/tidwall/geojson
• https://github.com/tidwall/tg
• https://github.com/jannikmi/timezonefinder
• https://github.com/evansiroky/timezone-boundary-builder
• And other projects listed in NOTICE

Citation

If you use tzf in academic work, please cite it via CITATION.cff, or use GitHub's "Cite this repository" button.

LICENSE

This project is licensed under the MIT license. The data is licensed under the ODbL license, same as evansiroky/timezone-boundary-builder