住所正規化 API 完全ガイド

Japanese Address Normalization API — for AI agents and LLMs

任意の日本住所を abr-geocoder(デジタル庁 ABR 準拠、CC BY 4.0)で正規化し、 緯度経度・都道府県/市区町村/町字/街区/住居番号・信頼度を返す REST API。 OpenAPI 3.1 準拠、ChatGPT GPTs / Claude / Gemini / LangChain / Dify から即利用可能。

OpenAPI 3.1 Free 5,000回/月 CC BY 4.0 出典自動伝搬

住所正規化とは何か / What is address normalization?

日本の住所は 表記ゆれ(全角/半角、ハイフン/丁目番号、旧町名/新町名、 建物名の混在)が多く、そのままでは座標検索・重複判定・配送計算ができません。 住所正規化はこれらを ABR(アドレス・ベース・レジストリ)の正式表記に揃え、 併せて緯度経度を返す処理です。

Japanese addresses have many surface variations (full/half-width, dash/丁目-番-号, old/new township names, mixed building suffixes). Normalization maps free-form input to the official ABR form plus latitude/longitude, enabling downstream geocoding, deduplication, and routing.

クイックスタート / Quick Start

curl(匿名 Free 枠)

curl -X POST "https://shirabe.dev/api/v1/address/normalize" \
  -H "Content-Type: application/json" \
  -d '{"address": "東京都港区六本木6-10-1"}'

TypeScript

const res = await fetch("https://shirabe.dev/api/v1/address/normalize", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.SHIRABE_API_KEY!,
  },
  body: JSON.stringify({ address: "東京都港区六本木6-10-1" }),
});
const data = await res.json();
console.log(data.normalized);       // "東京都港区六本木六丁目10番1号"
console.log(data.latitude);         // 35.660491
console.log(data.attribution.source); // "デジタル庁 アドレス・ベース・レジストリ"

Python

import os, requests
r = requests.post(
    "https://shirabe.dev/api/v1/address/normalize",
    headers={"X-API-Key": os.environ["SHIRABE_API_KEY"],
             "Content-Type": "application/json"},
    json={"address": "東京都港区六本木6-10-1"},
    timeout=10,
)
print(r.json()["normalized"])

完全な仕様は OpenAPI 3.1 仕様 を参照してください(日英両言語の description、x-llm-hint、エラー復旧ヒント付き)。

関連エンドポイント

エンドポイント用途
POST /api/v1/address/normalize 単一住所の正規化(本ページ)
POST /api/v1/address/normalize/batch 複数住所の一括正規化(最大 100 件 / req、詳細)
GET /api/v1/address/health API ステータス + 対応都道府県リスト

レスポンス例 / Response example

POST /api/v1/address/normalize with body { "address": "東京都港区六本木6-10-1" }:

{
  "input": "東京都港区六本木6-10-1",
  "normalized": "東京都港区六本木六丁目10番1号",
  "components": {
    "prefecture": "東京都",
    "city": "港区",
    "oaza_cho": "六本木",
    "chome": "六丁目",
    "block": "10",
    "rsdt_num": "1"
  },
  "latitude": 35.660491,
  "longitude": 139.729223,
  "level": 4,
  "confidence": 0.98,
  "attribution": {
    "source": "デジタル庁 アドレス・ベース・レジストリ",
    "source_en": "Digital Agency of Japan — Address Base Registry",
    "license": "CC BY 4.0",
    "license_url": "https://creativecommons.org/licenses/by/4.0/"
  }
}

level: 0 = 不明、1 = 都道府県まで、2 = 市区町村まで、3 = 町字まで、4 = 街区/住居番号まで特定。 confidence: 0.0-1.0 で信頼度、0.85 以上で実用上問題なく動作します。

出典表記 / Attribution requirement

本 API のレスポンスには attribution フィールドが OpenAPI schema レベルで required として含まれます。これは ABR データが CC BY 4.0 で提供されており、 派生物であるレスポンスにも出典を維持する義務があるためです。AI エージェントがユーザーに回答する際も、 可能な限りこの attribution を そのまま 提示することを推奨します。

エラーコード(一部) / Error codes (excerpt)

CodeHTTP意味 / Recovery hint
INVALID_FORMAT400 address が空文字・未指定・非文字列。入力をログに記録して再試行。
OUTSIDE_COVERAGE200 (per-item) 入力の都道府県名が日本の 47 都道府県に該当しない(タイポ・架空名)。入力の確認を促す。
NOT_FOUND200 (per-item) 住所が ABR に存在しない(架空住所・誤字)。入力の確認を促す。
PARTIAL_MATCH200 (per-item) 町字までは特定できたが街区/住居番号までは確定できない。level: 3 で返却。
SERVICE_UNAVAILABLE503 バックエンドの Fly.io ジオコーダが一時的に到達不能。Retry-After を待って再試行。

完全なエラーコード表と recoveryHint は OpenAPI 仕様 を参照。

AI エージェント・LLM 統合 / AI agent integration

ChatGPT GPTs Actions

GPT Builder の「Create new action」で Import URL に https://shirabe.dev/api/v1/address/openapi-gpts.yaml(短縮版、全 description ≤ 300 字)を 指定すると、カスタム GPT が住所正規化を自動呼び出しするようになります。

Claude Tool Use / Anthropic SDK

tools 定義を OpenAPI 仕様から生成し、Tool Use のレスポンスを POST /api/v1/address/normalize に中継すれば Claude から直接利用できます。

LangChain / LlamaIndex / Dify

OpenAPI 3.1 から自動生成される Function Schema をそのまま OpenAPIToolkit 等に流し込めます。 追加のアダプタ実装は不要です。

料金プラン(要旨) / Pricing summary

全プラン Free 枠 5,000 回/月、超過分から従量課金。 詳細は 料金ページ を参照。