iex-ruby-client 1.1.1 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63df99e38da35a6d4e4dc799e56d762b74ec873a8123b8c2f598edf6e284dc4d
-  data.tar.gz: 7a0c154efd557d72e50c887aeae7f7076afb5b93fffe10f3af403c8d83858e83
+  metadata.gz: bd85bc6a798e1c37eb803200aed631db1d1ff3fb6090714cceb01bb5d12c6c9f
+  data.tar.gz: 0e483fa9cf10d511714de9563034309c463278931628d077c580a33bbdbf32d0
 SHA512:
-  metadata.gz: 70bd058e8728effc81edecb7da6aa843e725a5648f27024bdf7e0b5458fe5906dc834d3b51d64d23df5df00091e11f334bc4a672b7ac815982885261344271e2
-  data.tar.gz: d1e9e823bc91ece071819487941a5b5d7efa4191178695e75c8ce9bdd65ee3f58c30b14354d9fdb5c839e2905b2a8acf7b5c54655377a25710d6a5cd8c26350a
+  metadata.gz: fe22b477b65f4ade43d1c0f9b44c07dc99664744f4d8fc0081aec8b29053e54c06d3c290e47a27a37c8452c81557f5d2c371d39e936ecd19d5ac0dbd68cd2124
+  data.tar.gz: 14b3664d77a34096534dc9c46fadfa8f7056c7d8bfe82bd5264ee390817363619ccc7de809e1bd8c80e9d7d5cce04e8e5d33b1f8ab8d88f86cf81d1f40e59027

data/.env.sample

@@ -0,0 +1,2 @@
+IEX_API_PUBLISHABLE_TOKEN=test-iex-api-publishable-token
+IEX_API_SECRET_TOKEN=test-iex-api-secret-token

data/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [dblock]

data/.rubocop_todo.yml

@@ -11,11 +11,3 @@
 Style/AsciiComments:
   Exclude:
     - 'lib/iex/resources/quote.rb'
-
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, Autocorrect.
-# SupportedStyles: module_function, extend_self
-Style/ModuleFunction:
-  Exclude:
-    - 'lib/iex/api/config.rb'

data/CHANGELOG.md

@@ -1,17 +1,54 @@
+### 1.4.1 (2021/05/15)
+* [#103](https://github.com/dblock/iex-ruby-client/pull/103): Added support for fetching symbols for an exchange - [@mathu97](https://github.com/mathu97).
+* [#99](https://github.com/dblock/iex-ruby-client/pull/99): Added `image` and `paywalled` to news - [@reddavis](https://github.com/reddavis).
+* [#100](https://github.com/dblock/iex-ruby-client/pull/100): Added `language` to news - [@reddavis](https://github.com/reddavis).
+
+### 1.4.0 (2020/11/19)
+* [#90](https://github.com/dblock/iex-ruby-client/pull/90): Added documentation for advanced stats and removed `avg_30_Volume` from advanced stats since it is found in key stats - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#91](https://github.com/dblock/iex-ruby-client/pull/91): Added support for Balance Sheet API endpoint - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#92](https://github.com/dblock/iex-ruby-client/pull/92): Added support for Cash Flow Statements API endpoint - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#93](https://github.com/dblock/iex-ruby-client/pull/93): Added `fiscal_date` and `currency` to income statements - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#94](https://github.com/dblock/iex-ruby-client/pull/94): Added `historical_prices` API endpoint - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+* [#95](https://github.com/dblock/iex-ruby-client/pull/95): Added all KeyStat properties to AdvancedStats since they are already returned in the API call - [@tylerhaugen-stanley](https://github.com/tylerhaugen-stanley).
+
+### 1.3.0 (2020/10/31)
+
+* [#82](https://github.com/dblock/iex-ruby-client/pull/82): Added `config.referer` to set HTTP `Referer` header. This enables IEX's "Manage domains" domain locking for tokens - [@agrberg](https://github.com/agrberg).
+* [#70](https://github.com/dblock/iex-ruby-client/pull/70): Added support for `ref_data_isin` taking a single `String` parameter - [@rodolfobandeira](https://github.com/rodolfobandeira).
+* [#84](https://github.com/dblock/iex-ruby-client/pull/84): Added support for Advanced Stats API - [@FanaHOVA](https://github.com/fanahova).
+* [#86](https://github.com/dblock/iex-ruby-client/issues/86): Added advanced logger configuration to `config.logger`. Now a hash with keys `:instance, :options, and :proc` can be passed and used directly with Faraday - [@agrberg](https://github.com/agrberg).
+* [#88](https://github.com/dblock/iex-ruby-client/pull/88): Updated logger configuration to work like `Config` class and allow attribute and block based configuration - [@agrberg](https://github.com/agrberg).
+* [#89](https://github.com/dblock/iex-ruby-client/pull/89): Backfill breaking `Config#logger` setting change from [#88](https://github.com/dblock/iex-ruby-client/pull/88) - [@agrberg](https://github.com/agrberg).
+
+### 1.2.0 (2020/09/01)
+
+* [#78](https://github.com/dblock/iex-ruby-client/pull/78): Added `Quote#extended_change_percent` and `Quote#extended_change_percent_s` properties to Quote - [@reddavis](https://github.com/reddavis).
+* [#71](https://github.com/dblock/iex-ruby-client/pull/71): Added `symbols` resource - [@ryosuke-endo](https://github.com/ryosuke-endo).
+* [#69](https://github.com/dblock/iex-ruby-client/pull/69): Fixed `ref_data_isin` request - [@bguban](https://github.com/bguban).
+* [#72](https://github.com/dblock/iex-ruby-client/pull/72): Cache `Faraday::Connection` for persistent adapters - [@dblock](https://github.com/dblock).
+
+### 1.1.2 (2020/03/25)
+
+* [#68](https://github.com/dblock/iex-ruby-client/pull/68): Fixed `ref_data_isin` request with wrong isin - [@bguban](https://github.com/bguban).
+* [#67](https://github.com/dblock/iex-ruby-client/pull/67): Added required ruby version to gemspec - [@wdperson](https://github.com/wdperson).
+* [#66](https://github.com/dblock/iex-ruby-client/pull/66): Fixed `KeyStats#week_52_change always` returns nil - [@brunjo](https://github.com/brunjo).
+* [#65](https://github.com/dblock/iex-ruby-client/pull/65): Added `stock_market_list` - [@bguban](https://github.com/bguban).
+* [#64](https://github.com/dblock/iex-ruby-client/pull/64): Added `ref_data_isin` - [@bguban](https://github.com/bguban).
+
 ### 1.1.1 (2020/03/02)
 
 * [#63](https://github.com/dblock/iex-ruby-client/pull/63): Allow direct API calls with support for secret_token - [@bguban](https://github.com/bguban).
-* [#61](https://github.com/dblock/iex-ruby-client/pull/61): Fix income endpoint if the api returns no result - [@brunjo](https://github.com/brunjo).
-* [#57](https://github.com/dblock/iex-ruby-client/pull/57): Update properties for chart api endpoint - [@brunjo](https://github.com/brunjo).
+* [#61](https://github.com/dblock/iex-ruby-client/pull/61): Fixed income endpoint if the api returns no result - [@brunjo](https://github.com/brunjo).
+* [#57](https://github.com/dblock/iex-ruby-client/pull/57): Updated properties for chart api endpoint - [@brunjo](https://github.com/brunjo).
 
 ### 1.1.0 (2019/07/08)
 
-* [#55](https://github.com/dblock/iex-ruby-client/pull/55): Add `income` statement API and add `tags` to the `company` - [@bingxie](https://github.com/bingxie).
+* [#55](https://github.com/dblock/iex-ruby-client/pull/55): Added `income` statement API and add `tags` to the `company` - [@bingxie](https://github.com/bingxie).
 
 ### 1.0.1 (2019/07/08)
 
-* [#50](https://github.com/dblock/iex-ruby-client/pull/50): Add missing properties for key stats API - [@bingxie](https://github.com/bingxie).
-* Fix: `uninitialized constant IEX::Endpoints::Chart::Date (NameError)` - [@dblock](https://github.com/dblock).
+* [#50](https://github.com/dblock/iex-ruby-client/pull/50): Added missing properties for key stats API - [@bingxie](https://github.com/bingxie).
+* Fixed `uninitialized constant IEX::Endpoints::Chart::Date (NameError)` - [@dblock](https://github.com/dblock).
 
 ### 1.0.0 (2019/04/23)
 
@@ -21,9 +58,9 @@
 ### 0.4.4 (2018/12/27)
 
 * [#39](https://github.com/dblock/iex-ruby-client/pull/39): Remove default range and use iextrading default range 1m instead in `IEX::Api::Dividends` - [@ildarkayumov](https://github.com/ildarkayumov).
-* [#37](https://github.com/dblock/iex-ruby-client/pull/37): Add `IEX::Resource::Crypto` - [@rodolfobandeira](https://github.com/rodolfobandeira).
-* [#34](https://github.com/dblock/iex-ruby-client/pull/34): Add `IEX::Resource::LargestTrades` - [@gil27](https://github.com/gil27).
-* [#32](https://github.com/dblock/iex-ruby-client/pull/32): Add `IEX::Resource::Sectors` - [@gil27](https://github.com/gil27).
+* [#37](https://github.com/dblock/iex-ruby-client/pull/37): Added `IEX::Resource::Crypto` - [@rodolfobandeira](https://github.com/rodolfobandeira).
+* [#34](https://github.com/dblock/iex-ruby-client/pull/34): Added `IEX::Resource::LargestTrades` - [@gil27](https://github.com/gil27).
+* [#32](https://github.com/dblock/iex-ruby-client/pull/32): Added `IEX::Resource::Sectors` - [@gil27](https://github.com/gil27).
 
 ### 0.4.3 (2018/08/18)
 
@@ -31,7 +68,7 @@
 
 ### 0.4.2 (2018/08/14)
 
-* [#24](https://github.com/dblock/iex-ruby-client/pull/24): Add danger-toc and danger-changelog - [@rodolfobandeira](https://github.com/rodolfobandeira).
+* [#24](https://github.com/dblock/iex-ruby-client/pull/24): Added danger-toc and danger-changelog - [@rodolfobandeira](https://github.com/rodolfobandeira).
 * [#21](https://github.com/dblock/iex-ruby-client/pull/21): Added `IEX::Resources::Dividends` - [@rodolfobandeira](https://github.com/rodolfobandeira).
 
 ### 0.4.1 (2018/08/07)
@@ -50,18 +87,18 @@
 
 ### 0.3.2 (2018/05/26)
 
-* Fix: undefined method > for nil:NilClass error - [@dblock](https://github.com/dblock).
+* Fixed undefined method > for nil:NilClass error - [@dblock](https://github.com/dblock).
 
 ### 0.3.1 (2018/05/23)
 
-* [#3](https://github.com/dblock/iex-ruby-client/issues/3): Fix: do not error on undefined properties - [@dblock](https://github.com/dblock).
+* [#3](https://github.com/dblock/iex-ruby-client/issues/3): Fixed do not error on undefined properties - [@dblock](https://github.com/dblock).
 
 ### 0.3.0 (2018/05/22)
 
 * Added `IEX::Resources::Chart#get` - [@dblock](https://github.com/dblock).
 * Added `IEX::Resources::News#get` - [@dblock](https://github.com/dblock).
 * Added `IEX::Resources::Price#get` - [@dblock](https://github.com/dblock).
-* Fix: added `IEX::Resources::Quote#extendedPrice` and `IEX::Resources::Quote#extendedPriceTime` - [@dblock](https://github.com/dblock).
+* Fixed added `IEX::Resources::Quote#extendedPrice` and `IEX::Resources::Quote#extendedPriceTime` - [@dblock](https://github.com/dblock).
 
 ### 0.2.0 (2018/03/26)
 

data/Dangerfile

@@ -1,2 +1,2 @@
-toc.check
-changelog.check
+toc.check!
+changelog.check!

data/Gemfile

@@ -3,7 +3,8 @@ source 'http://rubygems.org'
 gemspec
 
 group :test do
-  gem 'danger-changelog', '~> 0.3.0'
-  gem 'danger-toc', '~> 0.1'
+  gem 'danger-changelog', '~> 0.6.0'
+  gem 'danger-toc', '~> 0.2.0'
+  gem 'dotenv'
   gem 'pry'
 end

data/README.md

@@ -15,19 +15,29 @@ A Ruby client for the [The IEX Cloud API](https://iexcloud.io/docs/api/).
   - [Get a Quote](#get-a-quote)
   - [Get a OHLC (Open, High, Low, Close) price](#get-a-ohlc-open-high-low-close-price)
   - [Get a Market OHLC (Open, High, Low, Close) prices](#get-a-market-ohlc-open-high-low-close-prices)
+  - [Get Historical Prices](#get-historical-prices)
   - [Get Company Information](#get-company-information)
   - [Get a Company Logo](#get-a-company-logo)
   - [Get Recent News](#get-recent-news)
   - [Get Chart](#get-chart)
   - [Get Key Stats](#get-key-stats)
+  - [Get Advanced Stats](#get-advanced-stats)
   - [Get Dividends](#get-dividends)
   - [Get Earnings](#get-earnings)
   - [Get Income Statement](#get-income-statement)
+  - [Get Balance Sheet](#get-balance-sheet)
+  - [Get Cash Flow Statement](#get-cash-flow-statement)
   - [Get Sector Performance](#get-sector-performance)
   - [Get Largest Trades](#get-largest-trades)
   - [Get a Quote for Crypto Currencies](#get-a-quote-for-crypto-currencies)
+  - [ISIN Mapping](#isin-mapping)
+  - [Get Symbols](#get-symbols)
+  - [Get Symbols for an Exchange](#get-symbols-for-an-exchange)
+  - [Get List](#get-list)
   - [Other Requests](#other-requests)
 - [Configuration](#configuration)
+  - [Logging](#logging)
+- [Sandbox Environment](#sandbox-environment)
 - [Errors](#errors)
   - [SymbolNotFound](#symbolnotfound)
   - [PermissionDeniedError](#permissiondeniederror)
@@ -49,7 +59,7 @@ Run `bundle install`.
 
 ### Get an API Token
 
-Create an account on [IEX Cloud](https://iexcloud.io) and get a publishable token from the IEX cloud console. You should use a sandbox token and endpoint for testing.
+Create an account on [IEX Cloud](https://iexcloud.io) and get a publishable token from the IEX cloud console.
 
 ### Configure
 
@@ -57,7 +67,7 @@ Create an account on [IEX Cloud](https://iexcloud.io) and get a publishable toke
 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://sandbox.iexapis.com/v1' # defaults to 'https://cloud.iexapis.com/v1'
+  config.endpoint = 'https://cloud.iexapis.com/v1' # use 'https://sandbox.iexapis.com/v1' for Sandbox
 end
 ```
 
@@ -67,7 +77,7 @@ 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://sandbox.iexapis.com/v1'
+  endpoint: 'https://cloud.iexapis.com/v1'
 )
 ```
 
@@ -101,7 +111,7 @@ See [#quote](https://iexcloud.io/docs/api/#quote) for detailed documentation or
 Fetches a single stock OHLC price. Open and Close prices contain timestamp.
 
 ```ruby
-ohlc = client.ohlc.get('MSFT')
+ohlc = client.ohlc('MSFT')
 
 ohlc.close.price # 90.165
 ohlc.close.time #
@@ -125,6 +135,60 @@ 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.
+
+```ruby
+historial_prices = client.historical_prices('MSFT') # One month of data
+historial_prices = client.historical_prices('MSFT', {range: 'max'}) # All data up to 15 years
+historial_prices = client.historical_prices('MSFT', {range: 'ytd'}) # Year to date data
+historial_prices = client.historical_prices('MSFT', {range: '5y'}) # 5 years of data
+historial_prices = client.historical_prices('MSFT', {range: '6m'}) # 6 months of data
+historial_prices = client.historical_prices('MSFT', {range: '5d'}) # 5 days of data
+historial_prices = client.historical_prices('MSFT', {range: 'date', date: '20200930', chartByDay: 'true'}) # One day of data
+historial_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
+
+```ruby
+historial_prices = client.historical_prices('MSFT') # One month of data
+
+historial_price = historial_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](https://iexcloud.io/docs/api/#historical-prices) or [historical_prices.rb](lib/iex/resources/historical_prices.rb) for returned fields.
+
 ### Get Company Information
 
 Fetches company information for a symbol.
@@ -260,6 +324,50 @@ key_stats.beta # 1.4135449089973444
 
 See [#key-stats](https://iexcloud.io/docs/api/#key-stats) for detailed documentation or [key_stats.rb](lib/iex/resources/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.
+
+```ruby
+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](https://iexcloud.io/docs/api/#advanced-stats) for detailed documentation or [advanced_stats.rb](lib/iex/resources/advanced_stats.rb) for returned fields.
+
 ### Get Dividends
 
 Fetches dividends for a symbol.
@@ -299,12 +407,16 @@ See [#earnings](https://iexcloud.io/docs/api/#earnings) for detailed documentati
 
 ### Get Income Statement
 
-Fetches income statement for a symbol.
+Fetches income statements for a symbol.
 
 ```ruby
-income = client.income('MSFT')
+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
@@ -316,6 +428,48 @@ income.gross_profit_dollar # '$20,335,000,000'
 
 See [#income-statement](https://iexcloud.io/docs/api/#income-statement) for detailed documentation or [income.rb](lib/iex/resources/income.rb) for returned fields.
 
+### Get Balance Sheet
+
+Fetches balance sheets for a symbol.
+
+```ruby
+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](https://iexcloud.io/docs/api/#balance-sheet) for detailed documentation or [balance_sheet.rb](lib/iex/resources/balance_sheet.rb) for returned fields.
+
+### Get Cash Flow Statement
+
+Fetches cash flow statements for a symbol.
+
+```ruby
+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](https://iexcloud.io/docs/api/#cash-flow) for detailed documentation or [cash_flow.rb](lib/iex/resources/cash_flow.rb) for returned fields.
+
 ### Get Sector Performance
 
 Fetches latest sector's performance.
@@ -372,9 +526,78 @@ crypto.high_dollar #'$3,590'
 
 See [#crypto](https://iexcloud.io/docs/api/#crypto) for detailed documentation or [crypto.rb](lib/iex/resources/crypto.rb) for returned fields.
 
+### ISIN Mapping
+
+Convert ISIN to IEX Cloud symbols.
+
+```ruby
+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.
+
+```ruby
+symbols = client.ref_data_isin(['US0378331005', 'US0378331006'])
+```
+
+You can use `mapped: true` option to receive symbols grouped by their ISINs.
+
+```ruby
+client.ref_data_isin(['US0378331005', 'US5949181045'], mapped: true) # {'US0378331005' => [...], 'US5949181045' => [...]}
+```
+
+See [#ISIN Mapping](https://iexcloud.io/docs/api/#isin-mapping) for detailed documentation or [isin_mapping.rb](lib/iex/resources/isin_mapping.rb) for returned fields.
+
+### Get Symbols
+
+Returns an array of symbols
+
+```ruby
+symbols = client.ref_data_symbols()
+
+symbol = symbols.first
+symbol.exchange # NAS
+symbol.iex_id # IEX_46574843354B2D52
+symbol.region # US
+symbol.symbol # A
+```
+
+See [#symbols](https://iexcloud.io/docs/api/#symbols) for detailed documentation or [symbols.rb](lib/iex/resources/symbols.rb) for returned fields.
+
+### Get Symbols for an Exchange
+
+Returns an array of symbols for a given exchange
+
+```ruby
+symbols = client.ref_data_symbols_for_exchange('TSX')
+
+symbol = symbols.first
+symbol.exchange # TSX
+symbol.iex_id # IEX_4656374258322D52
+symbol.region # CA
+symbol.symbol # A-CV
+```
+
+See [#international-symbols](https://iexcloud.io/docs/api/#international-symbols).
+
+### Get List
+
+Returns an array of quotes for the top 10 symbols in a specified list.
+
+```ruby
+client.stock_market_list(:mostactive) # [{symbol: 'AAPL', ...}, {...}]
+```
+
+See [#list](https://iexcloud.io/docs/api/#list) for detailed documentation or [quote.rb](lib/iex/resources/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` 
+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:
 
 ```ruby
@@ -386,7 +609,7 @@ client.post('ref-data/isin', isin: ['US0378331005'], token: 'secret_token') # [{
 You can configure client options globally or directly with a `IEX::Api::Client` instance.
 
 ```ruby
-IEX::Api::Client.configure do |config|
+IEX::Api.configure do |config|
   config.publishable_token = ENV['IEX_API_PUBLISHABLE_TOKEN']
   config.endpoint = 'https://sandbox.iexapis.com/v1' # use sandbox environment
 end
@@ -395,23 +618,56 @@ end
 ```ruby
 client = IEX::Api::Client.new(
   publishable_token: ENV['IEX_API_PUBLISHABLE_TOKEN'],
-  endpoint: 'https://sandbox.iexapis.com/v1'
+  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 that logs 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`.
+| 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](https://lostisland.github.io/faraday/middleware/logger#include-and-exclude-headersbodies).
+
+```ruby
+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](https://intercom.help/iexcloud/en/articles/2915433-testing-with-the-iex-cloud-sandbox) for more information.
 
 ## Errors