Class: OpenfigiRuby::Client

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

Overview

HTTP client for the OpenFIGI V3 API.

Instantiate with an optional API key override, or configure globally via configure and call +Client.new+ with no arguments.

Constant Summary collapse

MAPPING_VALUE_KEYS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Valid field names accepted by #mapping_values.

%w[idType exchCode micCode currency marketSecDes securityType securityType2].freeze

Instance Method Summary collapse

Constructor Details

#initialize(api_key: OpenfigiRuby.configuration.api_key, open_timeout: OpenfigiRuby.configuration.open_timeout, read_timeout: OpenfigiRuby.configuration.read_timeout) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String, nil) (defaults to: OpenfigiRuby.configuration.api_key) —

    overrides the globally configured key

  • open_timeout (Integer) (defaults to: OpenfigiRuby.configuration.open_timeout) —

    seconds before the connection times out

  • read_timeout (Integer) (defaults to: OpenfigiRuby.configuration.read_timeout) —

    seconds before the read times out



20
21
22
23
24
25
26
27
28
 
# File 'lib/openfigi_ruby/client.rb', line 20

def initialize(
  api_key: OpenfigiRuby.configuration.api_key,
  open_timeout: OpenfigiRuby.configuration.open_timeout,
  read_timeout: OpenfigiRuby.configuration.read_timeout
)
  @api_key = api_key
  @open_timeout = open_timeout
  @read_timeout = read_timeout
end

Instance Method Details

#filter(query: nil, start: nil, **filters) ⇒ FilterResult

Filters FIGIs with alphabetical ordering and a total count (POST /v3/filter).

Parameters:

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

    optional search terms

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

    pagination token from a previous FilterResult#next_page

  • filters (Hash) —

    optional snake_case filter keys

Returns:



90
91
92
93
94
95
96
97
 
# File 'lib/openfigi_ruby/client.rb', line 90

def filter(query: nil, start: nil, **filters)
  body = {}
  body["query"] = query if query
  body["start"] = start if start
  body.merge!(serialize(filters))
  response = post("/filter", body)
  parse_filter_result(response)
end

#mapping(jobs) ⇒ Array<MappingResult>

Maps third-party identifiers to FIGIs (POST /v3/mapping).

Examples:

client.mapping([
  { id_type: "ID_ISIN", id_value: "US4592001014" },
  { id_type: "TICKER", id_value: "AAPL", exch_code: "US" }
])

Parameters:

  • jobs (Array<Hash>) —

    each hash must include +:id_type+ and +:id_value+. Optional keys: +:exch_code+, +:mic_code+, +:currency+, +:market_sec_des+, +:security_type+, +:security_type2+, +:include_unlisted_equities+, +:option_type+, +:strike+, +:contract_size+, +:coupon+, +:expiration+, +:maturity+, +:state_code+.

Returns:



44
45
46
47
48
 
# File 'lib/openfigi_ruby/client.rb', line 44

def mapping(jobs)
  body = jobs.map { |job| serialize(job) }
  response = post("/mapping", body)
  response.map { |item| parse_mapping_result(item) }
end

#mapping_values(key) ⇒ Array<String>

Returns the set of valid values for a filterable field (GET /v3/mapping/values/:key).

Examples:

client.mapping_values(:id_type)

Parameters:

  • key (String, Symbol) —

    snake_case or camelCase field name. Valid values: :id_type, :exch_code, :mic_code, :currency, :market_sec_des, :security_type, :security_type2

Returns:

  • (Array<String>) 


59
60
61
62
63
 
# File 'lib/openfigi_ruby/client.rb', line 59

def mapping_values(key)
  api_key = camelize(key.to_s)
  response = get("/mapping/values/#{api_key}")
  response["values"]
end

#search(query:, start: nil, **filters) ⇒ SearchResult

Searches for FIGIs by keyword (POST /v3/search).

Examples:

result = client.search(query: "Apple", exch_code: "US")
result.data   #=> [#<struct OpenfigiRuby::FigiResult ...>, ...]
result.next_page  #=> "BBG..." or nil

Parameters:

  • query (String) —

    search terms

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

    pagination token from a previous SearchResult#next_page

  • filters (Hash) —

    optional snake_case filter keys (same as mapping job filters)

Returns:



76
77
78
79
80
81
82
 
# File 'lib/openfigi_ruby/client.rb', line 76

def search(query:, start: nil, **filters)
  body = { "query" => query }
  body["start"] = start if start
  body.merge!(serialize(filters))
  response = post("/search", body)
  parse_search_result(response)
end