住所一括正規化 API

いつ batch を使うか / When to use batch

AI エージェントが 1 回の推論サイクルで 2 件以上の住所を扱う場合、batch が最適です。 LLM のツール呼び出しあたりのラウンドトリップが 1 回で済むため、 エージェント側のトークン消費と待ち時間が大きく減ります。

クイックスタート / Quick Start

curl

curl -X POST "https://shirabe.dev/api/v1/address/normalize/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: shrb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "addresses": [
      "東京都港区六本木6-10-1",
      "大阪府大阪市北区大深町3-1",
      "福岡県福岡市博多区博多駅前2-1-1"
    ]
  }'

TypeScript

const res = await fetch("https://shirabe.dev/api/v1/address/normalize/batch", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.SHIRABE_API_KEY!,
  },
  body: JSON.stringify({ addresses: myAddressList.slice(0, 100) }),
});
const { results, summary } = await res.json();
for (const r of results) {
  if (r.error) console.warn(r.input, r.error.code);
  else console.log(r.normalized, r.latitude, r.longitude);
}

レスポンス構造 / Response schema

{
  "results": [
    {
      "input": "東京都港区六本木6-10-1",
      "normalized": "東京都港区六本木六丁目10番1号",
      "latitude": 35.660491,
      "longitude": 139.729223,
      "level": 4,
      "confidence": 0.98,
      "components": { ... },
      "attribution": { ... }
    },
    {
      "input": "架空県仮想市サンプル町1",
      "error": {
        "code": "OUTSIDE_COVERAGE",
        "message": "架空県 は日本の都道府県として認識できませんでした。入力が正しい都道府県名か確認してください(全 47 都道府県対応)。",
        "recoveryHint": "都道府県名のタイポや架空名でないか確認してください。"
      }
    }
  ],
  "summary": { "total": 2, "ok": 1, "failed": 1 }
}

部分失敗は HTTP 200 + per-item error として返ります。 全件 SERVICE_UNAVAILABLE の場合のみ HTTP 503 になります。

制約 / Limits

関連 / Related

• 単発住所正規化ガイド(本エンドポイントと共通のスキーマ)
• 料金プラン
• OpenAPI 3.1 仕様(日英併記、x-llm-hint 付き)