# 住所正規化 API

デジタル庁「アドレス・ベース・レジストリ」をもとに、住所文字列を正規化するAPIです。
全国約2,370万件（都道府県・市区町村・町字・住居表示）を収録しています。

## Base URL

```
https://address.abalol.blog
```

---

## エンドポイント

### GET /search

住所文字列を解析し、正規化された住所・各種コードを返します。

#### リクエスト

```
GET /search?query=東京都新宿区西新宿1丁目1-1
```

| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| `query` | string | ✅ | 都道府県から始まる住所文字列 |

- 全角数字・漢数字（一丁目）は自動で変換
- ハイフン類（－、―）は自動で正規化
- 番地部分は `1-1` / `1番1号` どちらの表記も対応

#### レスポンス

```json
{
  "query": "東京都新宿区西新宿1丁目1-1",
  "level": "rsdt",
  "lg_code": "131016",
  "pref": "東京都",
  "city": "新宿区",
  "ward": "",
  "town": "西新宿一丁目",
  "machiaza_id": "0011001",
  "blk_id": "001",
  "rsdt_id": "001",
  "blk_num": "1",
  "rsdt_num": "1",
  "post_code": "160-0023",
  "address": "東京都新宿区西新宿一丁目1番1号"
}
```

| フィールド | 説明 |
|---|---|
| `level` | 特定できた粒度（`city` / `town` / `block` / `rsdt`） |
| `lg_code` | 全国地方公共団体コード（6桁） |
| `pref` | 都道府県名 |
| `city` | 市区町村名 |
| `ward` | 区名（政令指定都市のみ） |
| `town` | 町字名（大字＋丁目） |
| `machiaza_id` | 町字ID（7桁） |
| `blk_id` | 街区ID |
| `rsdt_id` | 住居ID |
| `blk_num` | 街区番号 |
| `rsdt_num` | 住居番号 |
| `post_code` | 郵便番号 |
| `address` | 正規化された住所（正式表記） |

#### level の読み方

| level | 意味 |
|---|---|
| `city` | 市区町村まで特定（町字が不明） |
| `town` | 町字まで特定（番地なし or 不明） |
| `block` | 街区まで特定（住居番号なし or 不明） |
| `rsdt` | 番号まで完全特定 |

---

### GET /health

```json
{"status": "ok", "records": 21984788}
```

---

## 使用例

### 基本的な住所正規化

```bash
curl "https://address.abalol.blog/search?query=東京都新宿区西新宿1丁目1-1"
```

### 漢数字・全角数字の自動変換

```bash
curl "https://address.abalol.blog/search?query=東京都新宿区西新宿一丁目１番１号"
```

### 番地なしで町字まで取得

```bash
curl "https://address.abalol.blog/search?query=東京都新宿区西新宿1丁目"
```

### マンションAPIとの組み合わせ

```
1. このAPIで lg_code → city_name を取得
2. マンションAPIの city_name フィルターに渡してベクトル検索
```

---

## AIが利用する際の指針

- 住所の表記揺れ（全角/半角、漢数字、ハイフン類）は自動で吸収する
- `level` が `city` の場合は町字が特定できていない → 入力住所を確認
- `level` が `town` 以上であれば `lg_code` と `machiaza_id` が利用可能
- マンション名寄せ時は `city`（ward があれば ward）を mansion API の `city_name` に渡す

---

## データ仕様

- **件数**: 約2,370万件
- **出典**: デジタル庁 アドレス・ベース・レジストリ（2026年5月時点）
- **収録範囲**: 都道府県・市区町村・町字・住居表示（街区・住居）
- **非収録**: 地番マスター