よくある質問
座標の順序は？
すべての tzf 実装は (経度，緯度) の順序を使用します。GeoJSON やほとんどの地理 API と同じです。一部のシステム（Google Maps URL、多くの地理教科書など）では (緯度，経度) を使用するため、値を渡す前に再確認してください。
tzf は 100% 正確ですか？
デフォルトの Finder は、タイムゾーン境界付近で完全精度データセットと同じ結果を保証しません。epsilon が 0.001 度のトポロジー対応 Douglas-Peucker 簡略化を使用し、境界の変位を約 111 m 以内に抑えています。
完全精度の 2026c データセットと比較した測定結果は BORDER_CHANGE.md に記録されています。
| 指標 | 結果 |
|---|---|
| 認証済みの最大境界変位 | 111.2 m、許容誤差 1.0 m |
| 100 m を超えて変位した境界長の割合 | 0.41% |
| 500 m を超えて変位した境界長の割合 | 0% |
| 誤って割り当てられた総面積 | 16,828 km²、地球面積の約 0.003% |
| 真の境界から 100 m 以内にある誤割当面積の割合 | 92.8% |
完全精度の結果と異なる可能性があるのは、タイムゾーン境界から約 111 m 以内のクエリのみです。影響を受ける帯域の大部分はさらに狭くなっています。
100% 正確な検索には、完全データセットを使用してください：
- Go:
tzf.NewFullFinder() - Rust:
fullfeature を有効にする（はじめるを参照） - Python/tzfpy: 完全精度モードは現在サポートされていません
tzf はどのくらいメモリを使用しますか？
初期化コストと実行時コストは同じ数値ではありません。finder の構築では .pb データセット全体を中間表現にデコードし、そこからクエリ構造を組み立てたうえで中間表現を破棄します。しかしメモリを解放しても RSS は縮みません。アロケータが再利用のためにページを保持し続けるからです。そのため、finder が定常状態で実際に保持しているデータは、ロード中の高水位より数倍小さくなります。
以下の数値は、Apple M3 Max で測定した 2026-07-26 ベンチマークスナップショットの値です。
| 実装 | モード | 初期化ピーク | 常駐 |
|---|---|---|---|
| Go | FuzzyFinder（プレインデックスのみ） | 30.4 MiB | 2.6 MiB |
| Go | Finder（トポロジー簡略化） | 127.8 MiB | 30.0 MiB |
| Go | DefaultFinder（簡略化 + プレインデックス） | 124.3 MiB | 32.3 MiB |
| Go | FullFinder（完全精度 + プレインデックス） | 359.4 MiB | 155.7 MiB |
| Rust | FuzzyFinder（プレインデックスのみ） | 23.8 MiB | 5.1 MiB |
| Rust | Finder（トポロジー簡略化） | 48.0 MiB | 20.7 MiB |
| Rust | DefaultFinder（簡略化 + プレインデックス） | 77.0 MiB | 36.3 MiB |
| Python | tzfpy DefaultFinder | 94.8 MiB | n/a |
- 初期化ピークは、ロード中に到達する高水位（
ru_maxrss）です。コンテナのメモリ上限はこの値を収容できる必要があります。そうでなければ、定常状態なら収まるはずのプロセスが起動時に kill されます。 - 常駐は、finder がクエリを処理できる状態になった後に実際に保持しているデータ量で、言語ネイティブの計測（Go は強制 GC 後の
HeapAlloc、Rust はカウント機能付きグローバルアロケータ）によるものです。Python は Python ヒープの外にデータを保持するためn/aです。
コンテナのメモリは初期化ピークに合わせて確保しつつ、長期運用時の実コストは常駐値で見積もってください。実際のメモリ使用量は、プラットフォーム、アロケータ、データセットのバージョンによって異なります。
初期化が遅いのはなぜですか？
NewDefaultFinder() / DefaultFinder::new() の最初の呼び出しは、バイナリタイムゾーンデータを読み込んで解析します。これは一度限りのコストで、その後の検索は非常に高速です。常に一度だけ初期化し、インスタンスを再利用してください。グローバル変数や lazy_static を使用するパターンについては、各言語ガイドを参照してください。
タイムゾーンデータはどのくらいの頻度で更新されますか？
tzf は evansiroky/timezone-boundary-builder 経由で IANA タイムゾーンデータベースのリリースを追跡しています。処理済みデータは ringsaturn/tzf-rel で公開されています。ライブラリのリリースは各上流データリリースの直後に行われます。
Finder、FuzzyFinder、DefaultFinder の違いは何ですか？
| クラス | 使用データ | カバレッジ | 速度 |
|---|---|---|---|
FuzzyFinder | タイルプレインデックスのみ | 内部タイルのみ、境界/未カバーエリアは結果なし | 最速 |
Finder | ポリゴンデータ | 全世界をカバー | 高速 |
DefaultFinder | タイルプレインデックス + ポリゴン | 全世界をカバー | 高速 |
FuzzyFinder プレインデックスは、単一のタイムゾーンポリゴン内に完全に収まるタイルのみを保存します。クエリポイントがカバーされたタイル内にある場合、すぐに正しいタイムゾーンを返します。カバーされていないエリア（境界付近、海岸線、疎な地域）では、推測せずに結果なしを返します。「近似」ではありません：結果は正確ですが、カバレッジが不完全です。
DefaultFinder（推奨）は、最初にタイルプレインデックスを試み、結果が返されなかった場合に完全なポリゴン検索にフォールバックします。これにより、ほとんどの世界都市クエリでほぼ一定の速度を保ちながら、すべての座標に対して正確な結果を得られます。
tzf はどのようなライセンスですか？
コードは MIT ライセンスです。タイムゾーンデータ（tzf-rel 経由で配布）は上流の evansiroky/timezone-boundary-builder と同様に ODbL です。
また、tzf、tzf-rs、tzfpy には「反 CSDN ライセンス」条項が付随しており、CSDN プラットフォームでの使用を禁止しています。この条項は他のユースケースに影響しません。
詳細は ライセンス を参照してください。