コマンドライン・インタフェース
ここでは jageocoder モジュールをコマンドラインから呼びだして 利用する方法を説明します。
同じ内容はオンラインヘルプでも確認できます。
(.venv) $ jageocoder -h
ジオコーディング
住所文字列をキーとして住所辞書データベースを検索し、 先頭から最長一致すると解釈できるレコードを取得し、 そのレコードの経緯度を含む情報を返します。
最長一致する長さが同じ候補が複数存在する場合、全ての候補を返します。
- コマンド
search- パラメータ
住所文字列
- オプション
-dデバッグ情報を表示します。--area=<area>検索する都道府県や市区町村を指定します。 省略した場合は全国を対象とします。複数の都道府県・市区町村を 指定する場合は,で区切ります。--db-dir=<dir>住所辞書データベースを配置したディレクトリを 指定します。
実行例
# 「落合１－１５－２」を検索します。
# 「栃木県下都賀郡壬生町落合一丁目15番2号」と
# 「広島県広島市安佐北区落合一丁目15番2号」が返ります。
(.venv) $ jageocoder search '落合１－１５－２'
{"matched": "落合１－１５－２", "candidates": [{"id": 6894076, "name": "2号", "x": 139.820208258, "y": 36.450565089, "level": 8, "priority": 4, "note": null, "fullname": ["栃木県", "下都賀郡", "壬生町", "落合", "一丁目", "15番", "2号"]}, {"id": 34195069, "name": "2号", "x": 132.510432116, "y": 34.473211622, "level": 8, "priority": 4, "note": null, "fullname": ["広島県", "広島市", "安佐北区", "落合", "一丁目", "15番", "2号"]}]}
# 「落合１－１５－２」を東京都から検索します。
# 「東京都多摩市落合一丁目15番地」が返ります。
(.venv) $ jageocoder search --area=東京都 '落合１－１５－２'
{"matched": "落合１－１５－", "candidates": [{"id": 12724450, "name": "15番地", "x": 139.428969, "y": 35.625779, "level": 7, "priority": 3, "note": null, "fullname": ["東京都", "多摩市", "落合", "一丁目", "15番地"]}]}
逆ジオコーディング
経度・緯度を指定し、その地点を囲む３点のレコードを検索し、 そのレコードリストの情報を指定地点に近い順に返します。
岬の突端や離島など、３点のレコードが存在しない場合は リストに含まれるレコード数が３より小さい場合もあります。
住所辞書には「住所に対応する代表点」の座標しか含まれておらず、 その住所が表す範囲（形状）の情報は利用できないため、 「指定した地点に近い代表点」を検索していることに注意してください。
- コマンド
reverse- パラメータ
経度 緯度 （WGS1984 の十進度表記）
- オプション
-dデバッグ情報を表示します。--level=<level>指定した住所レベルまで検索します。 デフォルトは 6 (字レベル) です。 より大きなレベルを指定すると、検索に時間がかかります。--db-dir=<dir>住所辞書データベースを配置したディレクトリを 指定します。
実行例
# 経度 139.6917, 緯度 35.6896 の地点付近の住所を検索します。
# 「東京都新宿区西新宿二丁目」、「東京都新宿区西新宿六丁目」、
# 「東京都新宿区西新宿四丁目」が返ります。
(.venv) $ jageocoder reverse 139.6917 35.6896
[{"candidate": {"id": 12977775, "name": "二丁目", "x": 139.691774, "y": 35.68945, "level": 6, "priority": 2, "note": "aza_id:0023002/postcode:1600023", "fullname": ["東京都", "新宿区", "西新宿", "二丁目"]}, "dist": 17.940303970792183}, {"candidate": {"id": 12978643, "name": "六丁目", "x": 139.690969, "y": 35.693426, "level": 6, "priority": 2, "note": "aza_id:0023006/postcode:1600023", "fullname": ["東京都", "新宿区", "西新宿", "六丁目"]}, "dist": 429.6327545403412}, {"candidate": {"id": 12978943, "name": "四丁目", "x": 139.68762, "y": 35.68754, "level": 6, "priority": 2, "note": "aza_id:0023004/postcode:1600023", "fullname": ["東京都", "新宿区", "西新宿", "四丁目"]}, "dist": 434.31591285255234}]
# 経度 139.6917, 緯度 35.6896 の地点付近の住所を
# 街区（○○番）レベルで検索します。
# 「東京都新宿区西新宿二丁目8番」、「東京都新宿区西新宿二丁目」、
# 「東京都新宿区西新宿四丁目15番」が返ります。
(.venv) $ jageocoder reverse 139.6917 35.6896 --level=7
[{"candidate": {"id": 12977785, "name": "8番", "x": 139.691778, "y": 35.689627, "level": 7, "priority": 3, "note": null, "fullname": ["東京都", "新宿区", "西新宿", "二丁目", "8番"]}, "dist": 7.669497303543382}, {"candidate": {"id": 12977775, "name": "二丁目", "x": 139.691774, "y": 35.68945, "level": 6, "priority": 2, "note": "aza_id:0023002/postcode:1600023", "fullname": ["東京都", "新宿区", "西新宿", "二丁目"]}, "dist": 17.940303970792183}, {"candidate": {"id": 12979033, "name": "15番", "x": 139.688172, "y": 35.689264, "level": 7, "priority": 3, "note": null, "fullname": ["東京都", "新宿区", "西新宿", "四丁目", "15番"]}, "dist": 321.50874020809823}]
住所辞書ディレクトリの取得
実行中の Python 環境で、住所辞書データベースがインストールされている ディレクトリを取得します。
辞書データベースは {sys.prefix}/jageocoder/db/ の下に
作成されますが、ユーザが書き込み権限を持っていない場合には
{site.USER_DATA}/jageocoder/db/ に作成されます。
上記以外の任意の場所を指定したい場合、環境変数 JAGEOCODER_DB_DIR
でディレクトリを指定することができます。
- コマンド
get-db-dir- パラメータ
（なし）
- オプション
-dデバッグ情報を表示します。
実行例
(.venv) $ jageocoder get-db-dir
/home/sagara/.local/share/virtualenvs/jageocoder-kWBL7Ve6/jageocoder/db/
住所辞書ファイルのダウンロード
インストール済みの jageocoder と互換性のある 住所辞書ファイルを、ウェブからダウンロードします。
特に理由が無い限り URL は省略してください。
逆にダウンロードするべきファイルの URL が分かっている場合は
curl や wget コマンドでダウンロードしても構いません。
- コマンド
download-dictionary- パラメータ
<url>ダウンロードする URL を指定できます（省略可）。- オプション
-dデバッグ情報を表示します。--gaikuより軽量な街区レベルまでの住所辞書ファイルを ダウンロードします。
実行例
# 街区レベルまでの住所辞書ファイルをダウンロードします
(.venv) $ jageocoder download-dictionary --gaiku
INFO:jageocoder.module:157:Downloading zipped dictionary file from https://www.info-proto.com/static/gaiku-20220519.zip to ...
住所辞書ファイルのインストール
住所辞書ファイルを展開し、住所辞書データベースを作ります。
- コマンド
install-dictionary- パラメータ
<url_or_path>インストールする住所辞書ファイルの URL または パスを指定します（省略可）。省略した場合、互換性のあるファイルを ダウンロードしてからインストールします。- オプション
-dデバッグ情報を表示します。--gaikuより軽量な街区レベルまでの住所辞書ファイルを ダウンロード・インストールします。<url_or_path>を 指定した場合にはこのオプションは意味がありません。--db-dir住所辞書データベースを作るディレクトリを 指定します。
実行例
# ダウンロード済みの住所辞書ファイルをインストールします
(.venv) $ jageocoder install-dictionary gaiku-20220519.zip
住所辞書ファイルのアンインストール
住所辞書データベースをアンインストールします。
- コマンド
uninstall-dictionary- パラメータ
（なし）
- オプション
-dデバッグ情報を表示します。--db-dir=<dir>住所辞書データベースのディレクトリを指定します。
実行例
# 住所辞書データベースをアンインストールします
(.venv) $ jageocoder uninstall-dictionary
INFO:jageocoder.module:248:Removing directory ...
INFO:jageocoder.module:251:Dictionary has been uninstalled.
住所辞書ファイルのマイグレーション
jageocoder のバージョンを上げた際に、インストール済みの
住所辞書データベースが非互換になる場合、利用できるように変換します。
この処理は全てのレコードのチェックを行なうため、
インストールに比べても非常に長い時間がかかります。
大きく仕様が変更された場合はマイグレーションできない場合もあります。 特に理由が無い限り、バージョンアップした場合は辞書も新しいものを インストールしなおすことをお勧めします。
- コマンド
migrate-dictionary- パラメータ
（なし）
- オプション
-dデバッグ情報を表示します。--db-dir=<dir>住所辞書データベースのディレクトリを指定します。
実行例
# 住所辞書データベースをマイグレートします
(.venv) $ jageocoder migrate-dictionary