入力となる JSON-LD に含まれる 住所>表記 をもつ 場所型 または 表記をもつ住所型 に対して各種のプロパティを補完して返します。
入力が 住所>表記 をもつ 場所型 の場合には地理座標と住所型の各プロパティが補完されます。
input1.json
{
"@type": "場所型",
"住所" : {
"@type": "住所型",
"表記" : "霞が関2-1-10"
}
}output1.json
{
"@type": "場所型",
"住所": {
"@type": "住所型",
"表記": "霞が関2-1-10",
"都道府県": "東京都",
"都道府県コード": "https://data.e-stat.go.jp/lod/sac/C13000",
"市区町村": "千代田区",
"市区町村コード": "https://data.e-stat.go.jp/lod/sac/C13101",
"町名": "霞が関",
"丁目": "2",
"番地": "1",
"号": "10"
},
"地理座標": {
"@type": "座標型",
"緯度": "35.675551",
"経度": "139.750413"
}
}
入力が 表記をもつ住所型 の場合には住所型のプロパティだけが補完されます。
input2.json
{
"@type": "住所型",
"表記" : "霞が関2-1-10"
}output2.json
{
"@type": "住所型",
"表記": "霞が関2-1-10",
"都道府県": "東京都",
"都道府県コード": "https://data.e-stat.go.jp/lod/sac/C13000",
"市区町村": "千代田区",
"市区町村コード": "https://data.e-stat.go.jp/lod/sac/C13101",
"町名": "霞が関",
"丁目": "2",
"番地": "1",
"号": "10"
}
- 総務省統計局 e-Stat 統計LOD:地域に関するデータ:統計に用いる標準地域コード および 国土交通省 国土政策局 国土情報課:位置参照情報ダウンロードサービス:大字・町丁目レベル位置参照情報 のデータをもとに各種情報が補完されます
- 付与される地理座標は大字・町丁目レベル位置参照情報のデータによるもので、大字・町丁目の代表点に相当します (番地・号レベルの緯度経度ではありません)
- それぞれのデータをダウンロードして加工したものが本パッケージにバンドルされています
- 町名・丁目レベルまでの地名についてダウンロードデータをもとに実在性が検証されます
- 町名・丁目が実在した場合、それ以下の番地・号は表記をもとに正規化が行われます
- 所与の住所文字列に合致するような地名がない場合にはエラーが返されます
output_with_error.json
{
"@context": "https://imi.go.jp/ns/core/context.jsonld",
"@type": "場所型",
"住所": {
"@type": "住所型",
"表記": "霞が関99",
"都道府県": "東京都",
"都道府県コード": "https://data.e-stat.go.jp/lod/sac/C13000",
"市区町村": "千代田区",
"市区町村コード": "https://data.e-stat.go.jp/lod/sac/C13101",
"町名": "霞が関"
},
"メタデータ": {
"@type": "文書型",
"説明": "該当する丁目が見つかりません"
}
}
以下のエラーが検出されます
- 該当する地名が見つからない場合 (海外住所、都道府県名の間違いなど)
- 該当する市区町村名が見つからない場合
- 該当する市区町村が複数存在する場合（「府中市」など）
- 該当する町名が見つからない場合
- 指定された丁目が存在しない場合（「霞が関五丁目」など）
imi-enrichment-address は node.js のモジュールですが、
動作のためには後述の環境構築の手順によってバンドルデータベースを構築する必要があります。
簡便な動作確認のために、バンドルデータベースを同梱したパッケージアーカイブが gBizInfo: IMI コンポーネントツール のページにて公開されています。
以下の手順は同ページで公開されているパッケージアーカイブ imi-enrichment-address-2.0.0.tgz を用いて実行します。
以下の手順でインストールします。
$ npm install https://info.gbiz.go.jp/tools/imi_tools/resource/imi-enrichment-address/imi-enrichment-address-2.0.0.tgz
imi-enrichment-address-2.0.0.tgz にはコマンドラインインターフェイスが同梱されており、
通常はインストールすると imi-enrichment-address コマンドが使用できるようになります。
コマンドラインインターフェイスのファイルの実体は bin/cli.js です。
$ npm install https://info.gbiz.go.jp/tools/imi_tools/resource/imi-enrichment-address/imi-enrichment-address-2.0.0.tgz
# ヘルプの表示
$ imi-enrichment-address -h
# JSON ファイルの変換
$ imi-enrichment-address input.json > output.json
# 標準入力からの変換
$ cat input.json | imi-enrichment-address > output.json
# 文字列からの変換
$ imi-enrichment-address -s 霞が関2 > output.json
または npx を使って以下のようにインストールせずに実行することも可能です。
$ npx https://info.gbiz.go.jp/tools/imi_tools/resource/imi-enrichment-address/imi-enrichment-address-2.0.0.tgz -s 霞が関2
imi-enrichment-address-2.0.0.tgz には Web API を提供するサーバプログラムが同梱されています。
bin/server.js がサーバの実体です。
以下のように bin/server.js を実行することで起動できます。
$ npm install https://info.gbiz.go.jp/tools/imi_tools/resource/imi-enrichment-address/imi-enrichment-address-2.0.0.tgz
$ node node_modules/imi-enrichment-address/bin/server.js
Usage: node server.js [port number]
$ node node_modules/imi-enrichment-address/bin/server.js 8080
imi-enrichment-address-server is running on port 8080
なお、実行時にはポート番号の指定が必要です。指定しなかった場合にはエラーが表示されて終了します。
サーバを停止するには Ctrl-C を入力してください。
WebAPI は POST された JSON または テキストを入力として JSON を返します。
$ curl -X POST -H 'Content-Type: application/json' -d '{"@type":"住所型","表記":"霞が関2"}' localhost:8080
{
"@type": "住所型",
"表記": "霞が関2",
"都道府県": "東京都",
"都道府県コード": "https://data.e-stat.go.jp/lod/sac/C13000",
"市区町村": "千代田区",
"市区町村コード": "https://data.e-stat.go.jp/lod/sac/C13101",
"町名": "霞が関",
"丁目": "2"
}
$ curl -X POST -H 'Content-Type: text/plain' -d '霞が関2' localhost:8080
{
"@type": "住所型",
"表記": "霞が関2",
"都道府県": "東京都",
"都道府県コード": "https://data.e-stat.go.jp/lod/sac/C13000",
"市区町村": "千代田区",
"市区町村コード": "https://data.e-stat.go.jp/lod/sac/C13101",
"町名": "霞が関",
"丁目": "2"
}
- WebAPI の URL に GET メソッドでアクセスした場合には HTML ページが表示され、WebAPI の動作を確認することができます
- POST,GET 以外のメソッドでアクセスした場合には
405 Method Not Allowedエラーが返されます Content-Type: application/jsonヘッダが設定されている場合は、POST Body を JSON として扱い、JSON に対しての変換結果を返しますContent-Type: application/jsonヘッダが設定されているが POST Body が JSON としてパースできない場合は400 Bad Requestエラーが返されますContent-Type: application/jsonヘッダが設定されていない場合は、POST Body を住所文字列として扱い、住所文字列をもとに情報の補完された場所型の JSON を返します
モジュール imi-enrichment-address は以下のような API の関数を提供します。
module.exports = function(input) {..}
- 入力 (input) : 変換対象となる JSON または住所文字列
- 出力 : 変換結果の JSON-LD オブジェクトを返却する Promise ※ 変換は非同期で行うために Promise が返されます
const convert = require('imi-enrichment-address');
convert("霞が関2").then(json=>{
console.log(json);
});
本パッケージでは 総務省統計局 e-Stat 統計LOD:地域に関するデータ:統計に用いる標準地域コード のデータおよび 国土交通省 国土政策局 国土情報課:位置参照情報ダウンロードサービス:大字・町丁目レベル位置参照情報 のデータをダウンロードして使用します。
これらのダウンロードは環境構築手順の bash tools/download.sh の中で自動的に実行されます。
以下の手順で環境を構築します。
$ git clone https://github.com/IMI-Tool-Project/imi-enrichment-address.git
$ cd imi-enrichment-address
$ npm install
$ bash tools/download.sh 12.0b
$ npm run tree
$ npm run format
以下の手順でテストを実行します
$ cd imi-enrichment-address
$ npm test
以下の手順で、バンドルデータを含むパッケージアーカイブを作成できます。
$ cd imi-enrichment-address
$ npm pack
imi-enrichment-address-2.0.0.tgz
$
上記の環境構築手順では位置参照情報 (平成30年度版) がダウンロードされ、環境が構築されます。 また、テストも位置参照情報 (平成30年度版) に含まれるデータを前提としたテストになっています。
一方で、位置参照情報は以下のような URL 構造を持っており、${バージョン} に適切な文字列を設定することで、
異なる年度のデータをダウンロードして環境を構築することが可能です。
https://nlftp.mlit.go.jp/isj/dls/data/${バージョン}/${地方公共団体コード}-${バージョン}.zip
バージョン文字列は、たとえば平成30年度版であれば 12.0b , 令和元年度版であれば 13.0b といったものです。
ダウンロード処理の実体は tools/download.sh に記述されており、
このシェルスクリプトは以下のように、位置参照情報のバージョン文字列を引数にとります。
$ bash tools/download.sh
usage: bash tools/download.sh [位置参照情報のバージョン (例:12.0b)]
$
仮に令和元年度版データをもとに環境を構築する場合は、以下のように 12.0b を 13.0b に書き換えることで対応できます。
$ git clone https://github.com/IMI-Tool-Project/imi-enrichment-address.git
$ cd imi-enrichment-address
$ npm install
$ bash tools/download.sh 13.0b
$ npm run tree
$ npm run format
なお、位置参照情報の URL 仕様変更・ファイル仕様変更・CSV レイアウトの変更・特定年度のデータエラーなどにより、 必ずしも動作を保証するものではありません。
また、テストコードは位置参照情報 (平成30年度版) を前提としたもので、 当該年度以外のデータで構築された環境でのテストについてはサポートされていないことに注意してください。
imi-enrichment-address はブラウザ上での直接動作をサポートしていません。
WebAPI を使用してください。