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

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

版本：0\.0\.5
npm 元数据更新时间：2026-02-11T05:40:43.165Z
中文译文更新时间：2026-11-16T04:29:25.588Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：18.3 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-10-09T02:31:18.253Z
- 最新版本发布：2024-10-18T08:24:30.213Z
- 近 30 天下载量：97661（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）

## 中文简介

[![NPM Version](https://img.shields.io/npm/v/%40geolonia%2Fjapanese-addresses-v2)](https://www.npmjs.com/package/@geolonia/japanese-addresses-v2)

## 安装

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

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

## README

# Geolonia 住所データツール v2 (英语)

[![NPM Version](https://img.shields.io/npm/v/%40geolonia%2Fjapanese-addresses-v2)](https://www.npmjs.com/package/@geolonia/japanese-addresses-v2)

HTTP API 请检查ACCESS-DATE=中的日期值 (帮助)。

本データは、デジタル庁が整備する「[アドレス・ベース・レジストリ](https://www.digital.go.jp/policies/base_registry_address)」を元に加工し、様々なアプリケーションから便利に使えるように整理したものとなります。

以前、「[吉洛尼亚岛](https://github.com/geolonia/japanese-addresses)」を管理しましたが、v2は従来版と比べて下記の違いがあります。。

-   住居表示住所データと対応(番地・号までのデータが含まれる)
-   地番住所のデータと対応(住居表示住所が導入されていない地域のデータが含まれる)

[リリースノート](https://github.com/geolonia/japanese-addresses-v2/releases)

## API 密码

API 页面存档备份,存于互联网档案馆. 吉洛尼亚岛。

#### 都道府県エンドポイント

```
https://japanese-addresses-v2.geoloniamaps.com/api/ja.json
```

例: [https://japanese-addresses-v2.geoloniamaps.com/api/ja.json 互联网档案馆的存檔,存档日期2013-12-12](https://japanese-addresses-v2.geoloniamaps.com/api/ja.json)

```
{ "meta": { "updated": 00000 }, "data": [
  {
    "code": 10006,
    "pref": "北海道",
    "point": [
      141.347906782,
      43.0639406375
    ]
    "cities": [
      {
        "code": 11011,
        "city": "札幌市",
        "ward": "中央区",
        "point": [
          141.35389,
          43.061414
        ]
      },
      ...
    ]
  },
  ...
```

#### 町字エンドポイント

```
https://japanese-addresses-v2.geoloniamaps.com/api/ja/<都道府県名>/<市区町村名>.json
```

\* URL \* \*。

例: [https://japanese-addresses-v2.geoloniamaps.com/api/ja/%E6%9D%B1%E4%BA%AC%E9%83%BD/%E6%96%B0%E5%AE%BF%E5%8C%BA.json](https://japanese-addresses-v2.geoloniamaps.com/api/ja/%E6%9D%B1%E4%BA%AC%E9%83%BD/%E6%96%B0%E5%AE%BF%E5%8C%BA.json)

```
{ "meta": { "updated": 00000 }, "data": [
  ...
  // 地番情報なしの住居表示未実施大字「新宿区北町」
  {"machiaza_id":"0001000","oaza_cho":"北町","point":[139.735037,35.69995]},

  // 地番情報ありの住居表示実施「新宿区新宿三丁目」
  {"machiaza_id":"0020003","oaza_cho":"新宿","chome":"三丁目","rsdt":true,"point":[139.703563,35.691227],"csv_ranges":{"住居表示":{"start":151421,"length":19193},"地番":{"start":189779,"length":8895}}},
  ...
```

### 页:1

-   町丁目エンドポイントは、すべての地名を網羅しているわけではありません。
-   アドレス・ベース・レジストリの整備状況によって住居表示が実施されている町字でも住居表示住所のデータが無いや、地番住所のデータが無いなどのことがあります。また、住居表示や地番の文字列が存在しても位置情報データがまだ存在しないケースもあります。

## API 页面存档备份,存于互联网档案馆

```shell
$ git clone git@github.com:geolonia/japanese-addresses-v2.git
$ cd japanese-addresses-v2
$ npm install
$ npm run run:all # APIを全て生成する

# オプション
$ npm run run:01_make_prefecture_city # 都道府県・市区町村のみ作成
$ npm run run:02_make_machi_aza # 町字API作成
$ npm run run:03_make_rsdt # 住居表示住所API作成 (町字APIが先に作らないとエラーになります)
$ npm run run:04_make_chiban # 地番住所API作成 (町字APIが先に作らないとエラーになります)
```

### API —— ——

```shell
└── api
    ├── ja
    │   │── {都道府県名}
    │   │   ├── {市区町村名}-住居表示.txt
    │   │   ├── {市区町村名}-地番.txt
    │   │   └── {市区町村名}.json     # 町字一覧
    │   └── {都道府県名}.json         # 市区町村一覧
    └── ja.json                     # 都道府県と市区町村の一覧
```

各ファイルの詳細な仕様は、 `src/data.ts` の型定義を参照してください。

#### `txt` ファイル内のフォーマットについて

`-地番.txt` 页:1 `-住居表示.txt` は容量節約のため、市区町村の住所を全て一つのファイルに集約するものです。そのテキストファイルのフォーマットは下記となります。

```
<町字1>,<start byte position>,<length in bytes>
<町字2>,<start byte position>,<length in bytes>
...
=END=
<padding>地番,<町字1>
prc_num1,prc_num2,prc_num3,lng,lat
1,,,<経度>,<緯度>
...
```

論理的な構造としては

1.  ファイル全体のヘッダー
    1.  ファイル内の町字(丁目、小字含む)一覧
        1.  それぞれのデータのバイトレンジ(開始バイト数、容量バイト数)
2.  町字データ(ループ)
    1.  町字データのヘッダー
        1.  地番・住居表示か
        2.  カラム名定義
    2.  住所・位置情報データ

ヘッダーは5万バイトの倍数となります。末尾に `=END=` を挿入し、残りまで `0x20` (半角スペース)で埋めます。クライアントは `=END=` を確認できるまで、5万バイトずつ読み込むことをおすすめします。

また、 `api/ja/{都道府県名}/{市区町村名}.json` エンドポイントにも、 `csv_ranges` 开始/长度 {}。

## 出典

吉罗尼亚。

「アドレス・ベース・レジストリ」(デジタル庁)[住居表示住所・住居マスターデータセット](https://catalog.registries.digital.go.jp/) 吉罗尼亚。

## 貢献方法

-   本データに不具合がある場合には、[问题](https://github.com/geolonia/japanese-addresses-v2/issues) または[プルリクエスト](https://github.com/geolonia/japanese-addresses-v2/pulls)にてご報告ください。

## 日语-地址-v2-を使っているプロジェクト

-   [正常的日本地址](https://github.com/geolonia/normalize-japanese-addresses) 日本の住所を正規化するライブラリ

## スポンサー

-   [一般社団法人](https://retechjapan.org/)

## 関連情報

-   [盖洛尼亚 身份证](https://retechjapan.org/news/archives/pressrelease-20200731/)
-   [【プレスリリース】日本全国の住所マスターデータをオープンデータとして無料公開](https://geolonia.com/pressrelease/2020/08/05/japanese-addresses.html)

## ライセンス

吉洛尼亚岛。

[CC BY 4.0 (英语)](https://creativecommons.org/licenses/by/4.0/deed.ja)

翻译:。

## 常见问题

### 如何安装 @geolonia/japanese-addresses-v2？

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

### @geolonia/japanese-addresses-v2 支持 TypeScript 吗？

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

### @geolonia/japanese-addresses-v2 支持 ESM 还是 CommonJS？

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

### @geolonia/japanese-addresses-v2 可以商用吗？

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

### @geolonia/japanese-addresses-v2 的下载量有多少？

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

### @geolonia/japanese-addresses-v2 还在维护吗？

最新版本 0\.0\.5 发布于 2024/10/18（2 年前）；至今共发布 5 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/10/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

