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 anIEX::Errors::ClientError
. - The options must include
chartByDay: 'true'
or anArgumentError
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.month_1_change_percent_s # "+7.63%"
key_stats.day_30_change_percent # 0.089589
key_stats.day_30_change_percent_s # "+8.96%"
key_stats.day_5_change_percent # -0.010013
key_stats.day_5_change_percent_s # "-1.00%"
key_stats.next_dividend_date # "2019-05-21"
key_stats.dividend_yield # 0.014087248841960684
key_stats.next_earnings_date # "2019-07-29"
key_stats.ex_dividend_date # "2019-05-24"
key_stats.pe_ratio # 29.47
key_stats.beta # 1.4135449089973444
You can also fetch a single stat for a symbol. Note that IEX uses lowerCamelCase
for the names of the stats.
client.key_stat('VTI', 'dividendYield') # 0.01271760965303361
See #key-stats for detailed documentation or key_stats.rb for returned fields.
Get Advanced Stats
Fetches company's advanced stats for a symbol, this will include all key stats as well.
advanced_stats = client.advanced_stats('MSFT')
advanced_stats.total_cash # 66301000000
advanced_stats.total_cash_dollars # "$66,301,000,000"
advanced_stats.current_debt # 20748000000
advanced_stats.current_debt_dollars # "$2,074,8000,000"
advanced_stats.revenue # 265809000000
advanced_stats.revenue_dollars # "$265,809,000,000"
advanced_stats.gross_profit # 101983000000
advanced_stats.gross_profit_dollar # "$101,983,000,000"
advanced_stats.total_revenue # 265809000000
advanced_stats.total_revenue_dollar # "$265,809,000,000"
advanced_stats.ebitda # 80342000000
advanced_stats.ebitda_dollar # "$80,342,000,000"
advanced_stats.revenue_per_share # 0.02
advanced_stats.revenue_per_share_dollar # "$0.02"
advanced_stats.revenue_per_employee # 2013704.55
advanced_stats.revenue_per_employee_dollar # "$2,013,704.55"
advanced_stats.debt_to_equity # 1.07
advanced_stats.profit_margin # 22.396157
advanced_stats.enterprise_value # 1022460690000
advanced_stats.enterprise_value_dollar # "$1,022,460,690,000"
advanced_stats.enterprise_value_to_revenue # 3.85
advanced_stats.price_to_sales # 3.49
advanced_stats.price_to_sales_dollar # "$3.49"
advanced_stats.price_to_book # 8.805916432564608
advanced_stats.forward_pe_ratio # 18.14
advanced_stats.pe_high # 22.61
advanced_stats.pe_low # 11.98
advanced_stats.peg_ratio # 2.19
advanced_stats.week_52_high_date # "2019-11-19"
advanced_stats.week_52_low_date # "2019-01-03
advanced_stats.beta # 1.4661365583766115
advanced_stats.put_call_ratio # 0.6780362005229779
...
See #advanced-stats for detailed documentation or advanced_stats.rb for returned fields.
Get Dividends
Fetches dividends for a symbol.
dividends = client.dividends('MSFT', '6m') # Options are: 5y, 2y, 1y, ytd, 6m, 3m, 1m
dividends.payment_date # '2018-03-08'
dividends.record_date # '2018-02-15'
dividends.declared_date # '2017-11-29'
dividends.amount # 0.42
See #dividends for detailed documentation or dividends.rb for returned fields.
Get Earnings
Fetches earnings for a symbol.
earnings = client.earnings('MSFT')
earnings.actual_eps # 1.13
earnings.consensus_eps # 1.07
earnings.announce_time # 'AMC'
earnings.number_of_estimates # 14
earnings.eps_surprise_dollar # 0.06
earnings.eps_report_date # '2018-07-19'
earnings.fiscal_period # 'Q4 2018'
earnings.fiscal_end_date # '2018-06-30'
earnings.year_ago # 0.98
earnings.year_ago_change_percent # 0.15306122448979584
earnings.year_ago_change_percent_s # '+15.31%'
See #earnings for detailed documentation or earnings.rb for returned fields.
Get Income Statement
Fetches income statements for a symbol.
income_statements = client.income('MSFT')
# Multiple income statements are returned with 1 API call.
income = income_statements.first
income.report_date # '2019-03-31'
income.fiscal_date # '2019-03-31'
income.currency # 'USD'
income.total_revenue # 30_505_000_000
income.total_revenue_dollar # '$30,505,000,000'
income.cost_of_revenue # 10_170_000_000
income.cost_of_revenue_dollar # '$10,170,000,000'
income.gross_profit # 20_335_000_000
income.gross_profit_dollar # '$20,335,000,000'
...
See #income-statement for detailed documentation or income.rb for returned fields.
Get Balance Sheet
Fetches balance sheets for a symbol.
balance_sheets = client.balance_sheet('MSFT')
# Multiple balance sheets are returned with 1 API call.
balance_sheet = balance_sheets.first
balance_sheet.report_date # '2017-03-31'
balance_sheet.fiscal_date # '2017-03-31'
balance_sheet.currency # 'USD'
balance_sheet.current_cash # 25_913_000_000
balance_sheet.current_cash_dollar # '$25,913,000,000'
balance_sheet.short_term_investments # 40_388_000_000
balance_sheet.short_term_investments_dollar # '$40,388,000,000'
...
See #balance-sheet for detailed documentation or balance_sheet.rb for returned fields.
Get Cash Flow Statement
Fetches cash flow statements for a symbol.
cash_flow_statements = client.cash_flow('MSFT')
# Multiple cash flow statements are returned with 1 API call.
cash_flow = cash_flow_statements.first
cash_flow.report_date # '2018-09-30'
cash_flow.fiscal_date # '2018-09-30'
cash_flow.currency # 'USD'
cash_flow.net_income # 14_125_000_000
cash_flow.net_income_dollar # '$14,125,000,000'
cash_flow.depreciation # 2_754_000_000
cash_flow.depreciation_dollar # '$2,754,000,000'
...
See #cash-flow for detailed documentation or cash_flow.rb for returned fields.
Get Sector Performance
Fetches latest sector's performance.
sectors = client.sectors('MARKET')
sectors.type # sectors
sectors.name # Industrials
sectors.performance # 0.00711
sectors.last_updated # 1533672000437
See #sector-performance for detailed documentation or sectors.rb for returned fields.
Get Largest Trades
Fetches largest trades in the day for a specific stock. Ordered by largest trade on the top.
trades = client.largest_trades('aapl')
trades.first.price # 186.39
trades.first.size # 10000 - refers to the number of shares negotiated in the day.
trades.first.time # 1527090690175
trades.first.time_label # 11:51:30
trades.first.venue # EDGX
trades.first.venue_name # Cboe EDGX
See #largest-trades for detailed documentation or largest_trades.rb for returned fields.
Get a Quote for Crypto Currencies
Fetches a crypto currency quote.
crypto = client.crypto('BTCUSDT')
crypto.symbol #'BTCUSDT'
crypto.company_name #'Bitcoin USD'
crypto.primary_exchange #'crypto'
crypto.sector #'cryptocurrency'
crypto.calculation_price #'realtime'
crypto.open #3527.79
crypto.open_dollar #'$3,527'
crypto.open_time #1_548_082_840_296
crypto.close #3522.05522498
crypto.close_dollar #'$3,522'
crypto.close_time #1_548_169_240_296
crypto.high #3590.51
crypto.high_dollar #'$3,590'
See #crypto for detailed documentation or crypto.rb for returned fields.
ISIN Mapping
Convert ISIN to IEX Cloud symbols.
symbols = client.ref_data_isin('US0378331005')
symbols.first.exchange # NAS
symbols.first.iex_id # IEX_4D48333344362D52
symbols.first.region # US
symbols.first.symbol # AAPL
The API also lets you convert multiple ISINs to IEX Cloud symbols.
symbols = client.ref_data_isin(['US0378331005', 'US0378331006'])
You can use mapped: true
option to receive symbols grouped by their ISINs.
client.ref_data_isin(['US0378331005', 'US5949181045'], mapped: true) # {'US0378331005' => [...], 'US5949181045' => [...]}
See #ISIN Mapping for detailed documentation or isin_mapping.rb for returned fields.
Get Symbols
Returns an array of symbols.
symbols = client.ref_data_symbols()
symbol = symbols.first
symbol.exchange # NAS
symbol.iex_id # IEX_46574843354B2D52
symbol.region # US
symbol.symbol # A
See #symbols for detailed documentation or symbols.rb for returned fields.
Get Symbols for an Exchange
Returns an array of symbols for an exchange identified by a market identifier code.
symbols = client.ref_data_symbols_for_exchange('XTSE')
symbol = symbols.first
symbol.exchange # XTSE
symbol.iex_id # IEX_4656374258322D52
symbol.region # CA
symbol.symbol # A-CV
See #international-symbols for returned fields.
Get Symbols for a Region
Returns an array of symbols for a region.
symbols = client.ref_data_symbols_for_region('ca')
symbol = symbols.first
symbol.exchange # XTSE
symbol.iex_id # IEX_4656374258322D53
symbol.region # CA
symbol.symbol # A-CT
Get Latest Foreign Exchange Rates
Returns an array of foreign exchange rates for a given list of symbols.
rates = client.fx_latest(['USDCAD', 'USDGBP', 'USDJPY'])
rate = rates.first
rate.symbol # USDCAD
rate.rate # 1.25674
rate.timestamp # <Date: 2021-07-23 ((2459419j,0s,0n),+0s,2299161j)>
See #latest-currency-rates for returned fields.
Get List
Returns an array of quotes for the top 10 symbols in a specified list.
client.stock_market_list(:mostactive) # [{symbol: 'AAPL', ...}, {...}]
See #list for detailed documentation or quote.rb for returned fields.
Other Requests
Public endpoints that aren't yet supported by the client can be called using client.get
, client.post
, client.put
and client.delete
methods. Pass the required token explicitly:
client.post('ref-data/isin', isin: ['US0378331005'], token: 'secret_token') # [{'exchange' => 'NAS', ..., 'symbol' => 'AAPL'}, {'exchange' => 'ETR', ..., 'symbol' => 'APC-GY']
Configuration
You can configure client options globally or directly with a IEX::Api::Client
instance.
IEX::Api.configure do |config|
config.publishable_token = ENV['IEX_API_PUBLISHABLE_TOKEN']
config.endpoint = 'https://sandbox.iexapis.com/v1' # use sandbox environment
end
client = IEX::Api::Client.new(
publishable_token: ENV['IEX_API_PUBLISHABLE_TOKEN'],
endpoint: 'https://cloud.iexapis.com/v1'
)
The following settings are supported.
setting | description |
---|---|
user_agent | User-agent, defaults to IEX Ruby Client/version. |
proxy | Optional HTTP proxy. |
ca_path | Optional SSL certificates path. |
ca_file | Optional SSL certificates file. |
logger | Optional Logger instance or logger configuration to log HTTP requests. |
timeout | Optional open/read timeout in seconds. |
open_timeout | Optional connection open timeout in seconds. |
publishable_token | IEX Cloud API publishable token. |
endpoint | Defaults to https://cloud.iexapis.com/v1 . |
referer | Optional string for HTTP Referer header, enables token domain management. |
Logging
Faraday will not log HTTP requests by default. In order to do this you can either provide a logger
instance or configuration attributes to IEX::Api::Client
. Configuration allows you to supply the instance
, options
, and proc
to Faraday.
logger_instance = Logger.new(STDOUT)
IEX::Api.configure do |config|
config.logger.instance = logger_instance
config.logger.options = { bodies: true }
config.logger.proc = proc { |logger| logger.filter(/T?[sp]k_\w+/i, '[REMOVED]') }
end
# or
IEX::Api.logger do |logger|
logger.instance = logger_instance
logger.options = …
logger.proc = …
end
# or
IEX::Api.logger = logger_instance
# or
IEX::Api::Client.new(logger: logger_instance)
Sandbox Environment
IEX recommends you use a sandbox token and endpoint for testing.
However, please note that data in the IEX sandbox environment is scrambled. Therefore elements such as company and people names, descriptions, tags, and website URLs don't render any coherent data. In addition, results, such as closing market prices and dividend yield, are not accurate and vary on every call.
See IEX sandbox environment for more information.
Errors
SymbolNotFound
If a symbol cannot be found an IEX::Errors::SymbolNotFound exception is raised.
PermissionDeniedError
All errors that return HTTP code 403 result in a IEX::Errors::PermissionDeniedError exception.
ClientError
All errors that return HTTP codes 400-600 result in a IEX::Errors::ClientError exception.
Contributing
See CONTRIBUTING.
Copyright and License
Copyright (c) 2018-2019, Daniel Doubrovkine and Contributors.
This project is licensed under the MIT License.