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

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

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

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

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

Staddress CLI をインストールする
API Key を config に保存する
usage で利用状況を確認する
parse で単件解析する（JSON / --pretty）
（任意）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 を設定する

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

コマンドフラグ --api-key / --base-url
環境変数 STADDRESS_API_KEY / STADDRESS_BASE_URL
設定ファイル ~/.config/staddress/config
既定（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 に関する公式リンク一覧です。