Class: SecApi::Mapping

Inherits:
Object
  • Object
show all
Defined in:
lib/sec_api/mapping.rb

Overview

Mapping proxy for entity resolution endpoints

All mapping methods return immutable Entity objects (not raw hashes). This ensures thread safety and a consistent API surface.

Examples:

Ticker to CIK resolution

entity = client.mapping.ticker("AAPL")
entity.cik      # => "0000320193"
entity.ticker   # => "AAPL"
entity.name     # => "Apple Inc."

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ SecApi::Mapping

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

Creates a new Mapping proxy instance.

Mapping instances are obtained via Client#mapping and cached for reuse. Direct instantiation is not recommended.

Parameters:



23
24
25
 
# File 'lib/sec_api/mapping.rb', line 23

def initialize(client)
  @_client = client
end

Instance Method Details

#cik(cik) ⇒ Entity

Resolve CIK number to company entity

CIK identifiers are normalized to 10 digits with leading zeros before making the API request. This allows flexible input formats:

  • “320193” -> “0000320193”

  • “00320193” -> “0000320193”

  • 320193 (integer) -> “0000320193”

Examples:

CIK without leading zeros

entity = client.mapping.cik("320193")
entity.cik    # => "0000320193"
entity.ticker # => "AAPL"

Parameters:

  • cik (String, Integer) —

    The CIK number (e.g., “0000320193”, “320193”, 320193)

Returns:

  • (Entity) —

    Immutable entity object with CIK, ticker, name, etc.

Raises:



60
61
62
63
64
65
 
# File 'lib/sec_api/mapping.rb', line 60

def cik(cik)
  validate_identifier!(cik, "CIK")
  normalized = normalize_cik(cik)
  response = @_client.connection.get("/mapping/cik/#{encode_path(normalized)}")
  Objects::Entity.from_api(response.body)
end

#cusip(cusip) ⇒ Entity

Resolve CUSIP identifier to company entity

Parameters:

  • cusip (String) —

    The CUSIP identifier (e.g., “037833100”)

Returns:

  • (Entity) —

    Immutable entity object with CIK, ticker, name, etc.

Raises:



75
76
77
78
79
 
# File 'lib/sec_api/mapping.rb', line 75

def cusip(cusip)
  validate_identifier!(cusip, "CUSIP")
  response = @_client.connection.get("/mapping/cusip/#{encode_path(cusip)}")
  Objects::Entity.from_api(response.body)
end

#name(name) ⇒ Entity

Resolve company name to entity

Parameters:

  • name (String) —

    The company name or partial name (e.g., “Apple”)

Returns:

  • (Entity) —

    Immutable entity object with CIK, ticker, name, etc.

Raises:



89
90
91
92
93
 
# File 'lib/sec_api/mapping.rb', line 89

def name(name)
  validate_identifier!(name, "name")
  response = @_client.connection.get("/mapping/name/#{encode_path(name)}")
  Objects::Entity.from_api(response.body)
end

#ticker(ticker) ⇒ Entity

Resolve ticker symbol to company entity

Parameters:

  • ticker (String) —

    The stock ticker symbol (e.g., “AAPL”, “BRK.A”)

Returns:

  • (Entity) —

    Immutable entity object with CIK, ticker, name, etc.

Raises:



35
36
37
38
39
 
# File 'lib/sec_api/mapping.rb', line 35

def ticker(ticker)
  validate_identifier!(ticker, "ticker")
  response = @_client.connection.get("/mapping/ticker/#{encode_path(ticker)}")
  Objects::Entity.from_api(response.body)
end