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

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

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

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

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

staddress gem をインストールする
Staddress::Client を初期化する
parse_address で単件解析する
get_usage で利用状況を確認する
Staddress::Error でエラーを扱う
（任意）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 に関する公式リンク一覧です。