Windowsでも15分 — Staddress APIをPowerShellで呼び出す（Token取得・usage・単件解析）
住所正規化・ジオコーディングAPI 「Staddress（スタドレス）」 開発チームです。
前回（Staddress APIをcurlで呼び出す）は、macOS / Linux 向けに curl サンプルで API を試す手順を紹介しました。
今回は Windows 環境 向けに、追加ツール（curl / jq）なしで動く PowerShell サンプル を使って、同じ流れを試します。
この記事で扱う内容は次の通りです。
- アカウント管理画面で API Key を確認する
-
staddress-toolsの PowerShell サンプルを clone する - 実行ポリシーを確認し、スクリプトを動かす
-
usageAPI で利用状況を確認する - 単件解析 API で住所を1件解析する
前提
- Free アカウント登録が完了していること
- アカウント管理画面で API Key を確認できること
- Windows で PowerShell 5.1（標準）または PowerShell 7+ が使えること
-
gitが使えること（Git for Windows など）
今回使うサンプルコードはこちらです。
Invoke-RestMethod のみで動作するため、jq のインストールは不要です。
Step 1. API Key を確認する
Staddress のアカウント管理画面を開き、画面下部の エンドポイント 欄で次を確認します。
- API Key（コピーボタンで取得）
-
API ドメイン（
https://api.staddress.com）
API Key は、API 呼び出し時に X-Api-Key ヘッダへ設定します。
X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxx
注意: API Key はパスワードと同じく秘密情報です。Qiita・GitHub・Slack などに貼らないようにしてください。
Step 2. PowerShell サンプルを clone する
git clone https://github.com/StaddressAI/staddress-tools.git
cd staddress-tools\examples\powershell
中身は次のような構成です。
examples/powershell/
├── README.md
├── batch-sample.json
└── staddress.ps1
今回使うのは staddress.ps1 です。
| 操作 | コマンド | API |
|---|---|---|
| 利用状況確認 | .\staddress.ps1 -Usage |
GET /api/v1/usage |
| 単件解析 | .\staddress.ps1 -Single "住所" |
POST /api/v1/addresses/parse |
| 一括解析 | .\staddress.ps1 -Batch .\batch-sample.json |
POST /api/v1/addresses/parse/batch |
この記事では 利用状況確認 と 単件解析 を試します。
Step 3. 実行ポリシーを確認する
Windows では、PowerShell の実行ポリシーにより .ps1 の直接実行がブロックされることがあります。
その場合は、次のいずれかで実行してください。
# 方法 A: 現在のセッションだけ許可して実行（おすすめ）
powershell -ExecutionPolicy Bypass -File .\staddress.ps1 -Usage
# 方法 B: PowerShell 7+ の場合
pwsh -File .\staddress.ps1 -Usage
# 方法 C: 直接実行（実行ポリシーが RemoteSigned / Unrestricted の場合）
.\staddress.ps1 -Usage
以降のコマンド例は、方法 C（.\staddress.ps1 ...）で書きます。ブロックされる場合は方法 A に読み替えてください。
Step 4. 接続先と API Key を設定する
設定方法は3つあります（優先順位は上から）。
- コマンドライン引数で指定する
- 環境変数 /
.envで指定する - 対話入力（未設定時にプロンプト表示。API Key は非表示入力）
最初は、引数で指定するのが分かりやすいです。
.\staddress.ps1 `
-Server https://api.staddress.com `
-Key sk_xxxxxxxxxxxxxxxxxxxx `
-Usage
毎回 -Key を入力するのが面倒な場合は、環境変数を使うのがおすすめです。
$env:STADDRESS_BASE_URL = "https://api.staddress.com"
$env:STADDRESS_API_KEY = "sk_xxxxxxxxxxxxxxxxxxxx"
.\staddress.ps1 -Usage
リポジトリルートに .env を置く方法もあります。
Copy-Item ..\..\.env.example ..\..\.env
# ..\..\.env を編集して STADDRESS_API_KEY / STADDRESS_BASE_URL を設定
.\staddress.ps1 -Usage
.env は UTF-8 で保存してください（文字化け防止）。
Step 5. usage で利用状況を確認する
まずは API Key が正しく使えるか、利用状況 API で確認します。
.\staddress.ps1 -Usage
成功すると、アカウント情報と利用状況が JSON で返ります。
{
"account": {
"plan": "free",
"planDisplayName": "Freeプラン"
},
"usage": {
"monthly": {
"limit": 100,
"used": 0,
"remaining": 100
}
}
}
Free プランでは、月間の解析上限が表示されます。
Step 6. 単件解析を実行する
次に、住所を1件解析してみます。
.\staddress.ps1 -Single "六本木ヒルズ 森タワー 52F"
郵便番号が分かっている場合は -PostalCode を付けます。
.\staddress.ps1 -Single "東京都渋谷区道玄坂1-2 マンション桜 101号" -PostalCode "150-0043"
内部的には、次の API を呼び出しています。
POST /api/v1/addresses/parse
X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
リクエストボディは次のような形です。
{
"input": "六本木ヒルズ 森タワー 52F"
}
レスポンスの見方（normalized / components / confidence など）は、前回記事の「レスポンスで見るべきポイント」 と同じです。Windows でも返ってくる JSON の構造は変わりません。
curl サンプルとの違い
| 観点 | curl（前回） | PowerShell（今回） |
|---|---|---|
| 主な環境 | macOS / Linux / WSL | Windows |
| 追加ツール |
curl + jq 推奨 |
不要（Invoke-RestMethod） |
| スクリプト | staddress.sh |
staddress.ps1 |
| 利用状況 |
-u / --usage
|
-Usage |
| 単件解析 | -s "住所" |
-Single "住所" |
| 文字化け対策 | シェルのロケールに依存しにくい | リクエストボディを UTF-8 で送信（Windows PowerShell 5.1 向け） |
どちらのサンプルも、呼んでいる API（usage / 単件解析 / 一括解析）は同じです。
社内が Windows 中心なら今回の PowerShell、macOS / Linux なら前回の curl を選ぶと導入しやすいです。
よくあるつまづき
.ps1 が実行できない（実行ポリシー）
次のようにして、現在のセッションだけ許可します。
powershell -ExecutionPolicy Bypass -File .\staddress.ps1 -Usage
401 unauthorized が返る
API Key が未設定、または誤っている可能性があります。
echo $env:STADDRESS_API_KEY
表示されない場合は、もう一度環境変数を設定してください。
日本語が文字化けする
.env や一括解析用 JSON は UTF-8 で保存してください。
staddress.ps1 は、Windows PowerShell 5.1 向けにリクエストボディを UTF-8 バイト列へ変換して送信しています。
STADDRESS_BASE_URL を毎回聞かれる
環境変数が設定されていない状態です。
$env:STADDRESS_BASE_URL = "https://api.staddress.com"
入力できる住所が長すぎる
単件解析の input は最大100文字です。会社名・部署名・宛名などが混ざっている場合は、住所欄と宛名欄を分ける設計をおすすめします。
まとめ
今回は、Windows の PowerShell から Staddress API を呼び出す手順を紹介しました。
- Windows 標準の PowerShell 5.1 / PowerShell 7+ で、追加ツールなしに試せる
-
staddress-toolsのexamples/powershell/staddress.ps1でusageと単件解析をすぐ試せる - 実行ポリシーでブロックされたら
-ExecutionPolicy Bypassを使う - レスポンスの見方は curl 編 と同じ
- API Key は秘密情報として扱い、画面共有・記事・GitHub には載せない
次回は、EC・物流SaaS向けに、配送先住所をどのタイミングで正規化するかを実装パターンとして整理します。
Staddress ホームセット
Staddress に関する公式リンク一覧です。