Japanese addresses v2

.github/workflows/build.yml

@@ -14,40 +14,76 @@ on:
 
 jobs:
   build:
+    name: "ビルド・リント"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run lint
+
+  test:
+    name: "テスト"
+    needs:
+      - build
+
     runs-on: ${{ matrix.os }}
 
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
-        node-version: [16.x, 18.x, 20.x]
+        node-version: [18.x, 22.x]
 
     steps:
       - uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
       - run: npm ci
-      - run: npm run build
       - run: npm run lint
       - run: npm test
-      # allow fails
-      # - run: npm run test:addresses || true
+
+  # アドレステストは時間かかるし、環境依存が無いので、matrixにいれる必要無い
+  test-addresses:
+    name: "詳細住所テスト"
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test:addresses
 
   publish:
-    name: 'Publish npm package'
+    name: 'npm 公開'
     runs-on: ubuntu-latest
-    needs: build
+    needs:
+      - test
     if: startsWith(github.ref, 'refs/tags/v')
     steps:
       - uses: actions/checkout@v4
       # Setup .npmrc file to publish to npm
       - uses: actions/setup-node@v4
         with:
-          node-version: '20.x'
+          node-version: '22.x'
           registry-url: 'https://registry.npmjs.org'
           scope: '@geolonia'
-      - run: npm install
+          cache: 'npm'
+      - run: npm ci
       - run: npm run build
       - run: npm publish --access=public
         env:

.gitignore

@@ -29,3 +29,6 @@ yarn-error.log*
 yarn.lock
 
 test/japanese-addresses-master
+
+# version
+src/version.ts

.prettierrc.js

@@ -1,4 +1,4 @@
-module.exports = {
+export default {
   semi: false,
   trailingComma: 'all',
   singleQuote: true,

.tool-versions

@@ -0,0 +1 @@
+nodejs 22.9.0

README.md

@@ -8,7 +8,7 @@
 
 ## デモ
 
-https://codepen.io/geolonia/pen/oNBrqzL
+近々公開予定
 
 ##  インストール
 
@@ -26,9 +26,25 @@ $ npm install @geolonia/normalize-japanese-addresses -S
 住所を正規化します。
 
 ```javascript
-const { normalize } = require('@geolonia/normalize-japanese-addresses')
+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", "lat": 43.074273, "lng": 141.315099, "level"; 3}
+  console.log(result);
+  // {
+  //   "pref": "北海道", // 都道府県名
+  //   "city": "札幌市西区", // 市区町村名
+  //   "town": "二十四軒二条二丁目", // 大字・丁目名
+  //   "addr": "3-3", // 街区符号・住居符号または地番
+  //   "level": 8, // 正規化レベル
+  //   "point": {
+  //     "lat": 43.074206115, // 緯度
+  //     "lng": 141.315540696, // 軽度
+  //     "level": 8 // 位置情報データレベル
+  //   },
+  //   "other": "" // 正規化できなかった文字列
+  // }
 })
 ```
 
@@ -37,48 +53,47 @@ normalize('北海道札幌市西区24-2-2-3-3').then(result => {
 * `0` - 都道府県も判別できなかった。
 * `1` - 都道府県まで判別できた。
 * `2` - 市区町村まで判別できた。
-* `3` - 町丁目まで判別できた。
+* `3` - 大字・丁目まで判別できた。
+* `8` - 住居表示住所の街区符号・住居符号または地番住所の地番まで判別できた。
+
+`point` に位置情報データ (EPSG:4326) が入っています。位置情報の精度を表す `level` プロパティを参照してください。住所正規化レベルと位置情報データのレベルが異なる場合は主には、住居表示または地番情報（レベル8）は存在しましたが、位置情報データが存在しなかった場合。この場合は、大字・丁目の代表点の位置情報データを返却します。
+
+位置情報データのレベルは下記となります。
 
-例えば都道府県名のみを正規化したい場合、`level` オプションで指定することで処理を速くすることができます。
+* `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": "北海道", "city": "", "town": "", "addr": "札幌市西区二十四軒二条二丁目3-3", "lat": null, "lng": null, "level"; 1}
+  console.log(result);
+  // {
+  //   "pref": "北海道",
+  //   "other": "札幌市西区24-2-2-3-3",
+  //   "level": 1,
+  //   "point": {
+  //     "lat": 43.0639406375,
+  //     "lng": 141.347906782,
+  //     "level": 1
+  //   }
+  // }
 })
 ```
 
 ### グローバルオプション
 
 以下のパラメーターを変更することでライブラリの動作全体に関わる設定が変更できます。
 
-#### `config.townCacheSize: number`
-
-＠geolonia/normalize-japanese-addresses は市区町村毎の最新の町丁目のデータを web API から取得し住所の正規化を行います。`townCacheSize` オプションはキャッシュする市区町村の数を変更します。デフォルトは 1,000 件になっています。
 
 #### `config.japaneseAddressesApi: string`
 
-町丁目データを配信する web API のエンドポイントを指定します。デフォルトは `https://geolonia.github.io/japanese-addresses/api/ja` です。この API から配信されるデータのディレクトリ構成は [Geolonia 住所データ](https://github.com/geolonia/japanese-addresses/tree/develop/api)を参考にしてください。
-
-このオプションに対して `file://` 形式の URL を指定することで、ローカルファイルとして保存したファイルを参照することができます。
+住所データを配信する Web API のエンドポイントを指定します。デフォルトは `https://japanese-addresses-v2.geoloniamaps.com/api/ja` です。この API から配信されるデータのディレクトリ構成は [Geolonia 住所データ](https://github.com/geolonia/japanese-addresses-v2/) を参考にしてください。
 
-##### 使用例
-
-```shell
-# Geolonia 住所データのダウンロード
-$ curl -sL https://github.com/geolonia/japanese-addresses/archive/refs/heads/master.tar.gz | tar xvfz -
-```
-
-```javascript
-const { config, normalize } = require('@geolonia/normalize-japanese-addresses')
-config.japaneseAddressesApi = 'file:///path/to/japanese-addresses-master/api/ja'
-
-(function(){
-  for (address of addresses) {
-    await normalize(address)
-  }
-})()
-```
+NodeJS環境のみ、このオプションに対して `file://` 形式の URL を指定することで、ローカルファイルとして保存したファイルを参照することができます。
 
 ## 正規化の内容
 
@@ -118,9 +133,24 @@ dist フォルダ以下に main-node.js など必要なファイルが生成さ
 
 ```javascript
 // sample.js
-const { normalize } = require('./dist/main-node.js');
+import { normalize } from './dist/main-node-esm.js';
+// 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": "", "addr": "札幌市西区二十四軒二条二丁目3-3", "level": 1 }
+  console.log(result);
+  // {
+  //   "pref": "北海道",
+  //   "city": "札幌市西区",
+  //   "town": "二十四軒二条二丁目",
+  //   "other": "3-3",
+  //   "level": 3,
+  //   "point": {
+  //     "lat": 43.074273,
+  //     "lng": 141.315099,
+  //     "level": 3
+  //   }
+  // }
 })
 ```
 
@@ -136,7 +166,7 @@ $ node sample.js
 
 * この正規化エンジンは、住所の「名寄せ」を目的としており、たとえば京都の「通り名」は削除します。
   * 郵便や宅急便などに使用される住所としては、問題ないと考えています。
-* この正規化エンジンは、町丁目及び小字レベルまでは対応していますが、それ以降については対応しておりません。
+* 正規化に利用するデータは、 [`japanese-addresses-v2`](https://github.com/geolonia/japanese-addresses-v2) で作成されます。元データに関してはそのレポジトリを御覧ください。
 * 住居表示が未整備の地域については全体的に苦手です。
 
 ### 貢献方法

eslint.config.mjs

@@ -0,0 +1,42 @@
+import tsdoc from 'eslint-plugin-tsdoc'
+import tsParser from '@typescript-eslint/parser'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import js from '@eslint/js'
+import { FlatCompat } from '@eslint/eslintrc'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+})
+
+export default [
+  {
+    ignores: ['node_modules/', 'dist'],
+  },
+  ...compat.extends(
+    'plugin:@typescript-eslint/recommended',
+    'plugin:prettier/recommended',
+  ),
+  {
+    plugins: {
+      tsdoc,
+    },
+
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: 2020,
+      sourceType: 'module',
+    },
+
+    rules: {
+      '@typescript-eslint/explicit-module-boundary-types': 0,
+      '@typescript-eslint/ban-ts-comment': 0,
+      '@typescript-eslint/no-var-requires': 0,
+      'tsdoc/syntax': 'error',
+    },
+  },
+]