@geolonia/japanese-addresses-v2

中文文档
0.0.5发布于 2024/10/18MITTypeScriptESM + CJS零依赖近 30 天下载 9.8万

NPM Version

原始使用文档
文档目录10 节
  1. API
  2. 注意
  3. 住所データ・ API のビルド
  4. API の構成
  5. 出典
  6. 貢献方法
  7. japanese-addresses-v2を使っているプロジェクト
  8. スポンサー
  9. 関連情報
  10. ライセンス

Geolonia 住所データツール v2

NPM Version

全国の住所データを HTTP API として公開するためのツールを公開いたします。

本データは、デジタル庁が整備する「アドレス・ベース・レジストリ」を元に加工し、様々なアプリケーションから便利に使えるように整理したものとなります。

以前、「Geolonia 住所データ」を管理しましたが、v2は従来版と比べて下記の違いがあります。

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

リリースノート

API

このデータを使用した API をご提供しています。現在、制限無しの無料公開をしていますが、様子見ながら公開を停止や変更など行うことがあります。商用稼働は、ご自身でデータを作成しホスティングすることを強くおすすめします。 Geolonia は有償で管理・ホスティングするサービスありますので、ご利用の方はお問い合わせてください。

都道府県エンドポイント

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

例: 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

{ "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}}},
  ...

注意

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

住所データ・ API のビルド

$ git clone [email protected]: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 の構成

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

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

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

-地番.txt と -住居表示.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 にヘッダーの start / length 情報入っているので、市区町村エンドポイントを既に読み込まれている場合はそのまま利用することをおすすめしております。

出典

本データは、以下のデータを元に、毎月 Geolonia にて更新作業を行っています。

「アドレス・ベース・レジストリ」(デジタル庁)住居表示住所・住居マスターデータセット をもとに株式会社 Geolonia が作成したものです。

貢献方法

japanese-addresses-v2を使っているプロジェクト

スポンサー

関連情報

ライセンス

Geolonia 住所データのライセンスは以下のとおりです。

CC BY 4.0

注: リポジトリに同梱されているデータ生成用のスクリプトのライセンスは MIT ライセンスとします。

版本与发布记录

@geolonia/japanese-addresses-v2 共发布 5 个版本,首次发布于 2024/10/09;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.0.5latest2024/10/182 年前
0.0.42024/10/182 年前
0.0.32024/10/092 年前
0.0.22024/10/092 年前
0.0.12024/10/092 年前

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

如何安装 @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 和提交记录判断。