ターミナル1本で完結 — Staddress CLIで住所解析する!

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

前回までは、curl / PowerShell のサンプルスクリプトで API を呼び出す手順を紹介しました。

今回は、公式の staddress コマンド（Shell CLI） をインストールして、ターミナルから直接 parse / usage を実行します。毎回サンプルディレクトリに入る必要がなく、設定もファイルに保存できます。

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

1. Staddress CLI をインストールする
2. API Key を config に保存する
3. usage で利用状況を確認する
4. parse で単件解析する（JSON / --pretty）
5. （任意）batch で一括解析する

---

前提

• Free アカウント登録が完了していること
• アカウント管理画面で API Key を確認できること
• macOS / Linux などで次が使えること
  • bash 4+
  • git
  • curl
  • jq

# macOS（Homebrew）
brew install jq

今回使う公式 CLI はこちらです。

• StaddressAI/staddress-tools — packages/cli

---

Step 1. CLI をインストールする

リポジトリを clone し、install.sh で staddress コマンドを配置します。

git clone https://github.com/StaddressAI/staddress-tools.git
cd staddress-tools/packages/cli
./install.sh

配置先を指定する場合:

./install.sh --prefix /usr/local/bin

既定では ~/.local/bin（または環境に応じたパス）へ symlink されます。
PATH に無い場合は、シェル設定に追加してください。

export PATH="$HOME/.local/bin:$PATH"

インストール確認:

staddress version
staddress --help

アンインストールする場合:

./install.sh --uninstall

---

Step 2. API Key を設定する

設定の解決順は次のとおりです（上が優先）。

1. コマンドフラグ --api-key / --base-url
2. 環境変数 STADDRESS_API_KEY / STADDRESS_BASE_URL
3. 設定ファイル ~/.config/staddress/config
4. 既定（base-url: https://api.staddress.com）

毎回フラグを付けるのが面倒な場合は、設定ファイルに保存するのがおすすめです（パーミッションは 600）。

staddress config set api-key sk_xxxxxxxxxxxxxxxxxxxx
staddress config set base-url https://api.staddress.com

# 現在の設定を確認（API キーはマスク表示）
staddress config show

環境変数でも同じです。

export STADDRESS_API_KEY="sk_xxxxxxxxxxxxxxxxxxxx"
export STADDRESS_BASE_URL="https://api.staddress.com"

注意: API Key は秘密情報です。GitHub・Qiita・Slack などに貼らないでください。

---

Step 3. usage で利用状況を確認する

staddress usage

人間可読な表示にする場合:

staddress usage --pretty

成功すると、プランと月間利用状況が返ります。Free プランでは月間の解析上限を確認できます。

---

Step 4. parse で単件解析する

staddress parse "六本木ヒルズ 森タワー 52F"

郵便番号が分かっている場合は -p（または --postal-code）を付けます。--pretty で人間可読な表示にもできます。

staddress parse "東京都渋谷区道玄坂1-2" -p 150-0043 --pretty

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

---

Step 5.（任意）batch で一括解析する

一括解析は Standard プラン以上、1リクエスト最大100件です。

staddress batch --file addresses.json
# または
cat addresses.json | staddress batch --stdin

入力 JSON の例:

{
  "items": [
    { "id": "1", "address": "東京都渋谷区道玄坂1-2-3", "postalCode": "150-0002" },
    { "id": "2", "address": "大阪府大阪市北区梅田1-1-1" }
  ]
}

items の配列のみ（トップレベルが配列）でも受け付けます。

---

curl / PowerShell サンプルとの違い

観点	curl / PowerShell サンプル	Staddress CLI（今回）
置き場所	examples/curl / examples/powershell	packages/cli（staddress コマンド）
インストール	ディレクトリへ移動して実行	install.sh で PATH に配置
設定の保存	環境変数 / .env	staddress config（~/.config/staddress/config）
主なコマンド	-u / -s などスクリプト固有	usage / parse / batch
出力	JSON（jq 整形）	JSON、または --pretty

PoC やスクリプト組み込みでは CLI、Windows だけで試すなら PowerShell 編、素の HTTP を確認するなら curl 編 が向いています。

---

よくあるつまづき

staddress: command not found

PATH にインストール先が入っていません。

export PATH="$HOME/.local/bin:$PATH"
staddress version

jq がない

CLI は JSON の整形・処理に jq を使います。

brew install jq

終了コード

コード	意味
0	成功
1	API エラー / ネットワークエラー
2	設定エラー / 使い方エラー

staddress parse --help

API Key が効かない

staddress config show
echo "$STADDRESS_API_KEY"

フラグ・環境変数・設定ファイルのどれかで Key が解決されているか確認してください。

---

まとめ

今回は、公式 Shell CLI（staddress）で住所解析する手順を紹介しました。

• packages/cli の install.sh でコマンドを PATH に入れられる
• staddress config で API Key をローカルに保存できる
• usage / parse / batch で主要 API をそのまま叩ける
• レスポンスの見方は curl 編と同じ
• API Key は秘密情報として扱う

次回は、Node.js / TypeScript 向け公式 SDK @staddress/client で、アプリから住所解析を呼び出す手順を紹介します。

---

Staddress ホームセット

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

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