Luke/backend/1036/snapshot v3 endpoint (#283)

* added client code and examples for new v3 snapshot endpoint

* chore: Updated coverage badge.

* adding a test for the v3 snapshot endpoint

* adding method comment for ListAssetSnapshots

* Adding proper types for response value

* fixed tests and added options response types

* aligned response models with models from API

* fixed failing test with model name change

* replaced ptime type with int64 and string for import issue

* refactored into test table with tests for stocks, options, and error case

* remove unneeded fields from test data, clean up test failure message

---------

Co-authored-by: GitHub Action <[email protected]>

.gitignore

@@ -13,3 +13,6 @@
 
 # Dependency directories
 vendor/
+
+# IntelliJ project settings
+.idea

README.md

@@ -1,5 +1,5 @@
 # Polygon Go Client
-![Coverage](https://img.shields.io/badge/Coverage-40.6%25-yellow)
+![Coverage](https://img.shields.io/badge/Coverage-40.4%25-yellow)
 
 <!-- todo: add a codecov badge -->
 <!-- todo: figure out a way to show all build statuses -->

rest/example/options/snapshots-assets/main.go

@@ -0,0 +1,30 @@
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+
+	polygon "github.com/polygon-io/client-go/rest"
+	"github.com/polygon-io/client-go/rest/models"
+)
+
+func main() {
+	// Init client
+	c := polygon.New(os.Getenv("POLYGON_API_KEY"))
+
+	// Set parameters
+	params := models.ListAssetSnapshotsParams{}.
+		WithTickerAnyOf("O:AAPL230512C00050000,O:META230512C00020000,O:F230512C00005000")
+
+	// Make request
+	iter := c.ListAssetSnapshots(context.Background(), params)
+
+	// do something with the result
+	for iter.Next() {
+		log.Println(iter.Item())
+	}
+	if iter.Err() != nil {
+		log.Fatal(iter.Err())
+	}
+}

rest/example/stocks/snapshots-assets/main.go

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+
+	polygon "github.com/polygon-io/client-go/rest"
+	"github.com/polygon-io/client-go/rest/models"
+)
+
+func main() {
+	// Init client
+	c := polygon.New(os.Getenv("POLYGON_API_KEY"))
+
+	// Set parameters
+	params := models.ListAssetSnapshotsParams{}.WithTickerAnyOf("AAPL,META,F")
+
+	// Make request
+	iter := c.ListAssetSnapshots(context.Background(), params)
+
+	// do something with the result
+	for iter.Next() {
+		log.Println(iter.Item())
+	}
+	if iter.Err() != nil {
+		log.Fatal(iter.Err())
+	}
+}

rest/models/snapshot.go

@@ -1,6 +1,8 @@
 package models
 
-import "strings"
+import (
+	"strings"
+)
 
 // GetAllTickersSnapshotParams is the set of parameters for the GetAllTickersSnapshot method.
 type GetAllTickersSnapshotParams struct {
@@ -378,3 +380,98 @@ type OrderBookQuote struct {
 	Price            float64            `json:"p,omitempty"`
 	ExchangeToShares map[string]float64 `json:"x,omitempty"`
 }
+
+type ListAssetSnapshotsParams struct {
+	TickerAnyOf *string `query:"ticker.any_of"`
+	Ticker      *string `query:"ticker"`
+
+	TickerLT  *string `query:"ticker.lt"`
+	TickerLTE *string `query:"ticker.lte"`
+	TickerGT  *string `query:"ticker.gt"`
+	TickerGTE *string `query:"ticker.gte"`
+
+	Type *string `query:"type"`
+}
+
+func (p ListAssetSnapshotsParams) WithTickerAnyOf(q string) *ListAssetSnapshotsParams {
+	p.TickerAnyOf = &q
+	return &p
+}
+
+func (p ListAssetSnapshotsParams) WithTicker(q string) *ListAssetSnapshotsParams {
+	p.Ticker = &q
+	return &p
+}
+
+func (p ListAssetSnapshotsParams) WithType(q string) *ListAssetSnapshotsParams {
+	p.Type = &q
+	return &p
+}
+
+func (p ListAssetSnapshotsParams) WithTickersByComparison(c Comparator, q string) *ListAssetSnapshotsParams {
+	switch c {
+	case LT:
+		p.TickerLT = &q
+	case LTE:
+		p.TickerLTE = &q
+	case GT:
+		p.TickerGT = &q
+	case GTE:
+		p.TickerGTE = &q
+	}
+	return &p
+}
+
+type ListAssetSnapshotsResponse struct {
+	BaseResponse
+	Results []SnapshotResponseModel `json:"results,omitempty"`
+}
+
+type SnapshotResponseModel struct {
+	Name         string            `json:"name,omitempty"`
+	MarketStatus string            `json:"market_status,omitempty"`
+	Ticker       string            `json:"ticker,omitempty"`
+	Type         string            `json:"type,omitempty"`
+	LastQuote    SnapshotLastQuote `json:"last_quote,omitempty"`
+	LastTrade    SnapshotLastTrade `json:"last_trade,omitempty"`
+	Session      Session           `json:"session,omitempty"`
+
+	BreakEvenPrice    float64         `json:"break_even_price,omitempty"`
+	Details           Details         `json:"details,omitempty"`
+	Greeks            Greeks          `json:"greeks,omitempty"`
+	ImpliedVolatility float64         `json:"implied_volatility,omitempty"`
+	OpenInterest      float64         `json:"open_interest,omitempty"`
+	UnderlyingAsset   UnderlyingAsset `json:"underlying_asset,omitempty"`
+
+	Error   string `json:"error"`
+	Message string `json:"message"`
+}
+
+type SnapshotLastQuote struct {
+	Ask         float64 `json:"ask,omitempty"`
+	AskSize     float64 `json:"ask_size,omitempty"`
+	Bid         float64 `json:"bid,omitempty"`
+	BidSize     float64 `json:"bid_size,omitempty"`
+	LastUpdated int64   `json:"last_updated,omitempty"`
+	Midpoint    float64 `json:"midpoint,omitempty"`
+	Timeframe   string  `json:"timeframe,omitempty"`
+}
+
+type SnapshotLastTrade struct {
+	Timestamp   int64   `json:"sip_timestamp,omitempty"`
+	Conditions  []int32 `json:"conditions,omitempty"`
+	Price       float64 `json:"price,omitempty"`
+	Size        uint32  `json:"size,omitempty"`
+	Exchange    int32   `json:"exchange,omitempty"`
+	Timeframe   string  `json:"timeframe,omitempty"`
+	ID          string  `json:"id,omitempty"`
+	LastUpdated int64   `json:"last_updated,omitempty"`
+}
+
+type Details struct {
+	ContractType      string  `json:"contract_type,omitempty"`
+	ExerciseStyle     string  `json:"exercise_style,omitempty"`
+	ExpirationDate    string  `json:"expiration_date,omitempty"`
+	SharesPerContract float64 `json:"shares_per_contract,omitempty"`
+	StrikePrice       float64 `json:"strike_price,omitempty"`
+}

rest/snapshot.go

@@ -17,6 +17,7 @@ const (
 	ListOptionsChainSnapshotPath  = "/v3/snapshot/options/{underlyingAsset}"
 	GetCryptoFullBookSnapshotPath = "/v2/snapshot/locale/global/markets/crypto/tickers/{ticker}/book"
 	GetIndicesSnapshotPath        = "/v3/snapshot/indices"
+	ListAssetSnapshots            = "/v3/snapshot"
 )
 
 // SnapshotClient defines a REST client for the Polygon snapshot API.
@@ -110,3 +111,24 @@ func (ac *SnapshotClient) GetIndicesSnapshot(ctx context.Context, params *models
 	err := ac.Call(ctx, http.MethodGet, GetIndicesSnapshotPath, params, res, opts...)
 	return res, err
 }
+
+// ListAssetSnapshots retrieves the snapshots for the specified tickers for the specified time. For more details see:
+// - https://staging.polygon.io/docs/stocks/get_v3_snapshot
+// - https://staging.polygon.io/docs/options/get_v3_snapshot
+//
+// This method returns an iterator that should be used to access the results via this pattern:
+//
+//	iter := c.ListAssetSnapshots(context, params, opts...)
+//	for iter.Next() {
+//		log.Print(iter.Item()) // do something with the current value
+//	}
+//	if iter.Err() != nil {
+//		return iter.Err()
+//	}
+func (ac *SnapshotClient) ListAssetSnapshots(ctx context.Context, params *models.ListAssetSnapshotsParams, options ...models.RequestOption) *iter.Iter[models.SnapshotResponseModel] {
+	return iter.NewIter(ctx, ListAssetSnapshots, params, func(uri string) (iter.ListResponse, []models.SnapshotResponseModel, error) {
+		res := &models.ListAssetSnapshotsResponse{}
+		err := ac.CallURL(ctx, http.MethodGet, uri, res, options...)
+		return res, res.Results, err
+	})
+}