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

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

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

前回（Pythonから15分 — Staddress で住所解析する）は、公式 Python SDK を紹介しました。

今回は、公式 Ruby Gem Staddress を使い、Rails やバッチスクリプトから住所解析を呼び出します。

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

1. staddress gem をインストールする
2. Staddress::Client を初期化する
3. parse_address で単件解析する
4. get_usage で利用状況を確認する
5. Staddress::Error でエラーを扱う
6. （任意）parse_batch で一括解析する

---

前提

• Free アカウント登録が完了していること
• アカウント管理画面で API Key を確認できること
• Ruby 3.1+
• gem / Bundler のいずれか

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

• RubyGems: staddress
• ソース: StaddressAI/staddress-tools — packages/ruby

特徴:

• HTTP は標準ライブラリ net/http（ランタイム依存なし）
• Ruby 3.1+
• レスポンスは snake_case アクセサ（未知フィールドは #raw から参照可）

バージョン確認:

ruby -v   # 3.1 以上であること

---

Step 1. インストールする

gem install staddress

Bundler を使う場合は Gemfile に追加します。

# Gemfile
gem "staddress"

bundle install

インストール確認:

gem list staddress

---

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

require "staddress"

client = Staddress::Client.new(
  api_key: "sk_xxxxxxxxxxxxxxxxxxxx",  # 省略時は環境変数 STADDRESS_API_KEY
  base_url: "https://api.staddress.com",  # 省略時は既定値（STADDRESS_BASE_URL も可）
  timeout: 30  # 任意（秒）
)

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

export STADDRESS_API_KEY="sk_xxxxxxxxxxxxxxxxxxxx"

# 環境変数があれば引数なしでも OK
client = Staddress::Client.new

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

---

Step 3. parse_address で単件解析する

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

puts result.normalized
puts result.components.pref
puts result.confidence.match_level

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

---

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

usage = client.get_usage
puts "#{usage.plan} / #{usage.account_name}"
p usage

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

---

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

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

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

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

本番では request_id をログに残すと、問い合わせ時に追跡しやすくなります。

---

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

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

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

results.each do |item|
  puts "#{item.id}: #{item.result&.normalized || item.error}"
end

---

最小の動くサンプル

demo.rb にまとめた例です。

#!/usr/bin/env ruby
require "staddress"

begin
  client = Staddress::Client.new

  usage = client.get_usage
  puts "plan: #{usage.plan}"

  result = client.parse_address(input: "六本木ヒルズ 森タワー 52F")
  puts "normalized: #{result.normalized}"
  puts "pref: #{result.components.pref}"
  puts "match_level: #{result.confidence.match_level}"
rescue Staddress::Error => err
  warn "[#{err.code}] #{err.message} request_id=#{err.request_id}"
  exit 1
end

export STADDRESS_API_KEY="sk_xxxxxxxxxxxxxxxxxxxx"
ruby demo.rb

---

Node / Python / Ruby の使い分け

観点	Node / Python	Ruby（今回）
配布	npm / PyPI	RubyGems: staddress
主な用途	Node アプリ / データ処理・FastAPI	Rails・Sidekiq・バッチ
HTTP	fetch / httpx	標準 net/http（依存ゼロ）
エラー	StaddressError	Staddress::Error

Rails や既存の Ruby バッチに載せるなら今回の gem、データ分析寄りなら Python 編、Node バックエンドなら Node 編 が向いています。

---

よくあるつまづき

unauthorized / API Key 未設定

echo "$STADDRESS_API_KEY"

空なら export し直すか、Staddress::Client.new(api_key: "...") を渡してください。

Ruby バージョンが古い

SDK は Ruby 3.1+ が必要です。

ruby -v

quota_exceeded

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

Bundler 配下で require できない

Gemfile に gem "staddress" を追加したうえで bundle exec ruby demo.rb を使ってください。

---

まとめ

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

• gem install staddress ですぐ使える（RubyGems）
• ランタイム依存なし（標準の net/http）
• parse_address / get_usage / parse_batch で主要 API をカバー
• Staddress::Error で code・HTTP ステータス・request_id を扱える
• API Key は環境変数で渡し、リポジトリに載せない
• レスポンスの見方は curl 編 と同じ

---

Staddress ホームセット

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

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