geohash-spatial-code-maps

Geohash と空間コードマップのベストプラクティス

TypeScript と Rust で geohash を正しく実装する方法、大規模なクエリとインデックス作成の方法、そしてコードを平面に投影して geohash のプレフィックスを、Google マップのように移動できるドメイン領域にする「ナビゲート可能な 2D マップとしてのコードベース」パターンへの適用方法を解説します。8 つのカテゴリにわたる 42 のルールを、影響度順にまとめています。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• TypeScript または Rust で geohash のエンコーダー／デコーダー（ビットのインターリーブ、base32、精度、近傍）を実装またはレビューするとき
• 緯度／経度データに対する近接検索、半径検索、バウンディングボックス検索を構築するとき、または geohash をインデックスキー（SQL B-tree、Redis sorted sets）として保存するとき
• よくある geohash のバグ（軸の入れ替え、誤ったアルファベット、境界での偽陰性、高精度でのセルのオフバイワン）をデバッグするとき
• コードベース（または抽象グラフ）を 2D 平面に投影し、geohash を適用してプレフィックスをビジネスドメインや機能の名前として使うとき
• 地図のように geohash データセットをナビゲートするとき：精度に応じたズーム、ビューポートのタイル読み込み、詳細度の集約、プレフィックスによるクラスタリング、ディープリンク

対象範囲について

カテゴリ 1〜4、6、7 は、権威ある情報源（geohash の仕様、davetroy/geohash-js の近傍テーブル、Redis、Elasticsearch）に基づく、標準的な geohash の内容です。カテゴリ 5（map-）と 8（nav-）は、新しい知見をまとめたものです。「コードベースに geohash を適用する」ための標準ライブラリは存在しないため、これらのルールは、確立された手法（決定論的なグラフレイアウト、Morton／Z-order キー、スリッピーマップのタイル分割、ソフトウェアの地図化）から設計原則を導き出しています。このパターンが過剰な場合についても、率直に説明しています。

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス	ルール数
1	エンコーディングとビットのインターリーブ	重大	enc-	6
2	精度とセルの形状	重大	prec-	5
3	近傍と隣接関係	高	nbr-	5
4	近接検索と範囲検索	高	qry-	5
5	コードベースの空間レイアウト	高	map-	7
6	デコードとバウンディングボックス	中〜高	dec-	4
7	空間インデックス作成とストレージ	中〜高	idx-	5
8	ナビゲーションとレンダリング	中	nav-	5

クイックリファレンス

1. エンコーディングとビットのインターリーブ（重大）

• enc-interleave-longitude-first — 偶数ビットに経度、奇数ビットに緯度をインターリーブします
• enc-base32-alphabet — RFC 4648 ではなく、geohash の base32 アルファベットを使います
• enc-integer-morton-encode — 高速化とソート可能なキーのため、インターリーブした 64 ビット整数にエンコードします
• enc-binary-chop-no-float-drift — 区間の中点を再計算し、浮動小数点の増分を累積しないようにします
• enc-normalize-input-domain — 緯度をクランプし、経度を折り返し、有限でない入力を拒否します
• enc-five-bit-char-boundary — 文字ごとに正確に 5 ビットを蓄積します

2. 精度とセルの形状（重大）

• prec-choose-from-error-radius — 必要な誤差半径に基づいて geohash の長さを選びます
• prec-cells-are-not-square — 長さに応じてアスペクト比が変わる長方形としてセルを扱います
• prec-error-is-half-cell — デコードした精度はセル全体ではなく、セルの半分として報告します
• prec-cells-shrink-toward-poles — 経度方向の距離（メートル）に緯度の cos を掛けてスケーリングします
• prec-avoid-mixed-precision — 比較や保存の前に、精度を統一します

3. 隣接関係（HIGH）

• nbr-canonical-lookup-tables — 正規の境界／隣接テーブルを使って隣接セルを計算します
• nbr-antimeridian-wrap — 日付変更線をまたいで東西の隣接セルを折り返します
• nbr-pole-handling — 極を越える隣接セルは返しません
• nbr-integer-level-neighbors — インターリーブ解除した整数上で隣接セルを計算します
• nbr-eight-neighbor-set — 近接検索用に8つの隣接セル一式を構築します

4. 近接検索と範囲クエリ（HIGH）

• qry-search-cell-plus-neighbors — プレフィックスだけでは検索せず、セルと8つの隣接セルをクエリします
• qry-precision-from-radius — 検索半径に合わせてクエリの精度を調整します
• qry-bbox-range-decomposition — バウンディングボックスを、それをカバーするジオハッシュ範囲に分解します
• qry-refine-with-haversine — ジオハッシュ候補を実際の距離で絞り込みます
• qry-expand-precision-when-sparse — セルがまばらな場合、プレフィックス文字を1つ削除して検索範囲を広げます

5. コードベースを地図として扱う空間レイアウト（HIGH）

• map-deterministic-projection — 任意のレイアウトではなく、構造的なシグナルからコードを2Dに投影します
• map-stable-coordinates — 座標の再現性と、増分変更に対する安定性を確保します
• map-normalize-to-geohash-domain — コードの平面をジオハッシュの緯度／経度領域に正規化します
• map-coupling-implies-proximity — 関連付けられたコードが同じ領域に配置されることを検証します
• map-prefix-as-domain-region — ジオハッシュのプレフィックスを名前付きのドメイン領域として扱います
• map-precision-as-architectural-level — プレフィックスの長さをアーキテクチャレベルに対応付けます
• map-persist-coordinate-sidecar — ファイルとジオハッシュの対応関係をコミット済みのサイドカーファイルとして保存します

6. デコードとバウンディングボックス（MEDIUM-HIGH）

• dec-decode-to-bbox — バウンディングボックスにデコードしてから中心を求めます
• dec-symmetric-interval-reconstruction — エンコーダーの区間分割を反映してデコードします
• dec-avoid-roundtrip-reencode — 元のハッシュを保持し、デコード後に再エンコードしないようにします
• dec-precompute-reverse-alphabet — 事前計算した逆引きアルファベットテーブルを使ってデコードします

7. 空間インデックスとストレージ（MEDIUM-HIGH）

• idx-sorted-string-range-scan — プレフィックス範囲スキャン用に、ジオハッシュをソート済み文字列として保存します
• idx-integer-sortable-key — コンパクトでソート可能なキーとしてインターリーブ済み整数を使用します
• idx-db-prefix-index — Postgres と Redis でプレフィックスクエリを検索可能にします
• idx-range-query-from-covering-set — カバー範囲の集合に対する範囲スキャンとして、ボックスクエリを実行します
• idx-trie-hierarchical-bucketing — ジオハッシュトライを使って領域ごとに集約します

8. ナビゲーションとレンダリング（中）

• nav-precision-to-zoom-levels — ジオハッシュの精度をズームレベルに対応付けます
• nav-level-of-detail-aggregation — ズームアウトしたときに、集約したプレフィックスバケットをレンダリングします
• nav-tile-lazy-loading — ビューポート内のジオハッシュセルのみを読み込みます
• nav-cluster-by-prefix — 共通のプレフィックスを持つ重なり合ったマーカーをクラスタリングします
• nav-breadcrumb-prefix-path — ジオハッシュのプレフィックスをナビゲーション状態およびディープリンクとして使用します

使い方

詳しい説明、コード例、「適用すべきでない場合」のガイダンスについては、各リファレンスファイルをお読みください。

• セクションの定義 — カテゴリー構成と影響レベル
• ルールのテンプレート — 新しいルールを追加するためのテンプレート

ルール間は [[other-rule-slug]] で相互リンクされています。関連するパターンが参照されている場合は、それに従ってください。コードマップをエンドツーエンドで構築する際の基本的な流れは、map-deterministic-projection → map-normalize-to-geohash-domain → エンコード（カテゴリー1）→ map-prefix-as-domain-region → ナビゲーション（カテゴリー8）です。

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報