Skip to main content

japan_reverse_geocoder/
geocoder.rs

1use crate::error::Error;
2use crate::store::Store;
3use jismeshcode::{coord_to_mesh, haversine_distance, Coordinate, MeshLevel};
4use std::io::Read;
5use std::path::Path;
6
7/// 大字・町丁目の住所情報
8///
9/// 文字列フィールドは[`Geocoder`]内部の文字列テーブルへの参照です。
10#[derive(Debug, Clone, Copy, PartialEq)]
11pub struct Address<'a> {
12    /// 都道府県名(例: "東京都")
13    pub prefecture: &'a str,
14    /// 都道府県コード(JIS X 0401、1〜47)
15    pub prefecture_code: u8,
16    /// 市区町村名(例: "千代田区")
17    pub city: &'a str,
18    /// 市区町村コード(JIS X 0402、5桁)
19    pub city_code: u32,
20    /// 大字町丁目名(例: "丸の内一丁目")
21    pub town: &'a str,
22    /// 大字町丁目コード(12桁)
23    pub town_code: u64,
24    /// 代表点の緯度(10進度)
25    pub lat: f64,
26    /// 代表点の経度(10進度)
27    pub lon: f64,
28}
29
30/// 逆ジオコーディングの結果
31#[derive(Debug, Clone, Copy, PartialEq)]
32pub struct ReverseGeocodeResult<'a> {
33    /// 住所情報
34    pub address: Address<'a>,
35    /// クエリ座標から代表点までのHaversine距離(メートル)
36    pub distance_meters: f64,
37}
38
39/// 逆ジオコーディングエンジン
40///
41/// 国土交通省「位置参照情報」(大字・町丁目レベル)の代表点データを保持し、
42/// 座標から最寄りの大字・町丁目を検索します。
43///
44/// # 注意
45///
46/// 位置参照情報は各町丁目の**代表点**(ポリゴンではない)のデータです。
47/// 検索結果は「代表点が最も近い町丁目」であり、厳密に「その座標を含む町丁目」
48/// とは限りません。町丁目の境界付近では隣の町丁目が返ることがあります。
49pub struct Geocoder {
50    store: Store,
51}
52
53/// リング探索の上限(日本のメッシュ範囲全体をカバーする値より大きい)
54const MAX_RING: i32 = 400;
55
56/// 緯度1度あたりの距離の下限(メートル)。打ち切り判定の過小評価用
57const LAT_DEG_METERS_MIN: f64 = 110_000.0;
58
59/// 経度1度あたりの距離の下限(メートル)。111,320 × cos(46°) を切り下げた値
60const LON_DEG_METERS_MIN: f64 = 77_000.0;
61
62/// 2次メッシュセルの緯度方向サイズ(度): 5分
63const CELL_LAT_DEG: f64 = 1.0 / 12.0;
64
65/// 2次メッシュセルの経度方向サイズ(度): 7.5分
66const CELL_LON_DEG: f64 = 1.0 / 8.0;
67
68/// `ring`まで探索済みの矩形領域の外にあるレコードとの距離の下限(メートル)
69///
70/// 探索済み矩形は行 `[row0-ring, row0+ring]`、列 `[col0-ring, col0+ring]`。
71/// 未探索の点はクエリと緯度差または経度差が矩形境界までのギャップ以上あるため、
72/// その座標差に保守的な距離換算係数(日本の範囲での下限)を掛けた値が下限になる。
73fn min_unexplored_distance(query: Coordinate, row0: i32, col0: i32, ring: i32) -> f64 {
74    let south_gap = query.lat() - (row0 - ring) as f64 * CELL_LAT_DEG;
75    let north_gap = ((row0 + ring + 1) as f64) * CELL_LAT_DEG - query.lat();
76    let west_gap = query.lon() - (100.0 + (col0 - ring) as f64 * CELL_LON_DEG);
77    let east_gap = (100.0 + (col0 + ring + 1) as f64 * CELL_LON_DEG) - query.lon();
78
79    let lat_bound = south_gap.min(north_gap).max(0.0) * LAT_DEG_METERS_MIN;
80    let lon_bound = west_gap.min(east_gap).max(0.0) * LON_DEG_METERS_MIN;
81    lat_bound.min(lon_bound)
82}
83
84impl Geocoder {
85    /// 同梱データから構築する
86    ///
87    /// 全国の大字・町丁目データ(約19万件)を展開するため、
88    /// 数十ミリ秒程度かかります。アプリケーションで使い回してください。
89    #[cfg(feature = "embedded-data")]
90    #[allow(clippy::new_without_default)]
91    pub fn new() -> Self {
92        static DATA: &[u8] = include_bytes!("../data/isj.bin");
93        let store = Store::from_compressed(DATA).expect("embedded data must be valid");
94        Geocoder { store }
95    }
96
97    /// データファイルから構築する
98    ///
99    /// `embedded-data`フィーチャーを無効にした場合、データファイルは
100    /// GitHub Releasesから取得するか、`tools/build-data`で生成してください。
101    pub fn from_path(path: impl AsRef<Path>) -> Result<Self, Error> {
102        let bytes = std::fs::read(path)?;
103        Self::from_bytes(&bytes)
104    }
105
106    /// リーダーから構築する
107    pub fn from_reader(mut reader: impl Read) -> Result<Self, Error> {
108        let mut bytes = Vec::new();
109        reader.read_to_end(&mut bytes)?;
110        Self::from_bytes(&bytes)
111    }
112
113    /// 圧縮済みデータのバイト列から構築する
114    pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
115        Ok(Geocoder {
116            store: Store::from_compressed(bytes)?,
117        })
118    }
119
120    /// 座標から最寄りの大字・町丁目を検索する
121    ///
122    /// # エラー
123    ///
124    /// 座標が日本のメッシュ範囲(北緯20〜46度、東経122〜154度)の外の場合は
125    /// [`Error::OutOfJapanRange`]を返します。
126    ///
127    /// # 例
128    ///
129    /// ```no_run
130    /// use japan_reverse_geocoder::Geocoder;
131    ///
132    /// let geocoder = Geocoder::new();
133    /// let result = geocoder.reverse_geocode(35.6812, 139.7671).unwrap();
134    /// println!(
135    ///     "{}{}{} ({:.0}m)",
136    ///     result.address.prefecture, result.address.city, result.address.town,
137    ///     result.distance_meters
138    /// );
139    /// ```
140    pub fn reverse_geocode(&self, lat: f64, lon: f64) -> Result<ReverseGeocodeResult<'_>, Error> {
141        let results = self.nearest(lat, lon, 1)?;
142        results
143            .into_iter()
144            .next()
145            .ok_or_else(|| Error::InvalidData("no records loaded".into()))
146    }
147
148    /// 座標に近い順にk件の大字・町丁目を検索する
149    ///
150    /// 収録レコード数より大きい`k`を指定した場合は全件を返します。
151    pub fn nearest(
152        &self,
153        lat: f64,
154        lon: f64,
155        k: usize,
156    ) -> Result<Vec<ReverseGeocodeResult<'_>>, Error> {
157        let query = self.validate(lat, lon)?;
158        if k == 0 {
159            return Ok(Vec::new());
160        }
161        let k = k.min(self.store.records.len());
162
163        let mut candidates: Vec<(f64, u32)> = Vec::new();
164        let (row0, col0) = self.query_cell(query);
165        for ring in 0..=MAX_RING {
166            self.collect_ring(query, row0, col0, ring, &mut candidates);
167
168            if candidates.len() >= k {
169                candidates.sort_unstable_by(|a, b| a.0.total_cmp(&b.0));
170                // 未探索領域にk位より近いレコードが存在し得なければ確定
171                if candidates[k - 1].0 <= min_unexplored_distance(query, row0, col0, ring) {
172                    break;
173                }
174            }
175        }
176
177        candidates.sort_unstable_by(|a, b| a.0.total_cmp(&b.0));
178        candidates.truncate(k);
179        Ok(self.to_results(candidates))
180    }
181
182    /// 半径`radius_meters`以内の大字・町丁目を近い順に列挙する
183    ///
184    /// 半径が負・NaNの場合は空のベクターを返します。
185    pub fn within_radius(
186        &self,
187        lat: f64,
188        lon: f64,
189        radius_meters: f64,
190    ) -> Result<Vec<ReverseGeocodeResult<'_>>, Error> {
191        let query = self.validate(lat, lon)?;
192        if radius_meters.is_nan() || radius_meters < 0.0 {
193            return Ok(Vec::new());
194        }
195
196        let mut candidates: Vec<(f64, u32)> = Vec::new();
197        let (row0, col0) = self.query_cell(query);
198        for ring in 0..=MAX_RING {
199            // 未探索領域が半径の外に出たら打ち切り
200            if ring > 0 && min_unexplored_distance(query, row0, col0, ring - 1) > radius_meters {
201                break;
202            }
203            self.collect_ring(query, row0, col0, ring, &mut candidates);
204        }
205
206        candidates.retain(|&(d, _)| d <= radius_meters);
207        candidates.sort_unstable_by(|a, b| a.0.total_cmp(&b.0));
208        Ok(self.to_results(candidates))
209    }
210
211    /// 収録データのバージョン表記(例: "19.0b")
212    pub fn data_version(&self) -> &str {
213        &self.store.data_version
214    }
215
216    /// 収録レコード数
217    pub fn len(&self) -> usize {
218        self.store.records.len()
219    }
220
221    /// レコードが空かどうか
222    pub fn is_empty(&self) -> bool {
223        self.store.records.is_empty()
224    }
225
226    fn validate(&self, lat: f64, lon: f64) -> Result<Coordinate, Error> {
227        Coordinate::new(lat, lon).map_err(|_| Error::OutOfJapanRange { lat, lon })
228    }
229
230    /// クエリ座標の2次メッシュを(行, 列)のグリッド座標で返す
231    ///
232    /// 行 = 1次メッシュ緯度番号×8 + 2次メッシュ緯度番号、列も同様。
233    /// レコードのバケット割当(build-data)と同じくjismeshcodeの計算を起点に
234    /// することで、境界での不整合を避ける。
235    fn query_cell(&self, query: Coordinate) -> (i32, i32) {
236        let mesh = coord_to_mesh(query, MeshLevel::Second)
237            .expect("validated coordinate is convertible")
238            .code() as u32;
239        mesh_to_cell(mesh)
240    }
241
242    /// Chebyshev距離がちょうど`ring`のセル群からレコードを収集する
243    fn collect_ring(
244        &self,
245        query: Coordinate,
246        row0: i32,
247        col0: i32,
248        ring: i32,
249        out: &mut Vec<(f64, u32)>,
250    ) {
251        if ring == 0 {
252            self.collect_cell(query, row0, col0, out);
253            return;
254        }
255        for dc in -ring..=ring {
256            self.collect_cell(query, row0 - ring, col0 + dc, out);
257            self.collect_cell(query, row0 + ring, col0 + dc, out);
258        }
259        for dr in (-ring + 1)..ring {
260            self.collect_cell(query, row0 + dr, col0 - ring, out);
261            self.collect_cell(query, row0 + dr, col0 + ring, out);
262        }
263    }
264
265    fn collect_cell(&self, query: Coordinate, row: i32, col: i32, out: &mut Vec<(f64, u32)>) {
266        let Some(mesh) = cell_to_mesh(row, col) else {
267            return;
268        };
269        let Ok(pos) = self
270            .store
271            .mesh_index
272            .binary_search_by_key(&mesh, |e| e.mesh)
273        else {
274            return;
275        };
276        let entry = &self.store.mesh_index[pos];
277        for i in entry.start..entry.start + entry.len {
278            let record = &self.store.records[i as usize];
279            let coord = Coordinate::new_unchecked(record.lat(), record.lon());
280            let distance = haversine_distance(query, coord);
281            out.push((distance, i));
282        }
283    }
284
285    fn to_results(&self, candidates: Vec<(f64, u32)>) -> Vec<ReverseGeocodeResult<'_>> {
286        candidates
287            .into_iter()
288            .map(|(distance_meters, i)| {
289                let record = &self.store.records[i as usize];
290                let city = &self.store.cities[record.city_idx as usize];
291                let pref = &self.store.prefs[city.pref_idx as usize];
292                ReverseGeocodeResult {
293                    address: Address {
294                        prefecture: &pref.name,
295                        prefecture_code: pref.code,
296                        city: &city.name,
297                        city_code: city.code,
298                        town: &self.store.town_names[record.town_name_idx as usize],
299                        town_code: record.town_code,
300                        lat: record.lat(),
301                        lon: record.lon(),
302                    },
303                    distance_meters,
304                }
305            })
306            .collect()
307    }
308}
309
310/// 2次メッシュコード → グリッド座標(行, 列)
311fn mesh_to_cell(mesh: u32) -> (i32, i32) {
312    let pq = (mesh / 10_000) as i32;
313    let rs = ((mesh / 100) % 100) as i32;
314    let t = ((mesh / 10) % 10) as i32;
315    let u = (mesh % 10) as i32;
316    (pq * 8 + t, rs * 8 + u)
317}
318
319/// グリッド座標(行, 列)→ 2次メッシュコード
320///
321/// メッシュコードとして表現できない範囲はNoneを返す。
322fn cell_to_mesh(row: i32, col: i32) -> Option<u32> {
323    if !(0..800).contains(&row) || !(0..800).contains(&col) {
324        return None;
325    }
326    let pq = (row / 8) as u32;
327    let t = (row % 8) as u32;
328    let rs = (col / 8) as u32;
329    let u = (col % 8) as u32;
330    Some(pq * 10_000 + rs * 100 + t * 10 + u)
331}
332
333#[cfg(test)]
334mod tests {
335    use super::*;
336
337    #[test]
338    fn test_mesh_cell_roundtrip() {
339        // 東京の2次メッシュ 533946: pq=53, rs=39, t=4, u=6
340        let (row, col) = mesh_to_cell(533946);
341        assert_eq!((row, col), (53 * 8 + 4, 39 * 8 + 6));
342        assert_eq!(cell_to_mesh(row, col), Some(533946));
343    }
344
345    #[test]
346    fn test_cell_to_mesh_out_of_range() {
347        assert_eq!(cell_to_mesh(-1, 100), None);
348        assert_eq!(cell_to_mesh(100, -1), None);
349        assert_eq!(cell_to_mesh(800, 100), None);
350        assert_eq!(cell_to_mesh(100, 800), None);
351    }
352
353    #[test]
354    fn test_cell_neighbors_cross_first_mesh_boundary() {
355        // 1次メッシュ境界をまたぐ隣接セル: 533977(t=7)の北隣は543907(pq+1, t=0)
356        let (row, col) = mesh_to_cell(533977);
357        assert_eq!(cell_to_mesh(row + 1, col), Some(543907));
358        // 経度方向: 533947(u=7)の東隣は534040(rs+1, u=0)
359        let (row, col) = mesh_to_cell(533947);
360        assert_eq!(cell_to_mesh(row, col + 1), Some(534040));
361    }
362}