finance

README

go-finance

go-finance is a Golang library for retrieving financial data for quantitative analysis.

To install go-finance, use the following command:

go get github.com/FlashBoys/go-finance

Features

Single security quotes

package main

import (
	"fmt"

	"github.com/FlashBoys/go-finance"
)

func main() {
	// 15-min delayed full quote for Apple.
	q, err := finance.GetQuote("AAPL")
	if err == nil {
		fmt.Println(q)
	}
}

Multiple securities quotes

package main

import (
	"fmt"

	"github.com/FlashBoys/go-finance"
)

func main() {
	// 15-min delayed full quotes for Apple, Twitter, and Facebook.
	symbols := []string{"AAPL", "TWTR", "FB"}
	quotes, err := finance.GetQuotes(symbols)
	if err == nil {
		fmt.Println(quotes)
	}
}

Quote history

package main

import (
	"fmt"
	"time"

	"github.com/FlashBoys/go-finance"
)

func main() {
	// Set time bounds to 1 month starting Jan. 1.
	start, _ := time.Parse(time.RFC3339, "2016-01-01T16:00:00+00:00")
	end := start.AddDate(0, 1, 0)
	
	// Request daily history for TWTR.
	// IntervalDaily OR IntervalWeekly OR IntervalMonthly are supported.
	bars, err := finance.GetQuoteHistory("TWTR", start, end, finance.IntervalDaily)
	if err == nil {
		fmt.Println(bars)
	}
}

Dividend/Split history

package main

import (
	"fmt"
	"time"

	"github.com/FlashBoys/go-finance"
)

func main() {
	// Set time range from Jan 2010 up to the current date.
	// This example will return a slice of both dividends and splits.
	start, _ := time.Parse(time.RFC3339, "2010-01-01T16:00:00+00:00")
	end := time.Now()
	
	// Request event history for AAPL.
	events, err := finance.GetDividendSplitHistory("AAPL", start, end)
	if err == nil {
		fmt.Println(events)
	}
}

Symbols download

package main

import (
	"fmt"

	"github.com/FlashBoys/go-finance"
)

func main() {
	// Request all BATS symbols.
	symbols, err := finance.GetUSEquitySymbols()
	if err == nil {
		fmt.Println(symbols)
	}
}

Options chains

package main

import (
	"fmt"

	"github.com/FlashBoys/go-finance"
)

func main() {
	// Fetches the available expiration dates.
	chain, err := finance.NewOptionsChain("AAPL")
	if err != nil {
		panic(err)
	}

	// Some examples - see docs for full explanation.

	// Fetches puts and calls for the closest expiration date.
	calls, puts, err := chain.GetOptionsExpiringNext()
	if err == nil {
		panic(err)
  	}
	fmt.Println(calls)
	fmt.Println(puts)

	// Fetches puts and calls for the specified expiration date.
	calls, puts, err := chain.GetOptionsForExpiration(chain.Expirations[1])
	if err == nil {
		panic(err)
	}
	fmt.Println(calls)
	fmt.Println(puts)

	// Fetches calls for the specified expiration date.
	calls, err := chain.GetCallsForExpiration(chain.Expirations[1])
	if err == nil {
		panic(err)
	}
	fmt.Println(calls)
}

Currency pairs quotes

package main

import (
	"fmt"

	"github.com/FlashBoys/go-finance"
)

func main() {
	// Fetches the quote for USD/GBP pair.
	pq, err := finance.GetCurrencyPairQuote(finance.USDGBP)
	if err == nil {
		fmt.Println(pq)
	}
}

Intentions

go-finance aims to provide a clean, flexible way to retrieve financial data for your own projects. This is accomplished through an implementation of the full suite of Yahoo! Finance APIs and other sources. After much consideration and exploration of the labyrinthian endpoint system in the Yahoo Finance ecosystem, I've done my best to select and document proper consumption of the seemingly most stable endpoints. The primary technical tenants of this project are:

• Make financial data easy and fun to work with in Go-lang.
• Abstract the burden of non-sexy model serialization away from the end-user.
• Provide a mature framework where the end-user needs only be concerned with analysis instead of data sourcing.

There are several applications for this library. It's intentions are to be conducive to the following activities:

• Quantitative financial analysis in Golang.
• Academic study/comparison in a clean, easy language.
• Algorithmic/Statistical-based strategy implementation.

To-do

• Add greeks calculations to options data
• International securities quotes
• Sector/Industry components
• Indicies components
• Key stats (full profile) for securities

Limitations (currently)

Given Yahoo! Finance's own perpetuation of a rabbit warren -like system of financial data YQL tables in varying degrees of deprecation, conflation/real time, exchange availability, protocol access, and overall lack of consistent usage guidelines/documentation, I advise users of this library to be aware that you should not depend on its returning data to you 100% of the time. Build fail-safes and back-up plans into your own systems tasked with handling these cases as they arise. You should also probably complain to Yahoo to build better financial engineering tools since so many of us depend on them.

While dataframes (tabular data structures used for analytical operations atypical of what you see in the beaten track of web programming) are popular in the financial development community for use in prototyping models, those concepts are not the current focus of this project.

Yahoo also does not currently support a way to download a master list of symbols available. I compromised and am using the BATS list for now.

Contributing

If you find this repo helpful, please give it a star. If you wish to discuss changes to it, please open an issue! This project is not as mature as it could be, and financial projects in Golang are in drastic need of some basic helpful dependencies as this repo aims to be.

Similar Projects

I've taken features from the following projects, chosen for their stability, wide-spread usage, completeness and accuracy of the financial data we know to be publicly available, as well as how much I like using them in other projects given their own concise syntax inherent in their own design:

• pandas datareader (Python) wide-spread use in academia.
• yahoofinance-api (Java) most popular java library for this purpose.
• quantmod (R) a package for development/testing/deployment of quant strategy.

Documentation

Overview

Package finance implements a growing set of financial data retrieval functions. It aims to provide a clean, flexible, and easy way to pull in basic financial markets quotes and information for analytical purposes.

Features

- Single security quotes

- Multiple security quotes

- Historical quotes in custom time frames and intervals

- Dividend and Split history

- FX pair quotes for all major pairs

- Option chains for multiple future expiration dates

- Updating symbols list of traded US Equities

Index

• Constants
• func GetUSEquitySymbols() ([]string, error)
• type Bar
  • func GetQuoteHistory(symbol string, start time.Time, end time.Time, interval Interval) (bars []*Bar, err error)
• type Event
  • func GetDividendSplitHistory(symbol string, start time.Time, end time.Time) (events []*Event, err error)
• type Expiration
  • func ExpirationFromDate(date time.Time) *Expiration
  • func NewExpiration(month, day, year string) *Expiration
• type FXPairQuote
  • func GetCurrencyPairQuote(symbol string) (*FXPairQuote, error)
• type Interval
• type Option
• type OptionChain
  • func NewOptionsChain(symbol string) (oc *OptionChain, err error)
  • func (chain *OptionChain) GetCallsForExpiration(e *Expiration) (calls []*Option, err error)
  • func (chain *OptionChain) GetExpirations() []*Expiration
  • func (chain *OptionChain) GetOptionsExpiringNext() (calls []*Option, puts []*Option, err error)
  • func (chain *OptionChain) GetOptionsForExpiration(e *Expiration) (calls []*Option, puts []*Option, err error)
  • func (chain *OptionChain) GetPutsForExpiration(e *Expiration) (puts []*Option, err error)
  • func (chain *OptionChain) GetStrikes() (strikes []decimal.Decimal, err error)
• type Quote
  • func GetQuote(symbol string) (*Quote, error)
  • func GetQuotes(symbols []string) ([]*Quote, error)

Constants

const (
	// Dividend constant.
	Dividend = "DIVIDEND"
	// Split constant.
	Split = "SPLIT"
)

const (
	// IntervalDaily daily interval.
	IntervalDaily = "d"
	// IntervalWeekly weekly interval.
	IntervalWeekly = "w"
	// IntervalMonthly monthly interval.
	IntervalMonthly = "m"
)

const (
	// USDGBP pair.
	USDGBP = "USDGBP=X"
	// USDEUR pair.
	USDEUR = "USDEUR=X"
	// USDAUD pair.
	USDAUD = "USDAUD=X"
	// USDCHF pair.
	USDCHF = "USDCHF=X"
	// USDJPY pair.
	USDJPY = "USDJPY=X"
	// USDCAD pair.
	USDCAD = "USDCAD=X"
	// USDSGD pair.
	USDSGD = "USDSGD=X"
	// USDNZD pair.
	USDNZD = "USDNZD=X"
	// USDHKD pair.
	USDHKD = "USDHKD=X"
	// GBPUSD pair.
	GBPUSD = "GBPUSD=X"
	// GBPEUR pair.
	GBPEUR = "GBPEUR=X"
	// GBPAUD pair.
	GBPAUD = "GBPAUD=X"
	// GBPCHF pair.
	GBPCHF = "GBPCHF=X"
	// GBPJPY pair.
	GBPJPY = "GBPJPY=X"
	// GBPCAD pair.
	GBPCAD = "GBPCAD=X"
	// GBPSGD pair.
	GBPSGD = "GBPSGD=X"
	// GBPNZD pair.
	GBPNZD = "GBPNZD=X"
	// GBPHKD pair.
	GBPHKD = "GBPHKD=X"
	// EURUSD pair.
	EURUSD = "EURUSD=X"
	// EURGBP pair.
	EURGBP = "EURGBP=X"
	// EURAUD pair.
	EURAUD = "EURAUD=X"
	// EURCHF pair.
	EURCHF = "EURCHF=X"
	// EURJPY pair.
	EURJPY = "EURJPY=X"
	// EURCAD pair.
	EURCAD = "EURCAD=X"
	// EURSGD pair.
	EURSGD = "EURSGD=X"
	// EURNZD pair.
	EURNZD = "EURNZD=X"
	// EURHKD pair.
	EURHKD = "EURHKD=X"
	// AUDUSD pair.
	AUDUSD = "AUDUSD=X"
	// AUDGBP pair.
	AUDGBP = "AUDGBP=X"
	// AUDEUR pair.
	AUDEUR = "AUDEUR=X"
	// AUDCHF pair.
	AUDCHF = "AUDCHF=X"
	// AUDJPY pair.
	AUDJPY = "AUDJPY=X"
	// AUDCAD pair.
	AUDCAD = "AUDCAD=X"
	// AUDSGD pair.
	AUDSGD = "AUDSGD=X"
	// AUDNZD pair.
	AUDNZD = "AUDNZD=X"
	// AUDHKD pair.
	AUDHKD = "AUDHKD=X"
	// CHFGBP pair.
	CHFGBP = "CHFGBP=X"
	// CHFEUR pair.
	CHFEUR = "CHFEUR=X"
	// CHFAUD pair.
	CHFAUD = "CHFAUD=X"
	// CHFJPY pair.
	CHFJPY = "CHFJPY=X"
	// CHFCAD pair.
	CHFCAD = "CHFCAD=X"
	// CHFSGD pair.
	CHFSGD = "CHFSGD=X"
	// CHFNZD pair.
	CHFNZD = "CHFNZD=X"
	// CHFHKD pair.
	CHFHKD = "CHFHKD=X"
	// JPYUSD pair.
	JPYUSD = "JPYUSD=X"
	// JPYGBP pair.
	JPYGBP = "JPYGBP=X"
	// JPYEUR pair.
	JPYEUR = "JPYEUR=X"
	// JPYAUD pair.
	JPYAUD = "JPYAUD=X"
	// JPYCHF pair.
	JPYCHF = "JPYCHF=X"
	// JPYCAD pair.
	JPYCAD = "JPYCAD=X"
	// JPYSGD pair.
	JPYSGD = "JPYSGD=X"
	// JPYNZD pair.
	JPYNZD = "JPYNZD=X"
	// JPYHKD pair.
	JPYHKD = "JPYHKD=X"
	// CADUSD pair.
	CADUSD = "CADUSD=X"
	// CADGBP pair.
	CADGBP = "CADGBP=X"
	// CADEUR pair.
	CADEUR = "CADEUR=X"
	// CADAUD pair.
	CADAUD = "CADAUD=X"
	// CADCHF pair.
	CADCHF = "CADCHF=X"
	// CADJPY pair.
	CADJPY = "CADJPY=X"
	// CADSGD pair.
	CADSGD = "CADSGD=X"
	// CADNZD pair.
	CADNZD = "CADNZD=X"
	// CADHKD pair.
	CADHKD = "CADHKD=X"
	// SGDUSD pair.
	SGDUSD = "SGDUSD=X"
	// SGDGBP pair.
	SGDGBP = "SGDGBP=X"
	// SGDEUR pair.
	SGDEUR = "SGDEUR=X"
	// SGDAUD pair.
	SGDAUD = "SGDAUD=X"
	// SGDCHF pair.
	SGDCHF = "SGDCHF=X"
	// SGDJPY pair.
	SGDJPY = "SGDJPY=X"
	// SGDCAD pair.
	SGDCAD = "SGDCAD=X"
	// SGDNZD pair.
	SGDNZD = "SGDNZD=X"
	// SGDHKD pair.
	SGDHKD = "SGDHKD=X"
	// NZDUSD pair.
	NZDUSD = "NZDUSD=X"
	// NZDGBP pair.
	NZDGBP = "NZDGBP=X"
	// NZDEUR pair.
	NZDEUR = "NZDEUR=X"
	// NZDAUD pair.
	NZDAUD = "NZDAUD=X"
	// NZDCHF pair.
	NZDCHF = "NZDCHF=X"
	// NZDJPY pair.
	NZDJPY = "NZDJPY=X"
	// NZDCAD pair.
	NZDCAD = "NZDCAD=X"
	// NZDSGD pair.
	NZDSGD = "NZDSGD=X"
	// NZDHKD pair.
	NZDHKD = "NZDHKD=X"
	// HKDUSD pair.
	HKDUSD = "HKDUSD=X"
	// HKDGBP pair.
	HKDGBP = "HKDGBP=X"
	// HKDEUR pair.
	HKDEUR = "HKDEUR=X"
	// HKDAUD pair.
	HKDAUD = "HKDAUD=X"
	// HKDCHF pair.
	HKDCHF = "HKDCHF=X"
	// HKDJPY pair.
	HKDJPY = "HKDJPY=X"
	// HKDCAD pair.
	HKDCAD = "HKDCAD=X"
	// HKDSGD pair.
	HKDSGD = "HKDSGD=X"
	// HKDNZD pair.
	HKDNZD = "HKDNZD=X"
)

Functions

func GetUSEquitySymbols

func GetUSEquitySymbols() ([]string, error)

GetUSEquitySymbols fetches the symbols available through BATS, ~8k symbols.

Types

type Bar

type Bar struct {
	Symbol   string
	Date     time.Time
	Open     decimal.Decimal
	High     decimal.Decimal
	Low      decimal.Decimal
	Close    decimal.Decimal
	Volume   int
	AdjClose decimal.Decimal
}

Bar represents a single bar(candle) in time-series of quotes.

func GetQuoteHistory

func GetQuoteHistory(symbol string, start time.Time, end time.Time, interval Interval) (bars []*Bar, err error)

GetQuoteHistory fetches a single symbol's quote history from Yahoo Finance.

type Event

type Event struct {
	Symbol      string
	EventType   string
	Date        time.Time
	DividendAmt decimal.Decimal
	SplitRatio  string
}

Event contains one historical event (either a split or a dividend).

func GetDividendSplitHistory

func GetDividendSplitHistory(symbol string, start time.Time, end time.Time) (events []*Event, err error)

GetDividendSplitHistory fetches a single symbol's dividend and split history from Yahoo Finance.

type Expiration

type Expiration struct {
	Month string    `json:"m"`
	Day   string    `json:"d"`
	Year  string    `json:"y"`
	Date  time.Time `json:",omitempty"`
}

Expiration is a date for options expiry.

func ExpirationFromDate

func ExpirationFromDate(date time.Time) *Expiration

ExpirationFromDate builds an expiration object from a proper date.

func NewExpiration

func NewExpiration(month, day, year string) *Expiration

NewExpiration builds an expiration object from month-day-year strings.

type FXPairQuote

type FXPairQuote struct {
	Symbol           string
	PairName         string
	LastTime         time.Time
	LastRate         decimal.Decimal
	ChangeNominal    decimal.Decimal
	ChangePercent    decimal.Decimal
	DayLow           decimal.Decimal
	DayHigh          decimal.Decimal
	FiftyTwoWeekLow  decimal.Decimal
	FiftyTwoWeekHigh decimal.Decimal
}

FXPairQuote represents the quote of a currency pair.

func GetCurrencyPairQuote

func GetCurrencyPairQuote(symbol string) (*FXPairQuote, error)

GetCurrencyPairQuote fetches a single currency pair's quote from Yahoo Finance.

type Interval

type Interval string

Interval is the duration of the bars returned from the query.

type Option

type Option struct {
	ContractID    string
	Security      string
	Strike        decimal.Decimal
	Price         decimal.Decimal
	ChangeNominal decimal.Decimal
	ChangePercent decimal.Decimal
	Bid           decimal.Decimal
	Ask           decimal.Decimal
	Volume        int
	OpenInterest  int
}

Option represents an instance of an option contract.

type OptionChain

type OptionChain struct {
	Symbol          string
	UnderlyingPrice decimal.Decimal
	Expirations     []*Expiration
}

OptionChain contains the option contracts for a given symbol and expiration.

func NewOptionsChain

func NewOptionsChain(symbol string) (oc *OptionChain, err error)

NewOptionsChain creates a new OptionChain instance.

func (*OptionChain) GetCallsForExpiration

func (chain *OptionChain) GetCallsForExpiration(e *Expiration) (calls []*Option, err error)

GetCallsForExpiration fetches calls for the given expiration date.

func (*OptionChain) GetExpirations

func (chain *OptionChain) GetExpirations() []*Expiration

GetExpirations returns the specified option's expirations

func (*OptionChain) GetOptionsExpiringNext

func (chain *OptionChain) GetOptionsExpiringNext() (calls []*Option, puts []*Option, err error)

GetOptionsExpiringNext fetches calls and puts with the shortest expiration date.

func (*OptionChain) GetOptionsForExpiration

func (chain *OptionChain) GetOptionsForExpiration(e *Expiration) (calls []*Option, puts []*Option, err error)

GetOptionsForExpiration fetches calls and puts for the given expiration date.

func (*OptionChain) GetPutsForExpiration

func (chain *OptionChain) GetPutsForExpiration(e *Expiration) (puts []*Option, err error)

GetPutsForExpiration fetches puts for the given expiration date.

func (*OptionChain) GetStrikes

func (chain *OptionChain) GetStrikes() (strikes []decimal.Decimal, err error)

GetStrikes returns the specified option's strikes.

type Quote

type Quote struct {
	Symbol             string
	Name               string
	LastTradeTime      time.Time
	LastTradePrice     decimal.Decimal
	LastTradeSize      int
	Ask                decimal.Decimal
	AskSize            int
	Bid                decimal.Decimal
	BidSize            int
	Volume             int
	ChangeNominal      decimal.Decimal
	ChangePercent      decimal.Decimal
	Open               decimal.Decimal
	PreviousClose      decimal.Decimal
	Exchange           string
	DayLow             decimal.Decimal
	DayHigh            decimal.Decimal
	FiftyTwoWeekLow    decimal.Decimal
	FiftyTwoWeekHigh   decimal.Decimal
	Currency           string
	MarketCap          string
	FiftyDayMA         decimal.Decimal
	TwoHundredDayMA    decimal.Decimal
	AvgDailyVolume     int
	FiftyTwoWeekTarget decimal.Decimal
	ShortRatio         decimal.Decimal
	BookValue          decimal.Decimal
	EBITDA             string
	PriceSales         decimal.Decimal
	PriceBook          decimal.Decimal
	PERatio            decimal.Decimal
	PEGRatio           decimal.Decimal
	DivYield           decimal.Decimal
	DivPerShare        decimal.Decimal
	DivExDate          time.Time
	DivPayDate         time.Time
	EPS                decimal.Decimal
	EPSEstCurrentYear  decimal.Decimal
	EPSEstNextYear     decimal.Decimal
	EPSEstNextQuarter  decimal.Decimal
}

Quote is the object that is returned for a quote inquiry.

func GetQuote

func GetQuote(symbol string) (*Quote, error)

GetQuote fetches a single symbol's quote from Yahoo Finance.

func GetQuotes

func GetQuotes(symbols []string) ([]*Quote, error)

GetQuotes fetches multiple symbol's quotes from Yahoo Finance.