用語集
API の動作
座標順序
すべての tzf 実装は (経度，緯度) の順序を使用します。GeoJSON やほとんどの地理 API と同じです。一部のシステム（Google Maps URL、多くの教科書）では (緯度，経度) を使用するため、値を渡す前に再確認してください。
複数タイムゾーン
タイムゾーン境界付近の地点は複数のタイムゾーンに属する場合があります。複数結果 API を使用してすべての候補を取得してください：
| 言語 | 関数 |
|---|---|
| Go | GetTimezoneNames() |
| Rust | get_tz_names() |
| Python | get_tzs() |
| Swift | getTimezones() |
Finder クラス
FuzzyFinder
タイルプレインデックスのみを使用します。インデックス内の各タイルは、単一のタイムゾーンポリゴン内に完全に収まる領域をカバーします。
- ポイントがカバーされたタイル内にある → ポリゴンテストなしで正しいタイムゾーンを即座に返します。
- ポイントがカバーされたタイルの外にある（境界付近、海岸線、疎な地域）→ 結果なしを返します。
カバーされたタイルの結果は正確です。呼び出し側は空結果を処理する必要があります。最速のオプション（約 470 ns / 約 9 MB）ですが、すべての座標をカバーするわけではありません。
Finder
トポロジー簡略化データセットと YStripes インデックスを使用した完全なポリゴン検索。全世界の座標をカバーします（約 1 から 2 µs、約 66 MB）。
DefaultFinder
FuzzyFinder と Finder を組み合わせたものです：まずタイルプレインデックスを参照し、結果が返されなかった場合に完全なポリゴン検索にフォールバックします。大部分の内部クエリにプレインデックスの速度を提供しつつ、すべての座標で正確な結果を保証します（約 1 µs、約 75 MB）。ほとんどのユースケースで推奨。
データバージョン
タイムゾーン境界データのバージョン識別子（例："2025b"）。evansiroky/timezone-boundary-builder 経由でIANA タイムゾーンデータベースのリリースを追跡します。data_version() (Python)、DataVersion() (Go)、data_version() (Rust) で実行時にアクセス可能です。
データファイル
tzf-dist
2026 年春に導入された現在のデータ配布リポジトリ（ringsaturn/tzf-dist）。処理済みバイナリデータを Go モジュールと Rust crate の両方として配布します。古い tzf-rel / tzf-rel-lite リポジトリを置き換えます（非推奨予定）。
データファイル
tzf-dist が提供する 3 つのバイナリファイル、すべて CompressedTopoTimezones 形式：
| ファイル | サイズ | 用途 |
|---|---|---|
combined-with-oceans.compress.topo.bin | 約 17 MB | 完全精度データ |
combined-with-oceans.topology.compress.topo.bin | 約 5.4 MB | トポロジー簡略化（デフォルト） |
combined-with-oceans.topology.preindex.bin | 約 2 MB | FuzzyFinder 用タイルプレインデックス |
tzf-rel / tzf-rel-lite（非推奨）
以前のデータ配布リポジトリ。現在は tzf-dist に取って代わられています。引き続き機能しますが、更新は行われません。
アルゴリズムとインデックス
ポリゴン簡略化
Ramer-Douglas-Peucker (RDP) アルゴリズムを適用して、タイムゾーン境界ポリゴンのポイント数を削減します。生の protobuf データをメモリ内の約 900 MB からディスク上の約 11 MB に縮小し、許容可能な精度損失（境界から約 1 km 以内で誤った結果が出る可能性があります）を伴います。
トポロジー認識簡略化
ポリゴンごとの RDP を強化し、共有境界でのギャップ/重複問題を修正します （tzf#183）。
隣接ポリゴン間の共有エッジを最初に検出し、一度だけ簡略化してから、両方のポリゴンに反映します。これにより、簡略化によって新しいギャップや重複が生じるのを防ぎます。
tzf v1.1.0（2026 年春）で導入。実装詳細：internal/topology/README.md。
タイルベースインデックス
FuzzyFinder が使用する事前計算された空間インデックス。地球表面を固定ズームレベルで四辺形タイルに分割します（地図タイル形式に着想）。タイルは、1 つのタイムゾーンポリゴンに完全に含まれる場合のみインデックスに追加されます。境界タイルは意図的に除外されます。内部ポイントに対してポリゴンテストなしの O(1) プレフィルタリングを可能にします。
YStripes インデックス
Josh Baker の tidwall/tg から移植されたポリゴンごとの空間インデックス。各ポリゴンのエッジを水平ストライプに分割し、クエリポイントに対して該当するストライプ内のエッジのみをテストします。tzf v1.1.0 (Go) および tzf-rs v1.2.0 (Rust) 以降デフォルト。最新ハードウェアで単一ランダム都市検索を約 1 µs にします。アルゴリズム詳細：POLYGON_INDEXING.md。
パフォーマンス
メモリ使用量
Go 実装のおおよその数値（Rust も同様）：
| モード | メモリ |
|---|---|
| DefaultFinder（トポロジー簡略化 + プレインデックス） | 約 75 MB |
| Finder（トポロジー簡略化） | 約 66 MB |
| FullFinder（完全精度 + プレインデックス） | 約 422 MB |
| FullFinder（完全精度のみ） | 約 413 MB |
Rust で YStripes インデックスを有効にすると、インデックスなしのベースラインから約 30 から 40 MB 増加します。 Rust の完全精度モード（YStripes 有効）は約 560 MB 必要です。 Python (tzfpy) は内部的に Rust バイナリを使用します。デフォルトモードでは約 120 MB を想定してください。
内部実装
CGO vs PyO3
tzfpy は当初 CGO 経由で Go 実装を呼び出し、.so ファイルにコンパイルしていました。
v0.11.0 以降は PyO3 を使用して tzf-rs (Rust) をラップしています。
PyO3 は FFI 境界を越えてオブジェクトのライフタイムを手動管理する必要がなくなり、
CGO が引き起こしていたメモリリーク（tzf#63）を解消し、
CPU 集約的なワークロードでより優れたスループットを提供します。