IEX Finance API

A Ruby client for the The IEX Cloud API.

Table of Contents

• Installation
• Usage
  • Get an API Token
  • Configure
  • Get a Single Price
  • Get a Quote
  • Get a OHLC (Open, High, Low, Close) price
  • Get a Market OHLC (Open, High, Low, Close) prices
  • Get Historical Prices
  • Get Company Information
  • Get a Company Logo
  • Get Recent News
  • Get Chart
  • Get Key Stats
  • Get Advanced Stats
  • Get Dividends
  • Get Earnings
  • Get Income Statement
  • Get Balance Sheet
  • Get Cash Flow Statement
  • Get Sector Performance
  • Get Largest Trades
  • Get a Quote for Crypto Currencies
  • ISIN Mapping
  • Get Symbols
  • Get Symbols for an Exchange
  • Get Symbols for a Region
  • Get Latest Foreign Exchange Rates
  • Get List
  • Other Requests
• Configuration
  • Logging
• Sandbox Environment
• Errors
  • SymbolNotFound
  • PermissionDeniedError
  • ClientError
• Contributing
• Copyright and License

Installation

Add to Gemfile.

gem 'iex-ruby-client'

Run bundle install.

Usage

Get an API Token

Create an account on IEX Cloud and get a publishable token from the IEX cloud console.

Configure

IEX::Api.configure do |config|
  config.publishable_token = 'publishable_token' # defaults to ENV['IEX_API_PUBLISHABLE_TOKEN']
  config.secret_token = 'secret_token' # defaults to ENV['IEX_API_SECRET_TOKEN']
  config.endpoint = 'https://cloud.iexapis.com/v1' # use 'https://sandbox.iexapis.com/v1' for Sandbox
end

You can also configure an instance of a client directly.

client = IEX::Api::Client.new(
  publishable_token: 'publishable_token',
  secret_token: 'secret_token',
  endpoint: 'https://cloud.iexapis.com/v1'
)

Get a Single Price

Fetches a single number, being the IEX real time price, the 15 minute delayed market price, or the previous close price.

client.price('MSFT') # 93.78

See #price for detailed documentation.

Get a Quote

Fetches a single stock quote.

quote = client.quote('MSFT')

quote.latest_price # 90.165
quote.change # 0.375
quote.change_percent # 0.00418
quote.change_percent_s # '+0.42%'

See #quote for detailed documentation or quote.rb for returned fields.

Get a OHLC (Open, High, Low, Close) price

Fetches a single stock OHLC price. Open and Close prices contain timestamp.

ohlc = client.ohlc('MSFT')

ohlc.close.price # 90.165
ohlc.close.time #
ohlc.open.price # 0.375
ohlc.open.time
ohlc.high # 0.00418
ohlc.low # '+0.42%'

Get a Market OHLC (Open, High, Low, Close) prices

Fetches a hash market OHLC prices.

market = client.market
market['SPY'].close.price # 278.56
market['SPY'].close.time # 2018-06-11 23:00:00 +0300
market['SPY'].open.price # 279.05
market['SPY'].open.time # 2018-06-12 16:30:00 +0300
market['SPY'].high #
market['SPY'].low #

Get Historical Prices

Fetches a list of historical prices.

There are currently a few limitations of this endpoint compared to the official IEX one.

Options for range include: max, ytd, 5y, 2y, 1y, 6m, 3m, 1m, 5d, date

NOTE: If you use the date value for the range parameter:

• The options must include a date entry, {date: ...}
• The date value must be either a Date object, or a string formatted as YYYYMMDD. Anything else will result in an IEX::Errors::ClientError.
• The options must include chartByDay: 'true' or an ArgumentError will be raised.
• See below for examples.

Query params supported include: chartByDay

This is a complicated endpoint as there is a lot of granularity over the time period of data returned. See below for a variety of ways to request data, NOTE: this is NOT as exhaustive list.

historical_prices = client.historical_prices('MSFT') # One month of data
historical_prices = client.historical_prices('MSFT', {range: 'max'}) # All data up to 15 years
historical_prices = client.historical_prices('MSFT', {range: 'ytd'}) # Year to date data
historical_prices = client.historical_prices('MSFT', {range: '5y'}) # 5 years of data
historical_prices = client.historical_prices('MSFT', {range: '6m'}) # 6 months of data
historical_prices = client.historical_prices('MSFT', {range: '5d'}) # 5 days of data
historical_prices = client.historical_prices('MSFT', {range: 'date', date: '20200930', chartByDay: 'true'}) # One day of data
historical_prices = client.historical_prices('MSFT', {range: 'date', date: Date.parse('2020-09-30'), chartByDay: 'true'}) # One day of data
...

Once you have the data over the preferred time period, you can access the following fields

historical_prices = client.historical_prices('MSFT') # One month of data

historical_price = historical_prices.first
historical_price.date # 2020-10-07
historical_price.open #207.06
historical_price.open_dollar # '$207.06'
historical_price.close # 209.83
historical_price.close_dollar # '$209.83'
historical_price.high # 210.11
historical_price.high_dollar # '$210.11'
historical_price.low # 206.72
historical_price.low_dollar # '$206.72'
historical_price.volume # 25681054
...

There are a lot of options here so I would recommend viewing the official IEX documentation #historical-prices or historical_prices.rb for returned fields.

Get Company Information

Fetches company information for a symbol.

company = client.company('MSFT')

company.ceo # 'Satya Nadella'
company.company_name # 'Microsoft Corporation'

See #company for detailed documentation or company.rb for returned fields.

Get a Company Logo

Fetches company logo for a symbol.

logo = client.logo('MSFT')

logo.url # 'https://storage.googleapis.com/iex/api/logos/MSFT.png'

See #logo for detailed documentation or logo.rb for returned fields.

Get Recent News

Fetches news for a symbol.

news = client.news('MSFT')

news.size # 10

latest = news.first
latest.headline # 'Smartsheet files for $100M IPO with growing losses'
latest.url # 'https://...'

Retrieve a range between 1 and 50.

news = client.news('MSFT', 5)

See #news for detailed documentation or news.rb for returned fields.

Get Chart

Fetches charts for a symbol.

chart = client.chart('MSFT')

chart.size # 38510

first = chart.first
first.label # '9:30 AM'
first.high # 94.97

You can specify a chart range and additional options.

client.chart('MSFT', 'dynamic') # 1d or 1m data depending on the day or week and time of day
client.chart('MSFT', Date.new(2018, 3, 26)) # a specific date
client.chart('MSFT', '1d', chart_interval: 10) # every n-th data point

Note that calling the chart API weighs more than 1 IEX message (you pay more than 1 call).

# 1 message per minute capped at 50 messages to intraday_prices
client.chart('MSFT', '1d')

# 2x22 trading days = 44 messages to historical_close_prices
client.chart('MSFT', '1m', chart_close_only: true)

# 2x251 trading days = 502 messages to historical_close_prices
client.chart('MSFT', '1y', chart_close_only: true)

Get Key Stats

Fetches company's key stats for a symbol.

key_stats = client.key_stats('MSFT')

key_stats.week_52_change_dollar # "$0.37"
key_stats.week_52_high # 136.04
key_stats.week_52_high_dollar # "$136.04"
key_stats.week_52_low # 95.92,
key_stats.week_52_low_dollar # "$95.92"
key_stats.market_cap # 990869169557
key_stats.market_cap_dollar # "$990,869,169,557"
key_stats.employees # 133074
key_stats.day_200_moving_avg # 112.43
key_stats.day_50_moving_avg # 121
key_stats.float # 7694414092
key_stats.avg_10_volume # 25160156.2
key_stats.avg_30_volume # 23123700.13
key_stats.ttm_eps # 4.66
key_stats.ttm_dividend_rate # 1.8
key_stats.company_name # "Microsoft Corp."
key_stats.shares_outstanding # 7849945172
key_stats.max_change_percent # 4.355607
key_stats.year_5_change_percent # 2.32987
key_stats.year_5_change_percent_s # "+232.99%"
key_stats.year_2_change_percent # 0.84983
key_stats.year_2_change_percent_s # "+84.98%"
key_stats.year_1_change_percent # 0.383503
key_stats.year_1_change_percent_s # "+38.35%"
key_stats.ytd_change_percent # 0.270151
key_stats.ytd_change_percent_s # "+27.02%"
key_stats.month_6_change_percent # 0.208977
key_stats.month_6_change_percent_s # "+20.90%"
key_stats.month_3_change_percent # 0.212188
key_stats.month_3_change_percent_s # "+21.22%"
key_stats.month_1_change_percent # 0.076335
key_stats.mont