japan-reverse-geocoder 0.1.0

国土交通省の位置参照情報(大字・町丁目レベル)を同梱した日本の逆ジオコーディングライブラリ / Offline reverse geocoding for Japan using MLIT location reference data
Documentation
use crate::error::Error;
use crate::store::Store;
use jismeshcode::{coord_to_mesh, haversine_distance, Coordinate, MeshLevel};
use std::io::Read;
use std::path::Path;

/// 大字・町丁目の住所情報
///
/// 文字列フィールドは[`Geocoder`]内部の文字列テーブルへの参照です。
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Address<'a> {
    /// 都道府県名(例: "東京都")
    pub prefecture: &'a str,
    /// 都道府県コード(JIS X 0401、1〜47)
    pub prefecture_code: u8,
    /// 市区町村名(例: "千代田区")
    pub city: &'a str,
    /// 市区町村コード(JIS X 0402、5桁)
    pub city_code: u32,
    /// 大字町丁目名(例: "丸の内一丁目")
    pub town: &'a str,
    /// 大字町丁目コード(12桁)
    pub town_code: u64,
    /// 代表点の緯度(10進度)
    pub lat: f64,
    /// 代表点の経度(10進度)
    pub lon: f64,
}

/// 逆ジオコーディングの結果
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ReverseGeocodeResult<'a> {
    /// 住所情報
    pub address: Address<'a>,
    /// クエリ座標から代表点までのHaversine距離(メートル)
    pub distance_meters: f64,
}

/// 逆ジオコーディングエンジン
///
/// 国土交通省「位置参照情報」(大字・町丁目レベル)の代表点データを保持し、
/// 座標から最寄りの大字・町丁目を検索します。
///
/// # 注意
///
/// 位置参照情報は各町丁目の**代表点**(ポリゴンではない)のデータです。
/// 検索結果は「代表点が最も近い町丁目」であり、厳密に「その座標を含む町丁目」
/// とは限りません。町丁目の境界付近では隣の町丁目が返ることがあります。
pub struct Geocoder {
    store: Store,
}

/// リング探索の上限(日本のメッシュ範囲全体をカバーする値より大きい)
const MAX_RING: i32 = 400;

/// 緯度1度あたりの距離の下限(メートル)。打ち切り判定の過小評価用
const LAT_DEG_METERS_MIN: f64 = 110_000.0;

/// 経度1度あたりの距離の下限(メートル)。111,320 × cos(46°) を切り下げた値
const LON_DEG_METERS_MIN: f64 = 77_000.0;

/// 2次メッシュセルの緯度方向サイズ(度): 5分
const CELL_LAT_DEG: f64 = 1.0 / 12.0;

/// 2次メッシュセルの経度方向サイズ(度): 7.5分
const CELL_LON_DEG: f64 = 1.0 / 8.0;

/// `ring`まで探索済みの矩形領域の外にあるレコードとの距離の下限(メートル)
///
/// 探索済み矩形は行 `[row0-ring, row0+ring]`、列 `[col0-ring, col0+ring]`。
/// 未探索の点はクエリと緯度差または経度差が矩形境界までのギャップ以上あるため、
/// その座標差に保守的な距離換算係数(日本の範囲での下限)を掛けた値が下限になる。
fn min_unexplored_distance(query: Coordinate, row0: i32, col0: i32, ring: i32) -> f64 {
    let south_gap = query.lat() - (row0 - ring) as f64 * CELL_LAT_DEG;
    let north_gap = ((row0 + ring + 1) as f64) * CELL_LAT_DEG - query.lat();
    let west_gap = query.lon() - (100.0 + (col0 - ring) as f64 * CELL_LON_DEG);
    let east_gap = (100.0 + (col0 + ring + 1) as f64 * CELL_LON_DEG) - query.lon();

    let lat_bound = south_gap.min(north_gap).max(0.0) * LAT_DEG_METERS_MIN;
    let lon_bound = west_gap.min(east_gap).max(0.0) * LON_DEG_METERS_MIN;
    lat_bound.min(lon_bound)
}

impl Geocoder {
    /// 同梱データから構築する
    ///
    /// 全国の大字・町丁目データ(約19万件)を展開するため、
    /// 数十ミリ秒程度かかります。アプリケーションで使い回してください。
    #[cfg(feature = "embedded-data")]
    #[allow(clippy::new_without_default)]
    pub fn new() -> Self {
        static DATA: &[u8] = include_bytes!("../data/isj.bin");
        let store = Store::from_compressed(DATA).expect("embedded data must be valid");
        Geocoder { store }
    }

    /// データファイルから構築する
    ///
    /// `embedded-data`フィーチャーを無効にした場合、データファイルは
    /// GitHub Releasesから取得するか、`tools/build-data`で生成してください。
    pub fn from_path(path: impl AsRef<Path>) -> Result<Self, Error> {
        let bytes = std::fs::read(path)?;
        Self::from_bytes(&bytes)
    }

    /// リーダーから構築する
    pub fn from_reader(mut reader: impl Read) -> Result<Self, Error> {
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes)?;
        Self::from_bytes(&bytes)
    }

    /// 圧縮済みデータのバイト列から構築する
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
        Ok(Geocoder {
            store: Store::from_compressed(bytes)?,
        })
    }

    /// 座標から最寄りの大字・町丁目を検索する
    ///
    /// # エラー
    ///
    /// 座標が日本のメッシュ範囲(北緯20〜46度、東経122〜154度)の外の場合は
    /// [`Error::OutOfJapanRange`]を返します。
    ///
    /// # 例
    ///
    /// ```no_run
    /// use japan_reverse_geocoder::Geocoder;
    ///
    /// let geocoder = Geocoder::new();
    /// let result = geocoder.reverse_geocode(35.6812, 139.7671).unwrap();
    /// println!(
    ///     "{}{}{} ({:.0}m)",
    ///     result.address.prefecture, result.address.city, result.address.town,
    ///     result.distance_meters
    /// );
    /// ```
    pub fn reverse_geocode(&self, lat: f64, lon: f64) -> Result<ReverseGeocodeResult<'_>, Error> {
        let results = self.nearest(lat, lon, 1)?;
        results
            .into_iter()
            .next()
            .ok_or_else(|| Error::InvalidData("no records loaded".into()))
    }

    /// 座標に近い順にk件の大字・町丁目を検索する
    ///
    /// 収録レコード数より大きい`k`を指定した場合は全件を返します。
    pub fn nearest(
        &self,
        lat: f64,
        lon: f64,
        k: usize,
    ) -> Result<Vec<ReverseGeocodeResult<'_>>, Error> {
        let query = self.validate(lat, lon)?;
        if k == 0 {
            return Ok(Vec::new());
        }
        let k = k.min(self.store.records.len());

        let mut candidates: Vec<(f64, u32)> = Vec::new();
        let (row0, col0) = self.query_cell(query);
        for ring in 0..=MAX_RING {
            self.collect_ring(query, row0, col0, ring, &mut candidates);

            if candidates.len() >= k {
                candidates.sort_unstable_by(|a, b| a.0.total_cmp(&b.0));
                // 未探索領域にk位より近いレコードが存在し得なければ確定
                if candidates[k - 1].0 <= min_unexplored_distance(query, row0, col0, ring) {
                    break;
                }
            }
        }

        candidates.sort_unstable_by(|a, b| a.0.total_cmp(&b.0));
        candidates.truncate(k);
        Ok(self.to_results(candidates))
    }

    /// 半径`radius_meters`以内の大字・町丁目を近い順に列挙する
    ///
    /// 半径が負・NaNの場合は空のベクターを返します。
    pub fn within_radius(
        &self,
        lat: f64,
        lon: f64,
        radius_meters: f64,
    ) -> Result<Vec<ReverseGeocodeResult<'_>>, Error> {
        let query = self.validate(lat, lon)?;
        if radius_meters.is_nan() || radius_meters < 0.0 {
            return Ok(Vec::new());
        }

        let mut candidates: Vec<(f64, u32)> = Vec::new();
        let (row0, col0) = self.query_cell(query);
        for ring in 0..=MAX_RING {
            // 未探索領域が半径の外に出たら打ち切り
            if ring > 0 && min_unexplored_distance(query, row0, col0, ring - 1) > radius_meters {
                break;
            }
            self.collect_ring(query, row0, col0, ring, &mut candidates);
        }

        candidates.retain(|&(d, _)| d <= radius_meters);
        candidates.sort_unstable_by(|a, b| a.0.total_cmp(&b.0));
        Ok(self.to_results(candidates))
    }

    /// 収録データのバージョン表記(例: "19.0b")
    pub fn data_version(&self) -> &str {
        &self.store.data_version
    }

    /// 収録レコード数
    pub fn len(&self) -> usize {
        self.store.records.len()
    }

    /// レコードが空かどうか
    pub fn is_empty(&self) -> bool {
        self.store.records.is_empty()
    }

    fn validate(&self, lat: f64, lon: f64) -> Result<Coordinate, Error> {
        Coordinate::new(lat, lon).map_err(|_| Error::OutOfJapanRange { lat, lon })
    }

    /// クエリ座標の2次メッシュを(行, 列)のグリッド座標で返す
    ///
    /// 行 = 1次メッシュ緯度番号×8 + 2次メッシュ緯度番号、列も同様。
    /// レコードのバケット割当(build-data)と同じくjismeshcodeの計算を起点に
    /// することで、境界での不整合を避ける。
    fn query_cell(&self, query: Coordinate) -> (i32, i32) {
        let mesh = coord_to_mesh(query, MeshLevel::Second)
            .expect("validated coordinate is convertible")
            .code() as u32;
        mesh_to_cell(mesh)
    }

    /// Chebyshev距離がちょうど`ring`のセル群からレコードを収集する
    fn collect_ring(
        &self,
        query: Coordinate,
        row0: i32,
        col0: i32,
        ring: i32,
        out: &mut Vec<(f64, u32)>,
    ) {
        if ring == 0 {
            self.collect_cell(query, row0, col0, out);
            return;
        }
        for dc in -ring..=ring {
            self.collect_cell(query, row0 - ring, col0 + dc, out);
            self.collect_cell(query, row0 + ring, col0 + dc, out);
        }
        for dr in (-ring + 1)..ring {
            self.collect_cell(query, row0 + dr, col0 - ring, out);
            self.collect_cell(query, row0 + dr, col0 + ring, out);
        }
    }

    fn collect_cell(&self, query: Coordinate, row: i32, col: i32, out: &mut Vec<(f64, u32)>) {
        let Some(mesh) = cell_to_mesh(row, col) else {
            return;
        };
        let Ok(pos) = self
            .store
            .mesh_index
            .binary_search_by_key(&mesh, |e| e.mesh)
        else {
            return;
        };
        let entry = &self.store.mesh_index[pos];
        for i in entry.start..entry.start + entry.len {
            let record = &self.store.records[i as usize];
            let coord = Coordinate::new_unchecked(record.lat(), record.lon());
            let distance = haversine_distance(query, coord);
            out.push((distance, i));
        }
    }

    fn to_results(&self, candidates: Vec<(f64, u32)>) -> Vec<ReverseGeocodeResult<'_>> {
        candidates
            .into_iter()
            .map(|(distance_meters, i)| {
                let record = &self.store.records[i as usize];
                let city = &self.store.cities[record.city_idx as usize];
                let pref = &self.store.prefs[city.pref_idx as usize];
                ReverseGeocodeResult {
                    address: Address {
                        prefecture: &pref.name,
                        prefecture_code: pref.code,
                        city: &city.name,
                        city_code: city.code,
                        town: &self.store.town_names[record.town_name_idx as usize],
                        town_code: record.town_code,
                        lat: record.lat(),
                        lon: record.lon(),
                    },
                    distance_meters,
                }
            })
            .collect()
    }
}

/// 2次メッシュコード → グリッド座標(行, 列)
fn mesh_to_cell(mesh: u32) -> (i32, i32) {
    let pq = (mesh / 10_000) as i32;
    let rs = ((mesh / 100) % 100) as i32;
    let t = ((mesh / 10) % 10) as i32;
    let u = (mesh % 10) as i32;
    (pq * 8 + t, rs * 8 + u)
}

/// グリッド座標(行, 列)→ 2次メッシュコード
///
/// メッシュコードとして表現できない範囲はNoneを返す。
fn cell_to_mesh(row: i32, col: i32) -> Option<u32> {
    if !(0..800).contains(&row) || !(0..800).contains(&col) {
        return None;
    }
    let pq = (row / 8) as u32;
    let t = (row % 8) as u32;
    let rs = (col / 8) as u32;
    let u = (col % 8) as u32;
    Some(pq * 10_000 + rs * 100 + t * 10 + u)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_mesh_cell_roundtrip() {
        // 東京の2次メッシュ 533946: pq=53, rs=39, t=4, u=6
        let (row, col) = mesh_to_cell(533946);
        assert_eq!((row, col), (53 * 8 + 4, 39 * 8 + 6));
        assert_eq!(cell_to_mesh(row, col), Some(533946));
    }

    #[test]
    fn test_cell_to_mesh_out_of_range() {
        assert_eq!(cell_to_mesh(-1, 100), None);
        assert_eq!(cell_to_mesh(100, -1), None);
        assert_eq!(cell_to_mesh(800, 100), None);
        assert_eq!(cell_to_mesh(100, 800), None);
    }

    #[test]
    fn test_cell_neighbors_cross_first_mesh_boundary() {
        // 1次メッシュ境界をまたぐ隣接セル: 533977(t=7)の北隣は543907(pq+1, t=0)
        let (row, col) = mesh_to_cell(533977);
        assert_eq!(cell_to_mesh(row + 1, col), Some(543907));
        // 経度方向: 533947(u=7)の東隣は534040(rs+1, u=0)
        let (row, col) = mesh_to_cell(533947);
        assert_eq!(cell_to_mesh(row, col + 1), Some(534040));
    }
}