15分で試せる — Staddress APIをcurlで呼び出す

Last updated at 2026-07-11Posted at 2026-07-11

15分で試せる — Staddress APIをcurlで呼び出す（Token取得・usage・単件解析）

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

前回（無料で試せる — Staddress AIで住所解析の精度を確認する）は、Free アカウント登録から公式サイト上での精度確認までを紹介しました。

今回は一歩進んで、取得した API Token を使い、ターミナルから Staddress API を curl で呼び出す ところまで試します。

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

アカウント管理画面で API Token を確認する
staddress-tools の curl サンプルを clone する
usage API で利用状況を確認する
単件解析 API で住所を1件解析する
レスポンスの normalized と components を確認する

前提

Free アカウント登録が完了していること
アカウント管理画面で API Token を確認できること
macOS / Linux / WSL などで git と curl が使えること
JSON を見やすく表示するため、jq の利用を推奨

# macOS（Homebrew）
brew install jq

今回使うサンプルコードはこちらです。

StaddressAI/staddress-tools — examples/curl

Step 1. API Token を確認する

Staddress のアカウント管理画面を開き、API キー（Token）を確認します。

API Token は、API 呼び出し時に X-Api-Key ヘッダへ設定します。

X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxx

画面下部の エンドポイント 欄で、API Key（コピーボタンで取得）と API ドメイン（https://api.staddress.com）を確認できます。

Step 2. curl サンプルを clone する

Staddress では、すぐ試せる curl サンプルを GitHub で公開しています。

git clone https://github.com/StaddressAI/staddress-tools.git
cd staddress-tools/examples/curl
chmod +x staddress.sh

中身は次のような構成です。

examples/curl/
├── README.md
├── _common.sh
├── batch-sample.json
└── staddress.sh

今回使うのは staddress.sh です。

このスクリプトには、以下の3機能がまとまっています。

操作	コマンド	API
利用状況確認	`./staddress.sh -u`	`GET /api/v1/usage`
単件解析	`./staddress.sh -s "住所"`	`POST /api/v1/addresses/parse`
一括解析	`./staddress.sh -b batch-sample.json`	`POST /api/v1/addresses/parse/batch`

この記事では 利用状況確認 と 単件解析 を試します。

Step 3. 接続先と API Token を設定する

設定方法は3つあります。

コマンドライン引数で指定する
環境変数で指定する
.env に保存する

最初は、コマンドライン引数で指定するのが分かりやすいです。

./staddress.sh \
  --server https://api.staddress.com \
  --key sk_xxxxxxxxxxxxxxxxxxxx \
  -u

ただし、毎回 --key を入力するのは面倒なので、ローカルでは環境変数を使うのがおすすめです。

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

この状態で、以降は短いコマンドで実行できます。

./staddress.sh -u

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

まずは API Token が正しく使えるか、利用状況 API で確認します。

./staddress.sh -u

または:

./staddress.sh --usage

成功すると、アカウント情報と利用状況が JSON で返ります。

{
  "account": {
    "plan": "free",
    "planDisplayName": "Freeプラン"
  },
  "usage": {
    "monthly": {
      "limit": 100,
      "used": 0,
      "remaining": 100
    }
  }
}

Free プランでは、月間の解析上限が表示されます。

Step 5. 単件解析を実行する

次に、住所を1件解析してみます。

./staddress.sh -s "六本木ヒルズ 森タワー 52F"

郵便番号が分かっている場合は、第2引数に渡せます。

./staddress.sh --single "東京都渋谷区道玄坂1-2 マンション桜 101号" "150-0043"

内部的には、次の API を呼び出しています。

POST /api/v1/addresses/parse
X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

リクエストボディは次のような形です。

{
  "input": "六本木ヒルズ 森タワー 52F"
}

レスポンスでは、第3回の精度確認画面と同じ観点の情報が JSON で返ります。主なフィールドは次のとおりです。

{
  "requestId": "req_xxxxxxxx",
  "result": {
    "normalized": "東京都港区六本木6-10-1 六本木ヒルズ森タワー 52F",
    "standard": "東京都港区六本木六丁目10-1 六本木ヒルズ森タワー 52F",
    "components": {
      "pref": "東京都",
      "prefCode": "13",
      "city": "港区",
      "cityCode": "13103",
      "oazaCho": "六本木",
      "chomeKoaza": "6丁目",
      "streetNumberBlock": "10-1",
      "buildingName": "六本木ヒルズ森タワー",
      "roomNumber": "52",
      "roomNumberUnit": "F",
      "lat": 35.6604,
      "lon": 139.7293,
      "lgCode": "131030",
      "machiazaId": "0014001"
    },
    "confidence": {
      "score": 1.0,
      "matchLevel": "parcel",
      "query": "東京都港区六本木6-10-1"
    }
  }
}

※ v1 API では components に postalCode は含まれません。取得できた項目のみが返ります。

レスポンスで見るべきポイント

第3回の精度確認画面と同じ流れで、JSON のどこを見るか整理します。
最初は次の 5つを確認すると分かりやすいです。

観点	主なフィールド	用途の例
正規化された住所	`normalized` / `standard`	画面表示・DB保存
住所要素への分解	`components`	名寄せ・配送先チェック
座標情報	`lat` / `lon`	地図表示・距離計算
行政コード・ID	`prefCode` / `cityCode` / `lgCode` / `machiazaId`	基幹連携・自治体データ照合
評価結果	`confidence.score` / `confidence.matchLevel`	解析結果をそのまま使ってよいかの目安

1. 正規化された住所

入力した表記ゆれ・欠落を吸収した、業務で扱いやすい1行住所です。

フィールド	説明
`result.normalized`	標準化された住所1行（丁目は半角数字寄り）
`result.standard`	丁目を漢数字表記とした1行（取得できない場合は `normalized` と同値になることがあります）

"normalized": "東京都港区六本木6-10-1 六本木ヒルズ森タワー 52F"

画面表示やマスタ保存では、まずこの1行を確認します。

2. 住所要素への分解（`components`）

住所を構造化した結果です。CRM の名寄せや配送先チェックでは、この分解結果が重要になります。

行政区分

フィールド	説明	例
`pref`	都道府県	東京都
`city`	市区町村	港区
`oazaCho`	大字・町名	六本木
`chomeKoaza`	丁目・小字	6丁目

住所詳細

フィールド	説明	例
`streetNumberBlock`	街区符号／住居番号／地番	10-1
`buildingName`	建物名	六本木ヒルズ森タワー
`roomNumber` / `roomNumberUnit`	部屋番号と単位	52 / F

表記ゆれのある入力（建物名だけ、フロアだけ、カタカナ混在など）でも、可能な範囲でこの粒度まで分解されます。

3. 座標情報（`lat` / `lon`）

緯度・経度です。地図へのプロットや距離計算に使います。

"lat": 35.6604,
"lon": 139.7293

Staddress AI では、デジタル庁のアドレス・ベース・レジストリ（公的住所DB）と Google Maps API を組み合わせて座標を付与します。
曖昧な住所や新築建物など、AI が必要と判断した場合は Google Maps 側の情報も参照されます。

4. 行政コード・ID

基幹システムや自治体データとの連携に使うコードです。いずれもアドレス・ベース・レジストリ由来の情報です。

フィールド	説明	例
`prefCode`	都道府県コード（2桁）	13
`cityCode`	市区町村コード（5桁）	13103
`lgCode`	全国地方公共団体コード（6桁・JIS準拠）	131030
`machiazaId`	町字ID	0014001

5. 評価結果（`confidence`）

入力がどの程度「公的データと一致したか」を示す指標です。
デジタル庁の住所ベースレジストリ（ABR-Geocoder）の仕様に準拠しており、自社独自のスコアではありません。

フィールド	説明
`confidence.score`	入力と正規化結果の文字列類似度（0〜1）。1に近いほど表記が一致
`confidence.matchLevel`	住所のどの階層までマッチしたか
`confidence.query`	上記を算出した照合クエリ（住所更新チェック等に利用）

評価スコア（score）の目安

1.0 … 町字・番地・号まで、レジストリと文字列が完全一致
0.9 以下 … 表記ゆれの正規化（1-1 → 1番1号）、字の補完、誤字修正などが入った。レーベンシュタイン距離（編集距離）で算出

マッチレベル（matchLevel）の目安

値	意味（粗い → 細かい）
`prefecture`	都道府県まで
`city`	市区町村まで
`machiaza`	大字・町まで
`machiaza_detail`	丁目・小字まで
`residential_block`	街区符号まで
`residential_detail`	住居番号まで
`parcel`	地番まで
`unknown`	照合できず

score だけで判断せず、matchLevel とセットで見てください。
例えば score が高くても matchLevel が city 止まりなら、番地までは特定できていない可能性があります。配送先としてそのまま使えるか、担当者に確認が必要か、といった用途に応じて、許容する matchLevel の下限を決めるのがおすすめです。

詳細はデジタル庁ジオコーダー（住所ベースレジストリ）公式仕様を参照してください。

補足: `requestId`

サポート問い合わせやログ追跡用の ID です。「この住所の解析結果を確認したい」ときに使います。

"requestId": "req_xxxxxxxx"

よくあるつまづき

`401 unauthorized` が返る

API Token が未設定、または誤っている可能性があります。

echo "$STADDRESS_API_KEY"

Token が表示されない場合は、もう一度環境変数を設定してください。

`jq が必要です` と出る

単件解析では JSON の生成・整形に jq を使います。

brew install jq

`STADDRESS_BASE_URL` を毎回聞かれる

環境変数が設定されていない状態です。

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

入力できる住所が長すぎる

単件解析の input は最大100文字です。会社名・部署名・宛名などが混ざっている場合は、住所欄と宛名欄を分ける設計をおすすめします。

まとめ

今回は、API Token を使って curl から Staddress API を呼び出す手順を紹介しました。

認証は X-Api-Key ヘッダで行う
staddress-tools の examples/curl/staddress.sh を使うと、usage と単件解析をすぐ試せる
単件解析では normalized → components → lat/lon → 行政コード → confidence の順に見ると分かりやすい
confidence.score と matchLevel はセットで見て、用途に足りる粒度まで特定できているか確認する
API Token は秘密情報として扱い、画面共有・記事・GitHub には載せない

次回は、EC・物流SaaS向けに、配送先住所をどのタイミングで正規化するかを実装パターンとして整理します。

Staddress ホームセット

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

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up