FinnhubRB

📢 Caution

04-05-2020 - This library has been archived.

Finnhub is an API for retrieving Stock market data in JSON or CSV format. FinnhubRB is a wrapper Gem to use Finnhub with Ruby. FinnhubRB is based on the HTTP API of Finnhub.

To install FinnhubRB: gem install finnhubrb

To use it in your application: require "finnhub"

How to test

To test the Gem create a config.yml file inside the folder /spec with inside a line

key: [YOUR KEY]

Then run "rspec spec/test_all.rb".

Support

Without a premium account, testing is hard and I could have missed something. Any bug, suggestions and improvements are more than welcome. Please do not be shy to create issues or pull requests. Premium features are implemented but untested.
This is a personal project, any stars for giving your support will make a man happy.

Client

To contact Alpha Vantage you need to use a valid key that you can require from here.

To setup your clients use:

client = Finnhub::Client.new(key: "YOURKEY")

If you want to see the request that the client will do to Finnhub you can setup verbose equal to true.

  client.verbose = true # You can setup this during the initialization too

Stock

To analyse a stock you can start by choosing which stock exchange you want to analyse.

client.stock_exchanges # Retrieve the available stock exchanges on Finnhub (Finnhub::Stock_Exchange instances)
client.stock_exchanges(plain: true) # As above, but it returns simply the output of the request
stock_exchange = client.stock_exchanges(name: "NAME_CRYPTO_EXCHANGE") # Create a single instance of Finnhub::Stock_Exchange

After that you can choose in that crypto exchange which symbol you want to check.

stock_exchange.symbols # Retrieve the available stock symbols on the chosen stock exchange (Finnhub::Stock instances)
stock_exchange.symbols(plain: true) # As above, but it returns simply the output of the request

In alternative you can create a stock instance directly:.

stock = client.stock symbol: "AAPL"

Finnhub::Stock is used to manage a stock class. Several methods are available under this class:

  stock.symbol # Return the symbol
  stock.profile # (PREMIUM) Retrieve profile of the stock
  stock.profile(isin: "US5949181045") # (PREMIUM) Retrieve profile of the stock by its isin
  stock.profile(cusip: "023135106") # (PREMIUM) Retrieve profile of the stock by its cusip
  stock.ceo_compensation # Retrieve compensation of the stock's CEO
  stock.executive # Retrieve list of company's executives
  stock.recommendation # Retrieve recommendation about this stock
  stock.price_target # Retrieve price target about this stock
  stock.upgrade_downgrade # Retrieve latest stock upgrade and downgrade
  stock.option_chain # Retrieve option chain about this stock
  stock.earnings # Retrieve earnings about this stock
  stock.metrics # Retrieve key metrics
  stock.investors # Retrieve full list of investors
  stock.funds # Retrieve list of fund investors
  stock.financials # (PREMIUM) Retrieve standardized balances sheet
  stock.news # Retrieve news about this stock (only US)
  stock.major_development # Retrieve major development
  stock.sentiment # Retrieve social sentiment about this stock (only US)
  stock.peers(plain: true) # Retrieve peers company similar to the one chosen
  stock.peers # Like the previous one, but the results are Finnhub::Stock instances
  stock.pattern # Retrieve pattern
  stock.support_resistance # Retrieve support resistance
  stock.technical_indicators # Retrieve technical indicators
  stock.revenue_estimate # Retrieve revenue estimate
  stock.earnings_estimate  # Retrieve earnings estimate
  stock.earnings_calendar # Retrieve earnings calendar (you can add from and to)
  stock.dividends(from: Time.now-24*30*3600, to: Time.now) # Retrieve dividends
  stock.splits(from: Time.now-24*30*3600, to: Time.now) # Retrieve splits

To create a timeseries you can use:

  stock.timeseries(count: 100) # Return the last 100 entries (default count is 100)
  stock.timeseries(resolution: "D") # Resolution is daily "D", alternative are 1, 5, 15, 30, 60, D, W, M) where the numeric one are for minutes (default resolution is "D")
  stock.timeseries(from: Time.now-24*30*3600, to: Time.now) # Fetch from a date to another date (default from: nil, to: nil)
  stock.timeseries(format: "json") # Return the output in json or in csv (default format: "json")
  stock.timeseries(adjusted: true) # Return adjusted data (default false)

Remember count and from/to are exclusive. If you use one, you cannot use the other two. The methods "open", "high", "low", "close", "volume" and "status" will not work if you use format csv.

  timeseries = stock.timeseries(from: Time.now-24*30*3600, to: Time.now, resolution: 60)
  timeseries.output # Return output obtained from the request
  timeseries.timestamps # Return timestamps obtained from the request
  timeseries.open # Return open obtained from the request  
  timeseries.low # Return low obtained from the request
  timeseries.close # Return close obtained from the request
  timeseries.volume # Return volume obtained from the request
  timeseries.status # Return status obtained from the request

(PREMIUM) To manage tick data use:

  tick = stock.tick(from: Time.now-24*30*3600, to: Time.now) # Create stick data
  tick.output # Return output obtained from the request
  tick.timestamps # Return timestamps obtained from the request
  tick.price  # Return price  obtained from the request
  tick.volume # Return volume obtained from the request
  tick.status # Return status obtained from the request

(PREMIUM) To retrieve transcripts you can use:

client.transcripts # Retrieve the available transcripts on Finnhub (Finnhub::Transcript instances)
client.transcripts(plain: true) # As above, but it returns simply the output of the request
client.transcripts[0].transcript # Retrieve the specific transcript

To handle indicators you can do:

  timeseries = stock.indicator(from: Time.now-24*30*3600, to: Time.now, resolution: 60, indicator: "sma", args: {timeperiod: 3})
  timeseries.sma # Return technical values (in this case is sma since the indicator)
  timeseries.output # Return output obtained from the request
  timeseries.timestamps # Return timestamps obtained from the request
  timeseries.open # Return open obtained from the request  
  timeseries.low # Return low obtained from the request
  timeseries.close # Return close obtained from the request
  timeseries.volume # Return volume obtained from the request
  timeseries.status # Return status obtained from the request

Crypto

To analyse a crypto currency you should start by choosing which crypto exchange you want to analyse.

client.crypto_exchanges # Retrieve the available crypto exchanges on Finnhub (Finnhub::Crypto_Exchange instances)
client.crypto_exchanges(plain: true) # As above, but it returns simply the output of the request
crypto_exchange = client.crypto_exchange(name: "NAME_CRYPTO_EXCHANGE") # Create a single instance of Finnhub::Crypto_Exchange

After that you can choose, in that crypto exchange which symbol you want to check.

crypto_exchange.symbols # Retrieve the available crypto symbols on the chosen crypto exchange (Finnhub::Crypto_Symbol instances)
crypto_exchange.symbols(plain: true) # As above, but it returns simply the output of the request
crypto_symbol = crypto_exchange.symbol(symbol: "BTC") # Create a single instance of Finnhub::Crypto_Symbol

From crypto_symbol instance you can retrieve some interesting information.

crypto_symbol.exchange # Exchange of the crypto_symbol
crypto_symbol.hasWM # If it has week and month
crypto_symbol.displaySymbol # Displayed symbol
crypto_symbol.symbol # Symbol of the crypto currency

Furthermore you can create a timeseries with the same logic used for Stock timeseries.

  timeseries = crypto_symbol.timeseries(from: Time.now-24*30*3600, to: Time.now, resolution: 60)
  timeseries.output # Return output obtained from the request
  timeseris.timestamps # Return timestamps obtained from the request
  timeseries.open # Return open obtained from the request  
  timeseries.low # Return low obtained from the request
  timeseries.close # Return close obtained from the request
  timeseries.volume # Return volume obtained from the request
  timeseries.status # Return status obtained from the request

Forex

To analyse a forex exchange you should start by choosing which forex exchange you want to analyse.

client.forex_exchanges # Retrieve the available forex exchanges on Finnhub (Finnhub::Forex_Exchange instances)
client.forex_exchanges(plain: true) # As above, but it returns simply the output of the request
forex_exchange = client.forex_exchange(name: "NAME_FOREX_EXCHANGE") # Create a single instance of Finnhub::Forex_Exchange

After that you can choose, in that forex exchange which symbol you want to check.

forex_exchange.symbols # Retrieve the available forex symbols on the chosen forex exchange (Finnhub::Forex_Symbol instances)
forex_exchange.symbols(plain: true) # As above, but it returns simply the output of the request
forex_symbol = forex_exchange.symbol(symbol: "USD") # Create a single instance of Finnhub::Forex_Symbol

From forex_symbol instance you can retrieve some interesting information.

forex_symbol.exchange # Exchange of the crypto_symbol
forex_symbol.hasWM # If it has week and month
forex_symbol.displaySymbol # Displayed symbol
forex_symbol.symbol # Symbol of the crypto currency

Furthermore you can create a timeseries with the same logic used for Stock timeseries.

  timeseries = forex_symbol.timeseries(from: Time.now-24*30*3600, to: Time.now, resolution: 60)
  timeseries.output # Return output obtained from the request
  timeseris.timestamps # Return timestamps obtained from the request
  timeseries.open # Return open obtained from the request  
  timeseries.low # Return low obtained from the request
  timeseries.close # Return close obtained from the request
  timeseries.volume # Return volume obtained from the request
  timeseries.status # Return status obtained from the request

Merge

(PREMIUM) You can retrieve information about company that are merging in relation of a given country.

client.merge_countries # Retrieve the available merge countries on Finnhub (Finnhub::Merge_Country instances)
client.merge_countries(plain: true) # As above, but it returns simply the output of the request
country = client.merge_country(country: "France") # Create a single instance of Finnhub::Merge_Country
country.merger # Fetch information about the company that are going to merge

Economic Code

You can retrieve information about economic_codes.

client.economic_codes # Retrieve the available economic_codes on Finnhub (Finnhub::Economic_Code instances)
client.economic_codes(plain: true) # As above, but it returns simply the output of the request
economic = client.economic_code(code: "CODE") # Create a single instance of Finnhub::Economic_Code
economic.data # Data of economic_code
economic.data(plaint: true) # As above, but it returns simply the output of the request

News and calendar

You can retrieve news and calendar in the following way.

client.news(category: "forex") # Retrieve news by category (general, forex, crypto, merger) and by minId (default 0)
client.economic_calendar # Retrieve economic calendar
client.earnings_calendar # Retrieve earning calendar
client.ipo_calendar # Retrieve IPO calendar
client.ico_calendar # Retrieve ICO calendar

Websocket

Here an example of how to create websocket.

Thread.new do
  EM.run do
    websocket = client.websocket # Create websocket
    websocket.on :message do |event|
      result = event.data # Result is not parsed
    end
    websocket.on :close do |event|
      result = [:close, event.code, event.reason]
      websocket = nil
    end  
  end
end

websocket.subscribe("AAPL") # Subscribe to a stock
websocket.unsubscribe("AAPL") # Unubscribe to a stock

The symbol under subscribe/unsubscribe can be a string of a stock, a crypto_symbol or a forex_symbol. Or in alternative can be a Finnhub::Stock, Finnhub::Crypto_Symbol, or a Finnhub::Forex_Symbol instance.

Webhook

You can manage the webhook in the following way.

webhook = client.webhook # Instantiate a webhook
webhook.create(body: {'event': 'earnings', 'symbol': 'AAPL'}) # Create a new webhook
webhook.id #Retrieve id of the webhook
client.webhooks # List webhooks
client.webhooks(plain: true)  # As above, but it returns simply the output of the request
webhook.delete # Delete webhook

Other

client.covid # Retrieve United States Covid-19 info

Errors

Error from FinnhubRB are returned under Finnhub::Error exception. You can use e.code to retrieve the code returned to a not successful request.

finnhubrb

Development

Runtime