Add historical prices api endpoint

CHANGELOG.md

@@ -4,6 +4,7 @@
 * [#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).
 
 ### 1.3.0 (2020/10/31)
 

README.md

@@ -15,6 +15,7 @@ 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)
@@ -133,6 +134,57 @@ 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.

lib/iex/api.rb

@@ -5,6 +5,7 @@
 require_relative 'endpoints/company'
 require_relative 'endpoints/dividends'
 require_relative 'endpoints/earnings'
+require_relative 'endpoints/historial_prices'
 require_relative 'endpoints/income'
 require_relative 'endpoints/largest_trades'
 require_relative 'endpoints/logo'

lib/iex/api/client.rb

@@ -12,6 +12,7 @@ class Client
       include Endpoints::Crypto
       include Endpoints::Dividends
       include Endpoints::Earnings
+      include Endpoints::HistoricalPrices
       include Endpoints::Income
       include Endpoints::KeyStats
       include Endpoints::LargestTrades

lib/iex/endpoints/historial_prices.rb

@@ -0,0 +1,30 @@
+module IEX
+  module Endpoints
+    module HistoricalPrices
+      def historical_prices(symbol, options = {})
+        if options[:range] == 'date'
+          raise ArgumentError unless options[:date].present?
+          raise ArgumentError unless options[:chartByDay].present?
+        end
+
+        options = options.dup
+        # Historical prices IEX endpoint expects dates passed in a specific format - YYYYMMDD
+        options[:date] = options[:date].strftime('%Y%m%d') if options[:date].is_a?(Date)
+
+        path = "stock/#{symbol}/chart"
+        path += "/#{options[:range]}" if options.key?(:range)
+        path += "/#{options[:date]}" if options[:range] == 'date'
+
+        # We only want options to include query params at this point, remove :range and :date
+        options.delete(:range)
+        options.delete(:date)
+
+        (get(path, { token: publishable_token }.merge(options)) || []).map do |data|
+          IEX::Resources::HistorialPrices.new(data)
+        end
+      rescue Faraday::ResourceNotFound => e
+        raise IEX::Errors::SymbolNotFoundError.new(symbol, e.response[:body])
+      end
+    end
+  end
+end

lib/iex/resources.rb

@@ -7,6 +7,7 @@
 require_relative 'resources/company'
 require_relative 'resources/dividends'
 require_relative 'resources/earnings'
+require_relative 'resources/historical_prices'
 require_relative 'resources/income'
 require_relative 'resources/key_stats'
 require_relative 'resources/largest_trades'

lib/iex/resources/historical_prices.rb

@@ -0,0 +1,31 @@
+module IEX
+  module Resources
+    class HistorialPrices < Resource
+      property 'date'
+      property 'open'
+      property 'open_dollar', from: 'open', with: ->(v) { to_dollar(amount: v, ignore_cents: false) }
+      property 'close'
+      property 'close_dollar', from: 'close', with: ->(v) { to_dollar(amount: v, ignore_cents: false) }
+      property 'high'
+      property 'high_dollar', from: 'high', with: ->(v) { to_dollar(amount: v, ignore_cents: false) }
+      property 'low'
+      property 'low_dollar', from: 'low', with: ->(v) { to_dollar(amount: v, ignore_cents: false) }
+      property 'volume'
+      property 'u_open', from: 'uOpen'
+      property 'u_open_dollar', from: 'uOpen', with: ->(v) { to_dollar(amount: v, ignore_cents: false) }
+      property 'u_close', from: 'uClose'
+      property 'u_close_dollar', from: 'uClose', with: ->(v) { to_dollar(amount: v, ignore_cents: false) }
+      property 'u_low', from: 'uLow'
+      property 'u_low_dollar', from: 'uLow', with: ->(v) { to_dollar(amount: v, ignore_cents: false) }
+      property 'u_high', from: 'uHigh'
+      property 'u_high_dollar', from: 'uHigh', with: ->(v) { to_dollar(amount: v, ignore_cents: false) }
+      property 'u_volume', from: 'uVolume'
+      property 'change'
+      property 'change_percent', from: 'changePercent'
+      property 'change_percent_s', from: 'changePercent', with: ->(v) { percentage_to_string(v) }
+      property 'label'
+      property 'change_over_time', from: 'changeOverTime'
+      property 'change_over_time_s', from: 'changeOverTime', with: ->(v) { percentage_to_string(v) }
+    end
+  end
+end

lib/iex/resources/resource.rb

@@ -14,6 +14,18 @@ def self.float_to_percentage(float_number)
         ].join
       end
 
+      # Useful for values that are already a percent but we want to convert into a 2 decimal place string
+      def self.percentage_to_string(float_percent)
+        return unless float_percent.is_a? Numeric
+        return '+0.00%' if float_percent.zero?
+
+        [
+          float_percent.positive? ? '+' : '',
+          format('%.2f', float_percent),
+          '%'
+        ].join
+      end
+
       def self.to_dollar(amount:, ignore_cents: true)
         MoneyHelper.money_to_text(amount, 'USD', nil, no_cents: ignore_cents)
       end