market_data 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '082a3b709ed32b745807906d0324a3b839a90c95e55bc199b564db75518d1fbc'
-  data.tar.gz: dab55b3c50200dbf92e071dc0bd3eab5b8d712928f82d045c92a80a5f09b0979
+  metadata.gz: c83d3644178f120e069d283ebfc132d543ac8dbe2aca9734388d2cd56274bf7c
+  data.tar.gz: eeef52d93f45e64b4869749bd787b0af576924a0b617e8897c4eada6dcf813b2
 SHA512:
-  metadata.gz: 64fca38c4e459cb4244f845ad4137939249c353b2e91922cc0bb416a2b1129871916c80bf0d44e3a71e8c48b797de2a27f378192a790286aed9d2f985345c556
-  data.tar.gz: 97b5508677cbff6418254771f78e68eb48c0ee66c067274663a40ad2c6cd00af3355dac9b93bd812e90290f2fb1c10af2d0b6ba3aa447bcc760f43024ccc8dc9
+  metadata.gz: b01a71a756244d6461e19cad34abb3b25df2705b43e03e47a936a66a471879f8ae0038e49ab01f062ec0db4c046e40e2d80d3162a5c065f535ffa7877efed548
+  data.tar.gz: fe1a289aa65eb0e6a0682b9e263a232f0eb2b913a808b9c6ac5271e46b52123a4c805a586bc5b2a1b9aeda92c17fb640815e6230907a9dcf6a0c5379bcd34b59

data/CHANGELOG.md

@@ -19,4 +19,14 @@
 - Internal rework of code. New modules for models, mappers, constants and errors
 - Introduced unit tests for almost all modules.
 - Introduced coverage. Currently at 85%
-- Add functionality for [Candles](https://www.marketdata.app/docs/api/stocks/candles) and [Bulk Candles](https://www.marketdata.app/docs/api/stocks/bulkcandles) endpoints
+- Add functionality for [Candles](https://www.marketdata.app/docs/api/stocks/candles) and [Bulk Candles](https://www.marketdata.app/docs/api/stocks/bulkcandles) endpoints
+
+## [0.2.1] - 2024-10-09
+
+- Fix broken tests
+- Add support for new optional parameters for `quotes` and `bulk_quotes` endpoint
+
+## [0.3.0] - 2024-10-09
+
+- Add support for Earnings endpoint under the `earnings` method
+- Introduced `Validations` module for parameter validation logic

data/README.md

@@ -2,17 +2,130 @@
 
 A Ruby wrapper for the [MarketData API](https://www.marketdata.app/docs/api).
 
+![coverage](https://img.shields.io/badge/coverage%3A-87.77%25-yellow.svg)
+
 ## Installation
 
-    $ gem install market-data
-    $ bundle install
+    $ gem install market_data
 
 ## Usage
 
-    $ client = MarketData.Client.new "YOUR_API_TOKEN"
+You must instantiate a `MarketData::Client` before running any method. You'll need your MarketData API token first.
+
+    $ client = MarketData::Client.new "YOUR_API_TOKEN"
+    
     $ client.quote("AAPL")
     $ => <struct MarketData::Models::Quote symbol="AAPL", ask=231.42, askSize=2, bid=231.4, .....
 
+### Quotes
+For getting a single quote, run the `quote` method just as the example above.
+
+#### Optional parameters
+
+* `w52`
+
+For getting fields with 52-week low and high information, pass true as the `w52` parameter. 
+    
+    $ q = client.quote("AAPL", w52=true)
+    $ => q.high52 = 252.11
+    $ => q.low52 = 222.35    
+**It is `false` by default.**
+
+* `extended`
+
+For getting a quote when market is on extended hours, you have to supply the `extended` parameter as true. 
+
+**It is false by default**, so if you fetch a quote during extended hours without the parameter, you'll always get the quote at closing time.
+
+### Bulk quotes
+
+For getting multiple quotes in a single request, use the `bulk_candle` method.
+
+    $ quotes = client.bulk_quotes(["AAPL", "AMD", "NOTAQUOTE])
+    
+    $ quotes["AMD"] => <struct MarketData::Models::Quote symbol="AMD", ask=150.42, askSize=2, bid=146.4, .....
+    
+    $ quotes["NOTAQUOTE"] = nil
+
+If a quote is not found, the hashmap will return a nil value for that ticker's key.
+
+#### Optional parameters
+
+* `snapshot`
+
+If snapshot is true, any supplied array of symbols will be ignored and a complete snapshot of the market ticker's will be returned.
+    
+    $ quotes = client.bulk_quotes([], snapshot = true)
+
+    $ quotes["A"] => <struct MarketData::Models::Quote symbol="A", ask=56.32, askSize=45, bid=67, .....
+    ....
+    $ quotes["Z"] => <struct MarketData::Models::Quote symbol="Z", ask=25, askSize=3, bid=14.5, .....
+
+**This could use all you API credits. Use with caution.**
+
+* `extended`
+
+For getting a quote when market is on extended hours, you have to supply the `extended` parameter as true. 
+
+**It is false by default**, so if you fetch a quote during extended hours without the parameter, you'll get the quote at closing time.
+
+### Candles
+For getting ticker candles, you'll need to specify:
+* a ticker symbol
+* a resolution (`M`, `D`, `W`, etc. See [docs](https://www.marketdata.app/docs/api/stocks/candles#request-parameters) for a complete list)
+* a strategy to specfy a date range. You can use `from` and `to` OR `to` and `countback`.
+
+
+As an example, for getting candles for last week, for the first strategy:
+        
+        $ quotes = client.candles("AAPL", "D", (Time.current - 1.week).iso8601, Time.current.iso8601, nil)
+
+and for the second
+
+        $ quotes = client.candles("AAPL", "D", nil, Time.current.iso8601, 7)
+
+`to` and `from` can receive an ISO 8601 compliant utc format or a unix timestamp.
+
+### Bulk candles
+
+For the `bulk_candles` method you pass a array of ticker symbols. Resolution is daily by default, although any daily variation will work as well (like `2D`, `3D`, etc.)
+
+It returns a hashmap with the ticker symbol as a key.
+
+        $ candles = client.bulk_candles(["AAPL", "AMD", "NOTAQUOTE"])
+
+        $ candles["AMD"]
+        $ => #<struct MarketData::Models::Candle symbol="AMD", open=174.05, high=174.05, low=169.55, close=171.02, volume=33391035, time=1728446400>
+        $ candles["AAPL"]
+        $ => #<struct MarketData::Models::Candle symbol="AAPL", open=225.23, high=229.75, low=224.83, close=229.54, volume=31398884, time=1728446400>
+        $ candles["NOTAQUOTE"] => nil
+
+If a quote is not found, the hashmap will return a nil value for that ticker's key.
+
+### Earnings
+
+See the API [docs](https://www.marketdata.app/docs/api/stocks/earnings) for parameter specification.
+
+        $ client.earnings("AAPL", from: (Time.now - MarketData::Constants::YEAR).iso8601, to: Time.now.iso8601, countback: nil, report: nil, date: nil)
+        $ => [#<struct MarketData::Models::Earning
+            symbol="AAPL",
+            fiscal_year=2023,
+            fiscal_quarter=4,
+            date=1696046400,
+            report_date=1698897600,
+            report_time="after close",
+            currency="USD",
+            reported_eps=1.46,
+            estimated_eps=1.39,
+            surprise_eps=0.07,
+            surprise_eps_pct=0.0504,
+            updated=1728273600>,
+            #<struct MarketData::Models::Earning
+            symbol="AAPL",
+            fiscal_year=2024,
+            fiscal_quarter=1,
+            ...
+
 ## ROADMAP
 
 The following is an ordered list of next expected developments, based on the endpoints present in the [docs](https://www.marketdata.app/docs/api)
@@ -22,19 +135,19 @@ From Stocks endpoints:
 - [X] Bulk Stocks
 - [X] Candles
 - [X] Bulk Candles
-- [X] Support for optional parameters for Bulk Candles
-- [] Earnings
+- [X] Support for new optional parameters for Quotes and Bulk Quotes
+- [X] Earnings
 
 From Markets endpoints:
-- [] Status
+- [ ] Status
 
 From Indices endpoints:
-- [] Quotes
-- [] Candles
+- [ ] Quotes
+- [ ] Candles
 
 From Stocks endpoints:
-- [] Support for optional parameters for Candles
-- [] Support for optional parameters for Bulk Candles
+- [ ] Support for optional parameters for Candles
+- [ ] Support for optional parameters for Bulk Candles
 
 
 ## Tests

data/lib/market_data/constants.rb

@@ -5,9 +5,47 @@ module MarketData
     HOUR = MINUTE * 60
     DAY = HOUR * 24
     WEEK = DAY * 7
+    MONTH_30 = DAY * 30
+    MONTH_31 = DAY * 31
     YEAR = DAY * 365
 
-    QUOTE_FIELDS = [:symbol, :ask, :askSize, :bid, :bidSize, :mid, :last, :change, :changepct, :volume, :updated, :high52, :low52]
-    CANDLE_FIELDS = [:symbol, :open, :high, :low, :close, :volume, :time]
+    EARNING_FIELD_MAPPING = {
+      symbol: "symbol",
+      fiscal_year: "fiscalYear",
+      fiscal_quarter: "fiscalQuarter",
+      date: "date",
+      report_date: "reportDate",
+      report_time: "reportTime",
+      currency: "currency",
+      reported_eps: "reportedEPS",
+      estimated_eps: "estimatedEPS",
+      surprise_eps: "surpriseEPS",
+      surprise_eps_pct: "surpriseEPSpct",
+      updated: "updated"
+    }
+    CANDLE_FIELD_MAPPING = {
+      symbol: "symbol",
+      open: "o",
+      close: "c",
+      low: "l",
+      high: "h",
+      volume: "v",
+      time: "t",
+    }
+    QUOTE_FIELD_MAPPING = {
+      symbol: "symbol",
+      ask: "ask",
+      ask_size: "askSize",
+      bid: "bid",
+      bid_size: "bidSize",
+      mid: "mid",
+      last: "last",
+      change: "change",
+      change_pct: "changepct",
+      volume: "volume",
+      updated: "updated",
+      high52: "high52",
+      low52: "low52",
+    }
   end
 end

data/lib/market_data/mappers.rb

@@ -3,32 +3,16 @@ require 'market_data/models'
 module MarketData
   module Mappers
     include MarketData::Models
-
     SYMBOL_RESPONSE_KEY = "symbol"
     STATUS_RESPONSE_KEY = "s"
 
     def map_quote response, i=0
-      Quote.new(
-        symbol: response["symbol"][i],
-        ask: response["ask"][i],
-        askSize: response["askSize"][i],
-        bid: response["bid"][i],
-        bidSize: response["bidSize"][i],
-        mid: response["mid"][i],
-        last: response["last"][i],
-        change: response["change"][i],
-        changepct: response["changepct"][i],
-        volume: response["volume"][i],
-        updated: response["updated"][i],
-        high52: response.fetch("high52", nil),
-        low52: response.fetch("low52", nil),
-      )
+      Quote.new(**map_fields_for(response, :quote, i))
     end
 
     def map_bulk_quotes response
       h = Hash.new
-      size = response[SYMBOL_RESPONSE_KEY].size
-      for i in 0..(size - 1) do
+      (0..(response[SYMBOL_RESPONSE_KEY].size - 1)).each do |i|
         qquote = map_quote(response, i)
         h[response[SYMBOL_RESPONSE_KEY][i]] = !qquote.blank? ? qquote : nil
       end
@@ -37,31 +21,50 @@ module MarketData
 
     def map_candles response, symbol
       ar = []
-      size = response["o"].size
-    
-      for i in 0..(size - 1) do
-        ar << Candle.new(
-          open: response["o"][i],
-          high: response["h"][i],
-          low: response["l"][i],
-          close: response["c"][i],
-          volume: response["v"][i],
-          time: response["t"][i],
-          symbol: symbol
-        )
+      (0..(response["o"].size - 1)).each do |i|
+        args = map_fields_for(response, :candle, i)
+        args[:symbol] = symbol
+        ar << Candle.new(**args)
       end
+    
       ar
     end
 
     def map_bulk_candles response
       h = Hash.new
-      size = response[SYMBOL_RESPONSE_KEY].size
-    
-      for i in 0..(size - 1) do
-        candle = Candle.new(symbol: response["symbol"][i], open: response["o"][i], high: response["h"][i], low: response["l"][i], close: response["c"][i], volume: response["v"][i], time: response["t"][i])
+      (0..(response[SYMBOL_RESPONSE_KEY].size - 1)).each do |i|
+        candle = Candle.new(**map_fields_for(response, :candle, i))
         h[response[SYMBOL_RESPONSE_KEY][i]] = !candle.blank? ? candle : nil
       end
       h
     end
+
+    def map_earning response
+      ar = []
+      (0..(response[SYMBOL_RESPONSE_KEY].size - 1)).each do |i|
+        ar << Earning.new(**map_fields_for(response, :earning, i))
+      end
+      ar
+    end
+
+    def map_fields_for(response, kind, i=0)
+      mapping = {}
+      case kind
+      when :candle
+        mapping = Constants::CANDLE_FIELD_MAPPING
+      when :earning
+        mapping = Constants::EARNING_FIELD_MAPPING
+      when :quote
+        mapping = Constants::QUOTE_FIELD_MAPPING
+      else
+        raise BadParameterError.new("unrecognized model for mapping: #{kind}")
+      end
+      
+      r = {}
+      mapping.each do |field, mapped|
+        r.store(field, response.fetch(mapped, nil).nil? ? nil : response.fetch(mapped)[i])
+      end
+      r
+    end
   end
 end

data/lib/market_data/models.rb

@@ -2,18 +2,18 @@ require 'market_data/constants'
 
 module MarketData
   module Models
-    include MarketData::Constants
-
-    Quote = Struct.new(*Constants::QUOTE_FIELDS) do
+    Quote = Struct.new(*Constants::QUOTE_FIELD_MAPPING.keys) do
       def blank?
-        (QUOTE_FIELDS - [:symbol]).all? { |mmethod| self[mmethod].nil?}
+        (Constants::QUOTE_FIELD_MAPPING.keys - [:symbol]).all? { |mmethod| self[mmethod].nil?}
       end
     end
 
-    Candle = Struct.new(*Constants::CANDLE_FIELDS) do
+    Candle = Struct.new(*Constants::CANDLE_FIELD_MAPPING.keys) do
       def blank?
-        (CANDLE_FIELDS - [:symbol]).all? { |mmethod| self[mmethod].nil?}
+        (Constants::CANDLE_FIELD_MAPPING.keys - [:symbol]).all? { |mmethod| self[mmethod].nil?}
       end
     end
+
+    Earning = Struct.new(*Constants::EARNING_FIELD_MAPPING.keys)
   end
 end

data/lib/market_data/quotes.rb

@@ -1,41 +1,38 @@
 require 'market_data/conn'
 require 'market_data/errors'
 require 'market_data/mappers'
+require 'market_data/validations'
 
 module MarketData
   module Quotes
     include MarketData::Mappers
     include MarketData::Errors
     include MarketData::Conn
+    include MarketData::Validations
 
     @@single = "/v1/stocks/quotes/"
     @@bulk = "/v1/stocks/bulkquotes/"
     @@candles = "/v1/stocks/candles/"
     @@bulk_candles = "/v1/stocks/bulkcandles/"
+    @@earnings = "/v1/stocks/earnings/"
 
-    def quote(symbol, w52 = false)
+    def quote(symbol, w52 = false, extended = false)
+      query = validate_quotes_input!(symbol: symbol, w52: w52, extended: extended)
+      
       path_hash = { host: MarketData.base_host, path: @@single + symbol }
-      if w52
-        path_hash[:query] = URI.encode_www_form({"52week" => true })
+      if !query.empty?
+        path_hash[:query] = URI.encode_www_form(query)
       end
+      
       res = do_connect(get_uri path_hash)
       map_quote(res)
     end
 
-    def bulk_quotes(symbols, snapshot = false)
-      path_hash = { host: MarketData.base_host, path: @@bulk  }
-      query_hash = {}
-      
-      if snapshot
-        query_hash[:snapshot] = true
-      else
-        if !symbols.is_a?(Array) || symbols.size < 1
-          raise BadParameterError.new("symbols must be a non-empty list")
-        end
-        query_hash = { symbols: symbols.join(",") }
-      end
+    def bulk_quotes(symbols, snapshot = false, extended = false)
+      query = validate_bulk_quotes_input!(symbols: symbols, snapshot: snapshot, extended: extended)
       
-      path_hash[:query] = URI.encode_www_form(query_hash)
+      path_hash = { host: MarketData.base_host, path: @@bulk  }
+      path_hash[:query] = URI.encode_www_form(query)
 
       res = do_connect(get_uri path_hash)
       map_bulk_quotes res
@@ -44,43 +41,33 @@ module MarketData
     def candles(symbol, opts = {})
       defaults = {resolution: "D", from: nil, to: Time.now.utc.to_i, countback: nil}
       opts = defaults.merge(opts)
-      
-      query_hash = {to: opts[:to]}
-    
-      # TODO Move method validations into own class
-      # TODO check to is either iso8601 or unix
-      if opts[:from].nil? && opts[:countback].nil?
-        raise BadParameterError.new("either :from or :countback must be supplied")
-      end
-
-      if opts[:from].nil?
-        query_hash[:countback] = opts[:countback]
-      else
-        query_hash[:from] = opts[:from]
-      end
+      query =  validate_candles_input!(**opts)
       
       path_hash = { host: MarketData.base_host, path: @@candles + opts[:resolution] + "/" + symbol }
-      path_hash[:query] = URI.encode_www_form(query_hash)
+      path_hash[:query] = URI.encode_www_form(query)
       
       res = do_connect(get_uri path_hash)
       map_candles res, symbol
     end
 
     def bulk_candles(symbols, resolution = "D")
-      unless resolution == "daily" || resolution == "1D" || resolution == "D"
-        raise BadParameterError.new("only daily resolution is allowed for this endpoint")
-      end
+      query = validate_bulk_candles_input!(symbols: symbols, resolution: resolution)
+      query = query.except(:resolution)
+      
       path_hash = { host: MarketData.base_host, path: @@bulk_candles + resolution + "/" }
+      path_hash[:query] = URI.encode_www_form(query)
       
-      if !symbols.is_a?(Array) || symbols.size < 1
-        raise BadParameterError.new("symbols must be a non-empty list")
-      end
-      query_hash = { symbols: symbols.join(",") }
+      res = do_connect(get_uri path_hash)
+      map_bulk_candles res
+    end
 
-      path_hash[:query] = URI.encode_www_form(query_hash)
+    def earnings(symbol, opts = {from: nil, to: nil, countback: nil, date: nil, report: nil})
+      path_hash = { host: MarketData.base_host(), path: @@earnings + symbol}
+      query = validate_earnings_input!(**opts)
+      path_hash[:query] = URI.encode_www_form(query)
 
       res = do_connect(get_uri path_hash)
-      map_bulk_candles res
+      map_earning res
     end
   end
 end

data/lib/market_data/validations.rb

@@ -0,0 +1,128 @@
+require 'date'
+
+module MarketData
+  module Validations
+    include MarketData::Errors
+    
+    VALID_DAILY_RESOLUTION = ['daily', 'D', '1D', '2D', '3D', '4D', '5D']
+    VALID_RESOLUTIONS = [
+      *VALID_DAILY_RESOLUTION,
+      'weekly', 'W', '1W', '2W', '3W', '4W', '5W',
+      'monthly', 'M', '1M', '2M', '3M', '4M', '5M',
+      'yearly', 'Y', '1Y', '2Y', '3Y', '4Y', '5Y',
+    ]
+
+    def validate_quotes_input!(symbol: nil, w52: nil, extended: nil)
+      result = {}
+    
+      if w52
+        result.merge!({"52week" => true})
+      end
+      # MarketData API considers extended as true by default. Should be included
+      # in the query when false
+      if !extended
+        result.merge!({extended: false})
+      end
+      
+      result
+    end
+    
+    def validate_bulk_quotes_input!(symbols: nil, snapshot: nil, extended: nil)
+      result = {extended: false}
+      if snapshot
+        result.merge!({snapshot: true})
+      else
+        if !symbols.kind_of?(Array) || symbols.size < 2
+          raise BadParameterError.new("symbols must be list with at least 2 symbols")
+        end
+        result.merge!({symbols: symbols.join(",")})
+      end
+      if extended
+        result.merge!({extended: true})
+      end
+      
+      result
+    end
+
+    def validate_bulk_candles_input!(resolution: nil, symbols: nil)
+      s, r = validate_resolution(resolution, VALID_DAILY_RESOLUTION)
+      if s == :invalid
+        raise BadParameterError.new(r)
+      end
+      if !symbols.kind_of?(Array) || symbols.size < 2
+        raise BadParameterError.new("symbols must be list with at least 2 symbols")
+      end
+
+      r.merge({symbols: symbols.join(",")})
+    end
+
+    def validate_candles_input!(
+      resolution: nil, from: nil, to: nil, countback: nil
+    )
+
+      state, response = validate_from_to_countback_strategy(from: from, to: to, countback: countback)
+      if state == :invalid
+        raise BadParameterError.new(response)
+      end
+
+      state, res = validate_resolution(resolution)
+      if state == :invalid
+        raise BadParameterError.new(res)
+      end
+
+      response.merge(res)
+    end
+    
+    def validate_earnings_input!(
+      from: nil, to: nil, countback: nil, date: nil, report: nil
+    )
+      if !date.nil?
+        return {date: date}
+      end
+      if !report.nil?
+        return {report: report}
+      end
+      
+      state, response = validate_from_to_countback_strategy(from: from, to: to, countback: countback)
+      if state == :invalid
+        raise BadParameterError.new(response)
+      end
+
+      return response
+    end
+
+    def validate_from_to_countback_strategy(
+      from: nil, to: nil, countback: nil
+    )
+      if !from.nil? && !to.nil?
+        return :valid, {from: from, to: to}
+      end
+      if !to.nil? && !countback.nil? && from.nil?
+        return :valid, {to: to, countback: countback}
+      end
+      
+      return :invalid, "supply either :from and :to, or :to and :countback"
+    end
+
+    def validate_resolution resolution, allowed_values = VALID_RESOLUTIONS
+      if VALID_RESOLUTIONS.include? resolution
+        return :valid, {resolution: resolution}
+      end
+      return :invalid, "invalid resolution: #{resolution}"
+    end
+    
+    def time_valid?(t)
+      if t.kind_of?(String)
+        begin
+          DateTime.iso8601(t)
+          return true
+        rescue
+          return false
+        end
+      end
+      if t.kind_of?(Integer)
+        return t > 0
+      end
+    end
+  end
+end

data/lib/market_data/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MarketData
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: market_data
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sebastián González
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-30 00:00:00.000000000 Z
+date: 2024-10-11 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby client for the MarketData API.
 email:
@@ -31,6 +31,7 @@ files:
 - lib/market_data/mappers.rb
 - lib/market_data/models.rb
 - lib/market_data/quotes.rb
+- lib/market_data/validations.rb
 - lib/market_data/version.rb
 - market_data.gemspec
 - sig/market_data.rbs