住所正規化 API ドキュメント

エンドポイント仕様・レスポンス・エラー・レート制限

ベース URL: https://shirabe.dev。キーなしで月 5,000 回まで利用できます。製品概要と料金はこちら。

クイックスタート — 10 秒で最初のレスポンス

API キー不要・登録不要で今すぐ試せます(匿名 Free 枠月 5,000 回)。ターミナルに貼るだけ:

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

JavaScript / Python から:

// JavaScript(Node.js 18+ / ブラウザ / Cloudflare Workers)
const res = await fetch("https://shirabe.dev/api/v1/address/normalize", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address: "東京都港区六本木6-10-1" }),
});
console.log(await res.json());

# Python(requests)
import requests
r = requests.post("https://shirabe.dev/api/v1/address/normalize", json={"address": "東京都港区六本木6-10-1"})
print(r.json())

公式 SDK(npm / PyPI とも shirabe-sdk、core 依存ゼロ)や AI エージェントの tool としても使えます:

import { ShirabeClient } from "shirabe-sdk";
const shirabe = new ShirabeClient();
console.log(await shirabe.normalizeAddress("東京都港区六本木6-10-1"));

// AI エージェントの tool として(Vercel AI SDK / LangChain)
import { shirabeAITools } from "shirabe-sdk/ai";               // shirabe_normalize_address ほか 7 tool
// import { shirabeLangChainTools } from "shirabe-sdk/langchain";

# Python(pip install "shirabe-sdk[langchain]"、import 名は shirabe)
from shirabe.langchain import shirabe_langchain_tools    # LangChain(同じ 7 tool)
# from shirabe.openai_agents import shirabe_openai_agents_tools  # OpenAI Agents SDK

有料プランのキーは X-API-Key ヘッダーで渡します(キーなし = 匿名 Free 扱い):

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

エンドポイント

メソッド	パス	説明
`POST`	`/api/v1/address/normalize`	住所 1 件の正規化
`POST`	`/api/v1/address/normalize/batch`	一括正規化(1 回で最大 100 件)
`GET`	`/api/v1/address/health`	ヘルスチェック(認証不要・カウント対象外)

POST /api/v1/address/normalize

リクエスト:

{ "address": "東京都港区六本木6-10-1" }

レスポンス(実例):

{
  "input": "東京都港区六本木6-10-1",
  "result": {
    "normalized": "東京都港区六本木6丁目10",
    "components": {
      "prefecture": "東京都",
      "city": "港区",
      "town": "六本木6丁目",
      "block": "10番",
      "building": null,
      "floor": null,
      "jis_code": "13103",
      "lg_code": "131032",
      "machiaza_id": "0028006"
    },
    "postal_code": null,
    "latitude": null,
    "longitude": null,
    "level": 4,
    "confidence": 0.93
  },
  "candidates": [],
  "attribution": {
    "source": "アドレス・ベース・レジストリ(住所データ)",
    "provider": "デジタル庁",
    "license": "CC BY 4.0",
    "license_url": "https://creativecommons.org/licenses/by/4.0/"
  }
}

主要フィールド

フィールド	意味
`result.normalized`	正規化済み住所文字列
`result.components`	都道府県〜建物の構造化分解。`lg_code` は市区町村レベル(level 2)以上、`machiaza_id` は町字レベル(level 3)以上で付与
`result.level`	正規化の到達レベル(1=都道府県〜 8=建物)。値が大きいほど詳細まで確定
`result.confidence`	マッチ信頼度(0〜1)。しきい値でのフィルタに使えます
`result.latitude / longitude`	代表点座標。レジストリに座標がない住所では `null`
`attribution`	出典(CC BY 4.0)。必須フィールドとして常に同梱。表示・再配布時はこの出典を伝搬してください

POST /api/v1/address/normalize/batch

リクエスト(最大 100 件。超過は 400):

{ "addresses": ["東京都港区六本木6-10-1", "大阪府大阪市北区梅田1-1-3"] }

レスポンスは results 配列(入力順)で、各要素は単発 normalize と同じ形です。カウントは要素数 N = N 回分です(1 リクエスト扱いにはなりません)。

エラー

エラーは全て次の形で返ります:

{ "error": { "code": "...", "message": "..." } }

HTTP	code	意味と対処
400	`INVALID_REQUEST`	body 不正・batch 上限超過など。カウントされません
200	`OUTSIDE_COVERAGE`(result 内)	日本の住所として解釈できない入力。エラーではなく結果として返ります(カウント対象)
401	`INVALID_API_KEY`	形式不正・未登録のキー。キーを外すと匿名 Free で通ります
429	`RATE_LIMIT_EXCEEDED` / `USAGE_LIMIT_EXCEEDED`	秒間または月間上限。`Retry-After` ヘッダーと、次プランへの `next_plan.checkout_path`(→ /address/buy)を同梱
503	`SERVICE_UNAVAILABLE`	バックエンド一時障害。カウントされません。リトライしてください

レート制限とカウント規則

プラン	月間上限	秒間レート
Free	5,000 回	1 req/s
Starter	200,000 回	30 req/s
Pro	2,000,000 回	100 req/s
Enterprise	無制限	500 req/s

単発 normalize = 1 カウント、batch = 要素数 N カウント
400 系・401・503 はカウントされません(無料枠を消費しない)
残量はレスポンスヘッダー X-RateLimit-Limit / X-RateLimit-Remaining で確認できます
月間カウントは毎月 1 日 0:00 UTC にリセット

AI 統合・機械可読仕様

OpenAPI 3.1(完全版): https://shirabe.dev/api/v1/address/openapi.yaml
OpenAPI(GPTs Actions 用短縮版): https://shirabe.dev/api/v1/address/openapi-gpts.yaml

→ 製品概要・料金 / → 申し込み / → API キー再発行