@geolonia/normalize-japanese-addresses

中文文档
3.1.3发布于 2024/12/24MITTypeScriptESM + CJS近 30 天下载 10.5万

日本の住所を正規化するライブラリ

原始使用文档
文档目录11 节
  1. デモ
  2. インストール
  3. 使い方
  4. normalize(address: string, option: Option)
  5. グローバルオプション
  6. 正規化の内容
  7. 開発者向け情報
  8. NodeJS バージョン対応方針について
  9. 注意
  10. 貢献方法
  11. ライセンス、利用規約

@geolonia/normalize-japanese-addresses

build

オープンソースの住所正規化ライブラリです。

経産省の IMI コンポーネントツールのジオコーディングの仕組みからインスピレーションをうけて開発しました。

デモ

https://geolonia.github.io/normalize-japanese-addresses/

インストール

ライブラリは npm レジストリで @geolonia/normalize-japanese-addresses として配布されています。 npm コマンドなどを使ってインストールして下さい。

$ npm install @geolonia/normalize-japanese-addresses -S

使い方

normalize(address: string, option: Option)

住所を正規化します。

import { normalize } from '@geolonia/normalize-japanese-addresses';
// ESMを利用しない場合は下記
// const { normalize } = require('@geolonia/normalize-japanese-addresses');

normalize('北海道札幌市西区24-2-2-3-3').then(result => {
  console.log(result);
  // {
  //   "pref": "北海道", // 都道府県名
  //   "city": "札幌市西区", // 市区町村名
  //   "town": "二十四軒二条二丁目", // 大字・丁目名
  //   "addr": "3-3", // 街区符号・住居符号または地番
  //   "level": 8, // 正規化レベル
  //   "point": {
  //     "lat": 43.074206115, // 緯度
  //     "lng": 141.315540696, // 軽度
  //     "level": 8 // 位置情報データレベル
  //   },
  //   "other": "" // 正規化できなかった文字列
  // }
})

住所の正規化結果として戻されるオブジェクトには、level プロパティが含まれます。level には、住所文字列のどこまでを判別できたかを以下の数値で格納しています。

  • 0 - 都道府県も判別できなかった。
  • 1 - 都道府県まで判別できた。
  • 2 - 市区町村まで判別できた。
  • 3 - 大字・丁目まで判別できた。
  • 8 - 住居表示住所の街区符号・住居符号または地番住所の地番まで判別できた。

point に位置情報データ (EPSG:4326) が入っています。位置情報の精度を表す level プロパティを参照してください。住所正規化レベルと位置情報データのレベルが異なる場合は主には、住居表示または地番情報(レベル8)は存在しましたが、位置情報データが存在しなかった場合。この場合は、大字・丁目の代表点の位置情報データを返却します。

位置情報データのレベルは下記となります。

  • 1 - 都道府県庁所在地
  • 2 - 市区町村役所(役場)所在地
  • 3 - 大字・丁目の代表点
  • 8 - 住居表示住所の場合はフロンテージ位置多い。地番住所の場合は地番の中央点。

レベルの上限を設定することも可能です。例えば都道府県名のみを正規化したい場合、level オプションで指定することで処理を速くすることができます。

const { normalize } = require('@geolonia/normalize-japanese-addresses')
normalize('北海道札幌市西区24-2-2-3-3', { level: 1 }).then(result => {
  console.log(result);
  // {
  //   "pref": "北海道",
  //   "other": "札幌市西区24-2-2-3-3",
  //   "level": 1,
  //   "point": {
  //     "lat": 43.0639406375,
  //     "lng": 141.347906782,
  //     "level": 1
  //   }
  // }
})

グローバルオプション

以下のパラメーターを変更することでライブラリの動作全体に関わる設定が変更できます。

config.japaneseAddressesApi: string

住所データを配信する Web API のエンドポイントを指定します。デフォルトは https://japanese-addresses-v2.geoloniamaps.com/api/ja です。この API から配信されるデータのディレクトリ構成は Geolonia 住所データ を参考にしてください。

NodeJS環境のみ、このオプションに対して file:// 形式の URL を指定することで、ローカルファイルとして保存したファイルを参照することができます。

正規化の内容

  • XXX郡 などの郡の名前が省略されている住所に対しては、それを補完します。
  • 住所に含まれるアルファベットと数字を半角に統一します。
  • 京都の通り名を削除します。
  • 新字体と旧字体のゆらぎを吸収して、国交省の位置参照情報に記載されている地名にあわせます。
  • ヶケが、ヵカか力、之ノの、ッツっつ などのゆらぎを吸収して、国交省の位置参照情報に記載されている地名にあわせます。
  • 釜と竈、埠頭とふ頭などの漢字のゆらぎを吸収します。
  • 町丁目レベルに記載されている数字は、国交省の位置参照情報にあわせて、すべて漢数字に変換します。
  • 番地や号レベルに記載されている数字はアラビア数字に変換し、番地 などの文字列は - に変換します。
  • 住所の末尾に建物名がある場合は、なるべくなにもしないでそのまま返す仕様になっていますが、できればあらかじめ分離していただいたほうがいいかもしれません。

参考:

開発者向け情報

まず、以下のコマンドで環境を用意してください。

$ git clone [email protected]:geolonia/normalize-japanese-addresses.git
$ cd normalize-japanese-addresses
$ npm install

次に、以下を実行してコンパイルをおこないます。

$ npm run build

dist フォルダ以下に main-node.js など必要なファイルが生成されるので、

// sample.js
import { normalize } from './dist/main-node-esm.mjs';
// ESMを利用しない場合は下記
// const { normalize } = require('./dist/main-node-cjs.cjs');

normalize('北海道札幌市西区24-2-2-3-3', { level: 3 }).then(result => {
  console.log(result);
  // {
  //   "pref": "北海道",
  //   "city": "札幌市西区",
  //   "town": "二十四軒二条二丁目",
  //   "other": "3-3",
  //   "level": 3,
  //   "point": {
  //     "lat": 43.074273,
  //     "lng": 141.315099,
  //     "level": 3
  //   }
  // }
})

という内容で sample.js を用意したら、

$ node sample.js

でサンプルファイルを実行することができます。

NodeJS バージョン対応方針について

normalize-japanese-addresses は現在、 NodeJS 18.x, 20.x, 22.x を対象としてテストを実施し、動作を確認しております。ビルド時は「開発環境」の NodeJS バージョンを利用ください。

NodeJS 以外のブラウザの環境は、最新ブラウザを前提とした対応となります。fetchが利用可能な環境であれば動く可能性が高い。テストは最新の Chrome を使って実施しております。

開発環境は、 .tool-versions にかかれているバージョンを利用してください。

準拠としては Node.js Releases を参照してください。基本的に動作環境は Maintenance, Active LTS をターゲットとし、開発環境は最新の Active LTS を利用しますが、更新のタイミング等でずれることがあります。

注意

  • この正規化エンジンは、住所の「名寄せ」を目的としており、たとえば京都の「通り名」は削除します。
    • 郵便や宅急便などに使用される住所としては、問題ないと考えています。
  • 正規化に利用するデータは、 japanese-addresses-v2 で作成されます。元データに関してはそのレポジトリを御覧ください。
  • 住居表示が未整備の地域については全体的に苦手です。

貢献方法

プルリクエスト や Issue はいつでも歓迎します。

ライセンス、利用規約

  • ソースコードのライセンスは MIT ライセンスです。
  • ご利用に際しましては、できればソーシャルでのシェア、Geolonia へのリンクの設置などをしていただけると、開発者たちのモチベーションが上がると思います。

住所の正規化を工夫すれば精度があがりそうなので、そのあたりのアイディアを募集しています。

版本与发布记录

@geolonia/normalize-japanese-addresses 共发布 69 个版本,首次发布于 2020/09/29;过去 12 个月发布了 0 个版本。

版本发布日期距今
3.1.3latest2024/12/241.9 年前
3.1.22024/12/241.9 年前
3.1.12024/10/252 年前
3.1.02024/10/232 年前
3.0.12024/10/182 年前
3.0.02024/10/102 年前

关于 @geolonia/normalize-japanese-addresses 的常见问题

@geolonia/normalize-japanese-addresses 是什么?

日本の住所を正規化するライブラリ

如何安装 @geolonia/normalize-japanese-addresses?

在项目目录运行 npm install @geolonia/normalize-japanese-addresses,或使用 pnpm add / yarn add / bun add。

@geolonia/normalize-japanese-addresses 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geolonia/normalize-japanese-addresses 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@geolonia/normalize-japanese-addresses 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@geolonia/normalize-japanese-addresses 可以商用吗?

@geolonia/normalize-japanese-addresses 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geolonia/normalize-japanese-addresses 的下载量有多少?

根据 npm 官方下载统计,@geolonia/normalize-japanese-addresses 在 2026/10/16 – 2026/11/14 这 30 天内被下载 105,334 次,日均约 3,511 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geolonia/normalize-japanese-addresses 还在维护吗?

最新版本 3.1.3 发布于 2024/12/24(1.9 年前);至今共发布 69 个版本,其中过去 12 个月发布了 0 个;首次发布于 2020/09/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。