market_data 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02bae11e4d0ffd6cbc6c1e9211188bf980c54f59c61cb36d9d32628975ace153
-  data.tar.gz: 661a761e828644036057ec05d6711ddeb1462e9885de3baf8319b4e483ea8333
+  metadata.gz: b63212c9e8ada21f198021bc3537392d9a6a34933682ebe789923883c2f38131
+  data.tar.gz: 9afa24ef746a81f115628f65aff4bccfdbfbf3086887444d62409545be76b7fb
 SHA512:
-  metadata.gz: 48056be17c0be8068325457f25e64d4a38e38d9b3573cf707960348d5ebc53597ea6beb96edf5a7f96da593d8480539cae01d4852a2b1ee658cb6f29665562ab
-  data.tar.gz: e7277b27c830b40a5e3de5fbbd83d53b69ab02e463b42e00ba2a72eb82265b1e972a42656a264e448e18387442cd81989f0cb047cdf093f11322281722bacd27
+  metadata.gz: e21e172593fcee9340de7ca5ac37373db2d07479e2c912c01d7bf05399e012edcf405caf12c2cbf3ad0545b4ae8a166d6c98f40f67367e60040f818356866666
+  data.tar.gz: a3fcd6d6368c073621e9f400be5412b82e88ada5cce2b00a26b4e6697b97b6beb568564f64032c6c8eb777db93fe7afa3f324c616465e2913b838fd02ffa3eed

data/CHANGELOG.md

@@ -12,4 +12,16 @@
 ## [0.1.2] - 2024-09-24
 
 - Change validations for bulk_quotes method
-- Add `token` method to `Client` class
+- Add `token` method to `Client` class
+
+## [0.2.0] - 2024-09-30
+
+- 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
+
+## [0.2.1] - 2024-10-09
+
+- Fix broken tests
+- Add support for new optional parameters for `quotes` and `bulk_quotes` endpoint

data/Gemfile

@@ -7,4 +7,8 @@ gemspec
 
 gem "rake", "~> 13.0"
 
-gem "minitest", "~> 5.0"
+group :test do
+  gem "minitest", "~> 5.0"
+  gem 'simplecov', require: false
+  gem 'mocha'
+end

data/Gemfile.lock

@@ -1,13 +1,23 @@
 PATH
   remote: .
   specs:
-    market_data (0.1.0)
+    market_data (0.1.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    docile (1.4.1)
     minitest (5.16.3)
+    mocha (2.4.5)
+      ruby2_keywords (>= 0.0.5)
     rake (13.0.6)
+    ruby2_keywords (0.0.5)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
 
 PLATFORMS
   arm64-darwin-23
@@ -15,7 +25,9 @@ PLATFORMS
 DEPENDENCIES
   market_data!
   minitest (~> 5.0)
+  mocha
   rake (~> 13.0)
+  simplecov
 
 BUNDLED WITH
    2.4.1

data/README.md

@@ -1,34 +1,144 @@
 # MarketData
 
-TODO: Delete this and the text below, and describe your gem
+A Ruby wrapper for the [MarketData API](https://www.marketdata.app/docs/api).
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/market_data`. To experiment with that code, run `bin/console` for an interactive prompt.
+![coverage](https://img.shields.io/badge/coverage%3A-84.71%25-yellow.svg)
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+    $ gem install market_data
+    $ bundle install
 
-Install the gem and add to the application's Gemfile by executing:
+## Usage
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+You must instantiate a `MarketData::Client` before running any method. You'll need your MarketData API token first.
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+    $ client = MarketData::Client.new "YOUR_API_TOKEN"
+    
+    $ client.quote("AAPL")
+    $ => <struct MarketData::Models::Quote symbol="AAPL", ask=231.42, askSize=2, bid=231.4, .....
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+### 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 = cl.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.
+
+## 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)
+
+From Stocks endpoints:
+- [X] Stocks
+- [X] Bulk Stocks
+- [X] Candles
+- [X] Bulk Candles
+- [X] Support for new optional parameters for Quotes and Bulk Quotes
+- [ ] Earnings
+
+From Markets endpoints:
+- [ ] Status
+
+From Indices endpoints:
+- [ ] Quotes
+- [ ] Candles
+
+From Stocks endpoints:
+- [ ] Support for optional parameters for Candles
+- [ ] Support for optional parameters for Bulk Candles
 
-## Usage
 
-TODO: Write usage instructions here
+## Tests
 
-## Development
+Run tests with
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+    $ rake 
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To run tests and check coverage
 
+    $  rake && open coverage/index.html 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/market_data. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/market_data/blob/main/CODE_OF_CONDUCT.md).
+Leave an issue or contact me at sebagonz91@gmail.com
 
 ## License
 

data/lib/market_data/constants.rb

@@ -0,0 +1,13 @@
+module MarketData
+  module Constants
+    SECOND = 1
+    MINUTE = 60
+    HOUR = MINUTE * 60
+    DAY = HOUR * 24
+    WEEK = DAY * 7
+    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]
+  end
+end

data/lib/market_data/errors.rb

@@ -1,16 +1,30 @@
+require 'json'
+
 module MarketData
 
   class ClientError < StandardError;end
   class UnauthorizedError < ClientError; end
   class RateLimitedError < ClientError; end
   class BadParameterError < ClientError; end
+  class NotFoundError < ClientError; end
 
   module Errors
     def handle_error e
       er = e.io
+      parsed_info = JSON.parse(er.string)
       case er.status[0]
+      when "400"
+        if parsed_info["s"] == "error"
+          raise BadParameterError.new(parsed_info["errmsg"])
+        end
+        raise BadParameterError
+      when "404"
+        if parsed_info["s"] == "no_data"
+            raise NotFoundError.new("no candle information was found for the request")  
+        end
+        raise NotFoundError
       when "401"
-        raise UnauthorizedError
+        raise UnauthorizedError.new(parsed_info["errmsg"])
       when "429"
         raise RateLimitedError
       else 

data/lib/market_data/mappers.rb

@@ -0,0 +1,67 @@
+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),
+      )
+    end
+
+    def map_bulk_quotes response
+      h = Hash.new
+      size = response[SYMBOL_RESPONSE_KEY].size
+      for i in 0..(size - 1) do
+        qquote = map_quote(response, i)
+        h[response[SYMBOL_RESPONSE_KEY][i]] = !qquote.blank? ? qquote : nil
+      end
+      h
+    end
+
+    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
+        )
+      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])
+        h[response[SYMBOL_RESPONSE_KEY][i]] = !candle.blank? ? candle : nil
+      end
+      h
+    end
+  end
+end

data/lib/market_data/models.rb

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

data/lib/market_data/quotes.rb

@@ -1,61 +1,98 @@
 require 'market_data/conn'
 require 'market_data/errors'
+require 'market_data/mappers'
 
 module MarketData
   module Quotes
+    include MarketData::Mappers
     include MarketData::Errors
     include MarketData::Conn
 
-    SYMBOL_RESPONSE_KEY = "symbol"
-    STATUS_RESPONSE_KEY = "s"
-
-    QUOTE_FIELDS = [:symbol, :ask, :askSize, :bid, :bidSize, :mid, :last, :change, :changepct, :volume, :updated, :high52, :low52]
     @@single = "/v1/stocks/quotes/"
     @@bulk = "/v1/stocks/bulkquotes/"
+    @@candles = "/v1/stocks/candles/"
+    @@bulk_candles = "/v1/stocks/bulkcandles/"
 
-    # Quote is the struct to hold ticker request information
-    Quote = Struct.new(*QUOTE_FIELDS) do
-      def blank?
-        (QUOTE_FIELDS - [:symbol]).all? { |mmethod| self[mmethod].nil?}
-      end
-    end
-    
-    def quote(symbol, w52 = false)
+    def quote(symbol, w52 = false, extended = false)
       path_hash = { host: MarketData.base_host, path: @@single + symbol }
-        if w52
-          path_hash[:query] = URI.encode_www_form({"52week" => true })
-        end
-        res = do_connect(get_uri path_hash)
-        Quote.new(*res.except(STATUS_RESPONSE_KEY).values.map { |ar| ar[0] })
+      query_hash = {}
+      if w52
+        query_hash["52week"] = true
+      end
+      # MarketData API considers extended as true by default
+      if !extended
+        query_hash[:extended] = false
+      end
+      if !query_hash.empty?
+        path_hash[:query] = URI.encode_www_form(query_hash)
+      end
+      res = do_connect(get_uri path_hash)
+      map_quote(res)
     end
 
-    def bulk_quotes(symbols, snapshot = false)
+    def bulk_quotes(symbols, snapshot = false, extended = false)
       path_hash = { host: MarketData.base_host, path: @@bulk  }
       query_hash = {}
       
+      # MarketData API considers extended as true by default
+      if !extended
+        query_hash[:extended] = false
+      end
+
       if snapshot
         query_hash[:snapshot] = true
       else
-        if not symbols.is_a?(Array) || symbols.size < 1
+        if !symbols.is_a?(Array) || symbols.size < 1
           raise BadParameterError.new("symbols must be a non-empty list")
         end
-        query_hash = { symbols: symbols.join(",") }
+        query_hash[:symbols] = symbols.join(",")
       end
-      
       path_hash[:query] = URI.encode_www_form(query_hash)
 
       res = do_connect(get_uri path_hash)
-      Quotes.map_quotes(res)
+      map_bulk_quotes res
+    end
+  
+    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
+      
+      path_hash = { host: MarketData.base_host, path: @@candles + opts[:resolution] + "/" + symbol }
+      path_hash[:query] = URI.encode_www_form(query_hash)
+      
+      res = do_connect(get_uri path_hash)
+      map_candles res, symbol
     end
 
-    def self.map_quotes(quotes)
-      h = Hash.new
-      size = quotes[SYMBOL_RESPONSE_KEY].size
-      for i in 0..(size - 1) do
-        qquote = Quote.new(*quotes.except(STATUS_RESPONSE_KEY).values.map { |ar| ar[i] })
-        h[quotes[SYMBOL_RESPONSE_KEY][i]] = !qquote.blank? ? qquote : nil
+    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
+      path_hash = { host: MarketData.base_host, path: @@bulk_candles + resolution + "/" }
+      
+      if !symbols.is_a?(Array) || symbols.size < 1
+        raise BadParameterError.new("symbols must be a non-empty list")
       end
-      h
+      query_hash = { symbols: symbols.join(",") }
+
+      path_hash[:query] = URI.encode_www_form(query_hash)
+
+      res = do_connect(get_uri path_hash)
+      map_bulk_candles res
     end
   end
 end

data/lib/market_data/version.rb

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

data/lib/market_data.rb

@@ -13,10 +13,6 @@ module MarketData
     def initialize token
       @access_token = token
     end
-
-    def token
-      @access_token
-    end
   end
 
   def self.base_host

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: market_data
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Sebastián González
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-24 00:00:00.000000000 Z
+date: 2024-10-09 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby client for the MarketData API.
 email:
@@ -26,7 +26,10 @@ files:
 - Rakefile
 - lib/market_data.rb
 - lib/market_data/conn.rb
+- lib/market_data/constants.rb
 - lib/market_data/errors.rb
+- lib/market_data/mappers.rb
+- lib/market_data/models.rb
 - lib/market_data/quotes.rb
 - lib/market_data/version.rb
 - market_data.gemspec