Pythonから15分 — Staddress で住所解析する

住所正規化・ジオコーディングAPI 「Staddress（スタドレス）」 開発チームです。

前回（Node.js — @staddress/client で住所解析する）は、公式 Node.js SDK を紹介しました。

今回は、公式 Python SDK staddress を使い、同期・非同期の両方から住所解析を呼び出します。

この記事で扱う内容は次の通りです。

1. staddress をインストールする
2. StaddressClient で同期クライアントを初期化する
3. parse_address で単件解析する
4. get_usage で利用状況を確認する
5. StaddressError でエラーを扱う
6. （任意）StaddressAsyncClient で非同期呼び出しする
7. （任意）parse_batch で一括解析する

---

前提

• Free アカウント登録が完了していること
• アカウント管理画面で API Key を確認できること
• Python 3.11+
• pip / uv / poetry のいずれか

今回使う SDK はこちらです。

• PyPI: staddress
• ソース: StaddressAI/staddress-tools — packages/python

特徴:

• HTTP は httpx（同期・非同期の両方）
• レスポンス型は pydantic v2（py.typed 同梱）
• Trusted Publishing による PyPI 公開（provenance 付き）

バージョン確認:

python -V   # 3.11 以上であること

---

Step 1. インストールする

pip install staddress
# または
uv add staddress
poetry add staddress

インストール確認:

pip show staddress

---

Step 2. 同期クライアントを初期化する

from staddress import StaddressClient, StaddressError

client = StaddressClient(
    api_key="sk_xxxxxxxxxxxxxxxxxxxx",  # 省略時は環境変数 STADDRESS_API_KEY
    base_url="https://api.staddress.com",  # 省略時は既定値
    timeout=30.0,  # 任意（秒）
)

実行前に API Key を環境変数へ設定するのがおすすめです。

export STADDRESS_API_KEY="sk_xxxxxxxxxxxxxxxxxxxx"

コンテキストマネージャでも使えます。

with StaddressClient() as client:
    result = client.parse_address(input="六本木ヒルズ 森タワー 52F")
    print(result.normalized)

注意: API Key は秘密情報です。リポジトリやノートブックにコミットしないでください。

---

Step 3. parse_address で単件解析する

result = client.parse_address(
    input="六本木ヒルズ 森タワー 52F",
    postal_code="106-6100",  # 任意
)

print(result.normalized)
print(result.components.pref)
print(result.confidence)

内部的には POST /api/v1/addresses/parse を呼び出しています。
レスポンスの見方（normalized / components / confidence）は、curl 編 と同じです。

使い終わったら接続を閉じます（with を使わない場合）。

client.close()

---

Step 4. get_usage で利用状況を確認する

usage = client.get_usage()
print(usage)

Free プランでは月間の解析上限を確認できます。

---

Step 5. エラーハンドリング

API エラー・ネットワークエラーは StaddressError として送出されます。

from staddress import StaddressClient, StaddressError

client = StaddressClient()

try:
    client.parse_address(input="...")
except StaddressError as err:
    print(err.code)         # 例: "unauthorized", "quota_exceeded", "unresolved"
    print(err.http_status)  # HTTP ステータス（ネットワークエラー時は 0）
    print(err.request_id)   # サポート問い合わせ用（あれば）
    print(err.retry_after)  # 再試行可能日時（あれば）

code の例	意味の目安
unauthorized	API Key 未設定・無効
quota_exceeded	月間上限超過
unresolved	住所として解析できなかった

---

Step 6.（任意）非同期クライアント

FastAPI や非同期バッチ処理では、StaddressAsyncClient を使います。

import asyncio
from staddress import StaddressAsyncClient

async def main():
    async with StaddressAsyncClient() as client:
        result = await client.parse_address(input="六本木ヒルズ 森タワー 52F")
        print(result.normalized)

        usage = await client.get_usage()
        print(usage)

asyncio.run(main())

メソッド名は同期版と同じで、呼び出し時に await するだけです。

---

Step 7.（任意）parse_batch で一括解析する

一括解析は Standard プラン以上、最大100件です。

results = client.parse_batch([
    {"id": "1", "address": "東京都渋谷区道玄坂1-2-3"},
    {"id": "2", "address": "大阪府大阪市北区梅田1-1-1"},
])

for item in results:
    print(item.id, item.result.normalized if item.result else item.error)

---

Node SDK / CLI との使い分け

観点	CLI / Node SDK	Python SDK（今回）
配布	GitHub / npm	PyPI: staddress
主な用途	シェル自動化 / Node アプリ	データ処理・バッチ・FastAPI 等
HTTP	curl / fetch	httpx（sync + async）
型	TypeScript 型定義	pydantic v2
エラー	終了コード / StaddressError	StaddressError

データ分析や既存の Python パイプラインに載せるなら今回の SDK、フロントや Node バックエンドなら Node 編、手元検証なら CLI 編 が向いています。

---

よくあるつまづき

API key is required / unauthorized

echo "$STADDRESS_API_KEY"

空なら export し直すか、StaddressClient(api_key="...") を渡してください。

Python バージョンが古い

SDK は Python 3.11+ が必要です。

python -V

quota_exceeded

Free の月間上限に達しています。get_usage() で残量を確認し、必要ならプランを見直してください。

input が組み込み関数と紛らわしい

SDK はキーワード引数 input= で渡します。組み込みの input() とは別物です。

# OK
client.parse_address(input="東京都港区六本木...")

# 位置引数ではなく、キーワードで渡す

---

まとめ

今回は、公式 Python SDK staddress で住所解析する手順を紹介しました。

• pip install staddress ですぐ使える（PyPI）
• 同期は StaddressClient、非同期は StaddressAsyncClient
• parse_address / get_usage / parse_batch で主要 API をカバー
• StaddressError で code・HTTP ステータス・request_id を扱える
• API Key は環境変数で渡し、リポジトリに載せない
• レスポンスの見方は curl 編 と同じ

---

Staddress ホームセット

Staddress に関する公式リンク一覧です。

• 公式サイト（トップ）
• Staddress Enterprise
• お問い合わせ・無料プラン申込
• 公式 Qiita
• 公式 Zenn