# マンション情報検索 API

全国428,873件のマンション情報をベクトル検索で照合するAPIです。
建物名の表記揺れ・英語/日本語混在・略称などに対応しています。

## Base URL

```
https://mansion.abalol.blog
```

---

## エンドポイント

### POST /search

クエリテキストに最も近いマンション情報を返します。

#### リクエスト

```json
{
  "query": "検索したい建物名・住所など（自由記述）",
  "top_k": 5,
  "pref_name": "東京都",
  "city_name": "昭島市"
}
```

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `query` | string | ✅ | 建物名・住所など自由記述。日本語・英語・混在可 |
| `top_k` | integer | - | 返却件数（デフォルト5、最大50） |
| `pref_name` | string | - | 都道府県名で絞り込み（例: `"東京都"`, `"大阪府"`） |
| `city_name` | string | - | 市区町村名で絞り込み（例: `"新宿区"`, `"横浜市"`） |

- `pref_name` / `city_name` はどちらか一方だけでも指定可能
- フィルターを指定した場合、**その範囲内でのみ**ベクトル検索を行う（グローバル検索後の絞り込みではない）

#### レスポンス

```json
{
  "query": "ライオンズ西立川",
  "results": [
    {
      "score": 0.5021,
      "name": "ライオンズステージ西立川フォレストアヴェニュー",
      "yomigana": "らいおんずすてーじにしたちかわふぉれすとあゔぇにゅー",
      "pref_name": "東京都",
      "city_name": "昭島市",
      "address": "東京都昭島市東町１丁目５",
      "nearest_station": "西立川駅",
      "distance_from_station": "西立川駅から直線距離で77m",
      "tel": "",
      "latitude": 35.70325043,
      "longitude": 139.39297314,
      "elevation": "海抜94m",
      "mapcode": "5 122 016*57"
    }
  ]
}
```

| フィールド | 説明 |
|---|---|
| `score` | 類似度スコア（0〜1、高いほど類似） |
| `name` | 正式なマンション名 |
| `yomigana` | よみがな（ひらがな） |
| `pref_name` | 都道府県名 |
| `city_name` | 市区町村名 |
| `address` | 住所 |
| `nearest_station` | 最寄り駅名 |
| `distance_from_station` | 最寄り駅からの距離 |
| `tel` | 電話番号（空の場合あり） |
| `latitude` | 緯度 |
| `longitude` | 経度 |
| `elevation` | 標高 |
| `mapcode` | マップコード |

---

### GET /health

サービスの死活確認。

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

---

## 使用例

### 表記揺れの名寄せ

```bash
curl -X POST https://mansion.abalol.blog/search \
  -H "Content-Type: application/json" \
  -d '{"query": "ライオンズ西立川フォレスト", "top_k": 3, "pref_name": "東京都"}'
```

### 英語名での検索

```bash
curl -X POST https://mansion.abalol.blog/search \
  -H "Content-Type: application/json" \
  -d '{"query": "Green Forest Nishitachikawa", "top_k": 3}'
```

### 住所 + 建物名での照合

```bash
curl -X POST https://mansion.abalol.blog/search \
  -H "Content-Type: application/json" \
  -d '{"query": "東京都昭島市東町 ライオンズ", "top_k": 5, "city_name": "昭島市"}'
```

---

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

- **名寄せ目的**の場合、`score` が `0.6` 以上であれば同一建物の可能性が高い
- **0.4〜0.6** は候補として提示し、人間の確認を推奨
- **0.4未満** は一致なしとして扱うことを推奨
- 市区町村が判明している場合は `city_name` で絞り込むと精度が上がる
- `top_k: 1` で最有力候補のみ、`top_k: 5` で候補を複数返して判断させることも可能

---

## データ仕様

- **件数**: 428,873件
- **対象**: 全国47都道府県のマンション・集合住宅
- **出典**: マピオン電話帳（2026年5月時点）
- **埋め込みモデル**: `intfloat/multilingual-e5-base`（日英対応）