Add options data retrieval and some documentation.

Author: ackleymi

README.md

@@ -39,7 +39,7 @@ I've taken features from the following projects, chosen for their stability, wid
 - [x] Single security quote history (yahoo)
 - [x] Single security dividend/split history (yahoo)
 - [x] Symbols download (bats)
-- [ ] Option chains (yahoo)
+- [x] Option chains (google)
 - [x] Currency pairs quotes
 - [ ] International securities quotes
 - [ ] Sector/Industry components
@@ -164,7 +164,57 @@ func main() {
 
 ```
 
+### Options chains
 
+```go
+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)
+	}
+
+	// Fetches puts and calls for the closest expiration date.
+	err = chain.FetchOptionsExpiringNext()
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(chain.Calls)
+	fmt.Println(chain.Puts)
+
+}
+
+```
+
+### Currency pairs quotes
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/FlashBoys/go-finance"
+)
+
+func main() {
+
+	// Fetches the quote for USD/GBP pair.
+	quote := finance.GetCurrencyPairQuote(finance.USDGBP)
+	fmt.Println(quote)
+}
+
+```
 
 
 
@@ -175,4 +225,4 @@ Given Yahoo! Finance's own perpetuation of a rabbit warren -like system of finan
 
 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, those concepts are not the focus of this project. A good place to start there would be [Gota](https://github.com/kniren/gota). In the future, tabular data will be the focus! I just have to determine the easiest way to integrate it in my current projects.
 
-Yahoo also does not currently support a way to download a master list of symbols available. I compromised and am using BATS list for now.
+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.

chain.go

@@ -8,8 +8,7 @@ import (
 
 func main() {
 
-	// Request all BATS symbols.
-	q := finance.GetCurrencyPairQuote(finance.USDGBP)
-	fmt.Println(q)
-
+	// Fetches the quote for USD/GBP pair.
+	quote := finance.GetCurrencyPairQuote(finance.USDGBP)
+	fmt.Println(quote)
 }

cmd/main.go

@@ -0,0 +1,50 @@
+package models
+
+import "github.com/shopspring/decimal"
+
+// Contract represents an instance of an option contract.
+type Contract 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
+}
+
+// NewContract creates a new instance of an options contract.
+func NewContract(option map[string]string) Contract {
+
+	c := Contract{
+		ContractID:    option["cid"],
+		Security:      option["s"],
+		Strike:        ToDecimal(option["strike"]),
+		Price:         ToDecimal(option["p"]),
+		ChangeNominal: ToDecimal(option["c"]),
+		Bid:           ToDecimal(option["b"]),
+		Ask:           ToDecimal(option["a"]),
+		Volume:        ToInt(option["vol"]),
+		OpenInterest:  ToInt(option["oi"]),
+	}
+
+	if c.Price.IntPart() != 0 {
+		hundred, _ := decimal.NewFromString("100")
+		c.ChangePercent = ((c.ChangeNominal).Div(c.Price.Sub(c.ChangeNominal))).Mul(hundred).Truncate(2)
+	}
+
+	return c
+}
+
+// NewContractSlice creates a new slice of contracts.
+func NewContractSlice(options []map[string]string) (contracts []Contract) {
+
+	for _, op := range options {
+		contracts = append(contracts, NewContract(op))
+	}
+
+	return contracts
+}

models/contract.go

@@ -24,7 +24,7 @@ func ToFloat(value interface{}) float64 {
 // ToInt converts a string to an int.
 func ToInt(value string) int {
 
-	if value == "N/A" {
+	if value == "N/A" || value == "-" {
 		return 0
 	}
 
@@ -38,7 +38,7 @@ func ToInt(value string) int {
 // ToDecimal converts a string to a decimal value.
 func ToDecimal(value string) decimal.Decimal {
 
-	if value == "N/A" {
+	if value == "N/A" || value == "-" {
 		return decimal.Decimal{}
 	}
 

models/derivative.go

@@ -0,0 +1,111 @@
+package finance
+
+import (
+	"encoding/json"
+	"strconv"
+	"time"
+
+	"github.com/FlashBoys/go-finance/models"
+	"github.com/shopspring/decimal"
+)
+
+const (
+	optionsURL = "http://www.google.com/finance/option_chain?"
+)
+
+// OptionChain contains the option contracts for a given symbol and expiration.
+type OptionChain struct {
+	Symbol          string
+	Expirations     []time.Time
+	UnderlyingPrice decimal.Decimal
+	Calls           []models.Contract
+	Puts            []models.Contract
+}
+
+type timeMap struct {
+	Month string `json:"m"`
+	Day   string `json:"d"`
+	Year  string `json:"y"`
+}
+
+type fetchResult struct {
+	Expiry      json.RawMessage     `json:"expiry"`
+	Expirations []timeMap           `json:"expirations"`
+	Underlying  json.RawMessage     `json:"underlying_id"`
+	Price       string              `json:"underlying_price"`
+	Calls       []map[string]string `json:"calls,omitempty"`
+	Puts        []map[string]string `json:"puts,omitempty"`
+}
+
+// NewOptionsChain creates a new OptionChain instance.
+func NewOptionsChain(symbol string) (oc *OptionChain, err error) {
+
+	oc = &OptionChain{Symbol: symbol}
+	oc.Expirations, oc.UnderlyingPrice, err = fetchExpirations(symbol)
+
+	return oc, err
+}
+
+func fetchExpirations(symbol string) (expirations []time.Time, price decimal.Decimal, err error) {
+
+	params := map[string]string{
+		"q":      symbol,
+		"expd":   "4",
+		"expm":   "4",
+		"expy":   "2014",
+		"output": "json",
+	}
+
+	url := buildURL(optionsURL, params)
+	b, err := request(url)
+	if err != nil {
+		return expirations, price, err
+	}
+
+	var fr fetchResult
+	err = json.Unmarshal(b, &fr)
+	if err != nil {
+		return expirations, price, err
+	}
+
+	for _, t := range fr.Expirations {
+		dString := t.Month + "/" + t.Day + "/" + t.Year
+		expirations = append(expirations, models.ParseDate(dString))
+	}
+
+	price = models.ToDecimal(fr.Price)
+
+	return expirations, price, err
+}
+
+// FetchOptionsExpiringNext fetches calls and puts with the shortest expiration date.
+func (chain *OptionChain) FetchOptionsExpiringNext() (err error) {
+
+	expiry := chain.Expirations[0]
+
+	params := map[string]string{
+		"q":      chain.Symbol,
+		"expd":   strconv.Itoa(expiry.Day()),
+		"expm":   strconv.Itoa(int(expiry.Month())),
+		"expy":   strconv.Itoa(expiry.Year()),
+		"output": "json",
+	}
+
+	url := buildURL(optionsURL, params)
+
+	b, err := request(url)
+	if err != nil {
+		return err
+	}
+
+	var fr fetchResult
+	err = json.Unmarshal(b, &fr)
+	if err != nil {
+		return err
+	}
+
+	chain.Calls = models.NewContractSlice(fr.Calls)
+	chain.Puts = models.NewContractSlice(fr.Puts)
+
+	return err
+}

models/utils.go

@@ -2,8 +2,15 @@ package finance
 
 import (
 	"encoding/csv"
+	"io/ioutil"
 	"net/http"
 	"net/url"
+	"regexp"
+)
+
+var (
+	firstRegex  = regexp.MustCompile(`(\w+:)(\d+\.?\d*)`)
+	secondRegex = regexp.MustCompile(`(\w+):`)
 )
 
 // requestCSV fetches a csv from a supplied URL.
@@ -35,3 +42,25 @@ func buildURL(base string, params map[string]string) string {
 
 	return url.String()
 }
+
+// request fetches a file from a supplied URL.
+func request(url string) ([]byte, error) {
+	resp, err := http.Get(url)
+	if err != nil {
+		return []byte{}, err
+	}
+	defer resp.Body.Close()
+	contents, err := ioutil.ReadAll(resp.Body)
+	if err != nil {
+		return []byte{}, err
+	}
+	result := string(contents)
+
+	return transformResult(result), err
+}
+
+func transformResult(input string) []byte {
+
+	json := firstRegex.ReplaceAllString(input, "$1\"$2\"")
+	return []byte(secondRegex.ReplaceAllString(json, "\"$1\":"))
+}