Getting Started

Project tzf provides multi-language support for looking up a timezone by longitude and latitude.

Language or Server	Repository	API Docs
Go	`ringsaturn/tzf`
Rust	`ringsaturn/tzf-rs`
Python	`ringsaturn/tzfpy`	`tzfpy.pyi`
Swift	`ringsaturn/tzf-swift`
Ruby	`HarlemSquirrel/tzf-rb`
JS via Wasm (browser)	`ringsaturn/tzf-wasm`
HTTP API	`racemap/rust-tz-service`
Online Demo	`ringsaturn/tzf-web`

Go

go get github.com/ringsaturn/tzf

// Use about 150MB memory for init, and 60MB after GC.
package main

import (
	"fmt"

	"github.com/ringsaturn/tzf"
)

func main() {
	finder, err := tzf.NewDefaultFinder()
	if err != nil {
		panic(err)
	}
	fmt.Println(finder.GetTimezoneName(116.6386, 40.0786))
}

For 100% accurate results, use NewFullFinder (reuse it when possible — initialization is expensive):

package main

import (
	"fmt"

	"github.com/ringsaturn/tzf"
)

func main() {
	finder, err := tzf.NewFullFinder()
	if err != nil {
		panic(err)
	}
	fmt.Println(finder.GetTimezoneName(139.6917, 35.6895))
}

Rust

cargo add tzf-rs

use lazy_static::lazy_static;
use tzf_rs::DefaultFinder;

lazy_static! {
    static ref FINDER: DefaultFinder = DefaultFinder::new();
}

fn main() {
    // Coordinates are in (longitude, latitude) order.
    print!("{:?}\n", FINDER.get_tz_name(116.3883, 39.9289));
    print!("{:?}\n", FINDER.get_tz_names(116.3883, 39.9289));
}

Full-precision support (v1.3.0+)

Since v1.3.0, full-precision data is available via an optional Cargo feature. Because the full dataset (~17 MB) exceeds crates.io size limits, it must be referenced via a git dependency:

[dependencies]
tzf-rs = { git = "https://github.com/ringsaturn/tzf-rs", tag = "v{X}.{Y}.{Z}", features = ["full"], default-features = false }

use tzf_rs::DefaultFinder;

fn main() {
    let finder = DefaultFinder::new_full();
    let tz_name = finder.get_tz_name(139.767125, 35.681236);
    println!("tz_name: {}", tz_name);
}

Python

# Install just tzfpy
pip install tzfpy

# Install with pytz
pip install "tzfpy[pytz]"

# Install with tzdata
pip install "tzfpy[tzdata]"

# Install via conda
conda install -c conda-forge tzfpy

>>> from tzfpy import get_tz, get_tzs
>>> get_tz(116.3883, 39.9289)   # (longitude, latitude) order
'Asia/Shanghai'
>>> get_tzs(87.4160, 44.0400)   # returns all matching timezones
['Asia/Shanghai', 'Asia/Urumqi']

Python does not support full-precision mode.

Swift

Add the package to your Package.swift:

dependencies: [
    .package(url: "https://github.com/ringsaturn/tzf-swift.git", from: "{latest_version}")
]

import Foundation
import tzf

do {
    let finder = try DefaultFinder()

    let timezone = try finder.getTimezone(lng: 116.3833, lat: 39.9167)
    print("Beijing timezone:", timezone)

    let timezones = try finder.getTimezones(lng: 87.5703, lat: 43.8146)
    print("Multiple possible timezones:", timezones)

    print("Data version:", finder.dataVersion())
} catch {
    print("Error:", error)
}

Ruby

Ruby support is created and maintained by HarlemSquirrel. See tzf-rb for detailed documentation.

bundle add tzf
# or
gem install tzf

require 'tzf'

TZF.tz_name(40.74771675713742, -73.99350390136448)
# => "America/New_York"

TZF.tz_names(40.74771675713742, -73.99350390136448)
# => ["America/New_York"]

WebAssembly

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>tzf-wasm Example</title>
    <script type="module">
      import init, { WasmFinder } from "https://www.unpkg.com/tzf-wasm@v0.1.4/tzf_wasm.js";

      async function loadWasm() {
        await init();
        const finder = new WasmFinder();
        const timezone = finder.get_tz_name(-74.006, 40.7128);
        console.log("Timezone for New York:", timezone);
      }

      loadWasm();
    </script>
  </head>
  <body></body>
</html>

Online preview: http://ringsaturn.github.io/tzf-web/

CLI

Both the Go and Rust implementations ship a command-line tool.

Go CLI

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

tzf -lng 116.3883 -lat 39.9289

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

Rust CLI

cargo install tzf-rs

tzf --lng 116.3883 --lat 39.9289

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

NixOS users can install tzf-rs via Nix — see NixOS packages for details.