Class: Staddress::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/staddress/client.rb

Overview

Staddress AI API クライアント（同期）。

例:

client = Staddress::Client.new(api_key: "sk_xxx")
result = client.parse_address(input: "六本木ヒルズ 森タワー 52F")
puts result.normalized

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String, nil) (defaults to: nil) —

    省略時は環境変数 STADDRESS_API_KEY

  • base_url (String, nil) (defaults to: nil) —

    省略時は STADDRESS_BASE_URL または既定値

  • timeout (Numeric) (defaults to: DEFAULT_TIMEOUT) —

    接続・読み取りタイムアウト（秒）



25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/staddress/client.rb', line 25

def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT)
  @api_key = api_key || ENV.fetch("STADDRESS_API_KEY", nil)
  if @api_key.nil? || @api_key.empty?
    raise Error.new(
      "API キーが設定されていません。api_key 引数または環境変数 STADDRESS_API_KEY を指定してください。",
      code: "unauthorized",
      http_status: 0
    )
  end

  base = base_url || ENV.fetch("STADDRESS_BASE_URL", nil) || DEFAULT_BASE_URL
  @base_url = base.sub(%r{/+\z}, "")
  @timeout = timeout
end

Instance Method Details

#get_usage ⇒ Staddress::Models::UsageResponse

利用状況取得 (GET /api/v1/usage)。

Returns:



76
77
78
79
 
# File 'lib/staddress/client.rb', line 76

def get_usage
  data = request("GET", "/api/v1/usage", nil)
  Models::UsageResponse.from(data)
end

#parse_address(input:, postal_code: nil) ⇒ Staddress::Models::ParseResult

単件住所解析 (POST /api/v1/addresses/parse)。

Returns:



42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/staddress/client.rb', line 42

def parse_address(input:, postal_code: nil)
  if input.nil? || input.empty?
    raise Error.new("input は必須です。", code: "invalid_request", http_status: 0)
  end

  body = { "input" => input }
  body["postalCode"] = postal_code if postal_code && !postal_code.empty?

  data = request("POST", "/api/v1/addresses/parse", body)
  Models::ParseResult.from(data["result"]) || Models::ParseResult.from({})
end

#parse_batch(items) ⇒ Array<Staddress::Models::BatchItemResult>

一括住所解析 (POST /api/v1/addresses/parse/batch)。Standard プラン以上、最大 100 件。

Parameters:

  • items (Array<Hash>) —

    例: [{ id: "1", address: "東京都..." }]

Returns:



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/staddress/client.rb', line 57

def parse_batch(items)
  list = items.to_a
  if list.empty?
    raise Error.new("items には1件以上を指定してください。", code: "invalid_request", http_status: 0)
  end
  if list.size > MAX_BATCH_ITEMS
    raise Error.new(
      "items は最大 #{MAX_BATCH_ITEMS} 件です（現在: #{list.size} 件）。",
      code: "batch_size_exceeded",
      http_status: 0
    )
  end

  data = request("POST", "/api/v1/addresses/parse/batch", { "items" => list })
  (data["results"] || []).map { |item| Models::BatchItemResult.from(item) }
end