# @geolonia/normalize-japanese-addresses 中文文档

规范地址：https://npmcn.com/package/%40geolonia/normalize-japanese-addresses/

版本：3\.1\.3
npm 元数据更新时间：2026-02-11T05:40:48.094Z
中文译文更新时间：2026-11-16T04:28:48.238Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40geolonia/normalize-japanese-addresses
原文对照：https://npmcn.com/package/%40geolonia/normalize-japanese-addresses/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，38 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：5 个
- 首次发布：2020-09-29T09:33:52.025Z
- 最新版本发布：2024-12-24T02:45:24.540Z
- 近 30 天下载量：105334（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 0 个）

## 中文简介

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

## 安装

```sh
npm install @geolonia/normalize-japanese-addresses
```

也可以使用：`pnpm add @geolonia/normalize-japanese-addresses`、`yarn add @geolonia/normalize-japanese-addresses`、`bun add @geolonia/normalize-japanese-addresses`

## README

# @geolonia/ 正常化- japanese- 地址

[![build](https://github.com/geolonia/normalize-japanese-addresses/actions/workflows/build.yml/badge.svg)](https://github.com/geolonia/normalize-japanese-addresses/actions/workflows/build.yml)

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

経産省の [IMI コンポーネントツール](https://info.gbiz.go.jp/tools/imi_tools/)のジオコーディングの仕組みからインスピレーションをうけて開発しました。

## デモ

[https://geolonia.github.io/ 规范化-贾帕内塞-地址/](https://geolonia.github.io/normalize-japanese-addresses/)

## インストール

时间轴: `@geolonia/normalize-japanese-addresses` として配布されています。 无。

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

## 使い方

### `normalize(address: string, option: Option)`

住所を正規化します。

```javascript
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` オプションで指定することで処理を速くすることができます。

```javascript
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`

\# # 网络 API # # # `https://japanese-addresses-v2.geoloniamaps.com/api/ja` API 页面存档备份,存于互联网档案馆 [吉洛尼亚岛](https://github.com/geolonia/japanese-addresses-v2/) を参考にしてください。

节点JS環境のみ、このオプションに対して `file://` \[永久失效連結\] \[永久失效連結\]。

## 正規化の内容

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

参考:

-   [ゆらぎを処理している文字列に関しては、ソースコードを御覧ください。](https://github.com/geolonia/normalize-japanese-addresses/blob/master/src/lib/dict.ts)
-   [変換前、変換後の住所の例はテストコードを御覧ください。](https://github.com/geolonia/normalize-japanese-addresses/blob/master/test/main.test.ts)

## 開発者向け情報

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

```shell
$ git clone git@github.com:geolonia/normalize-japanese-addresses.git
$ cd normalize-japanese-addresses
$ npm install
```

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

```shell
$ npm run build
```

主节点.js

```javascript
// 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
  //   }
  // }
})
```

样本.js

```shell
$ node sample.js
```

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

## 节点JS

`normalize-japanese-addresses` 节点JS 18.x, 20.x, 22.x を対象としてテストを実施し、動作を確認しております。ビルド時は「開発環境」の. 节点JS。

节点JS {快讯} {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢。

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

準拠としては [节点.js 发布](https://nodejs.org/en/about/previous-releases) 维护、活动 LTS 活动 LTS 活动。

## 页:1

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

### 貢献方法

[プルリクエスト](https://github.com/geolonia/normalize-japanese-addresses/pulls) 页:1 [问题](https://github.com/geolonia/normalize-japanese-addresses/issues) はいつでも歓迎します。

## ライセンス、利用規約

-   麻省理工学院。
-   ご利用に際しましては、できればソーシャルでのシェア、[地罗尼亚](https://geolonia.com/) へのリンクの設置などをしていただけると、開発者たちのモチベーションが上がると思います。

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

## 常见问题

### @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 和提交记录判断。

