Skip to content

ticker

import "github.com/wnjoon/go-yfinance/pkg/ticker"

Package ticker provides the main interface for accessing Yahoo Finance data.

Overview

The ticker package is the primary entry point for go-yfinance. It provides a Ticker type that represents a single stock, ETF, or fund, and offers methods to fetch various types of financial data.

Quick Start

import "github.com/wnjoon/go-yfinance/pkg/ticker"

// Create a ticker
t, err := ticker.New("AAPL")
if err != nil {
    log.Fatal(err)
}
defer t.Close()

// Get current quote
quote, err := t.Quote()

// Get historical data
history, err := t.History(models.HistoryParams{
    Period:   "1mo",
    Interval: "1d",
})

Available Data

The Ticker type provides methods for:

Caching

The Ticker automatically caches API responses to minimize redundant requests. Use Ticker.ClearCache to force a refresh of cached data.

Thread Safety

All Ticker methods are safe for concurrent use from multiple goroutines.

Index

type Option

Option is a function that configures a Ticker.

type Option func(*Ticker)

func WithClient

func WithClient(c *client.Client) Option

WithClient sets a custom client for the Ticker.

type Ticker

Ticker represents a single stock/ETF/fund ticker.

type Ticker struct {
    // contains filtered or unexported fields
}

func New

func New(symbol string, opts ...Option) (*Ticker, error)

New creates a new Ticker for the given symbol.

func (*Ticker) Actions

func (t *Ticker) Actions() (*models.Actions, error)

Actions returns dividends, splits, and capital gains for the ticker.

This is a convenience method that combines the action event series into a single response.

func (*Ticker) AnalystPriceTargets

func (t *Ticker) AnalystPriceTargets() (*models.PriceTarget, error)

AnalystPriceTargets returns analyst price targets. This method name matches Python yfinance's ticker.analyst_price_targets property.

func (*Ticker) BalanceSheet

func (t *Ticker) BalanceSheet(freq string) (*models.FinancialStatement, error)

BalanceSheet returns the balance sheet data.

Parameters:

  • freq: "annual", "yearly", or "quarterly" (default: "annual")

Note: "yearly" is accepted as an alias for "annual" for Python yfinance compatibility.

The returned [models.FinancialStatement] contains fields like TotalAssets, TotalLiabilities, TotalEquity, CashAndCashEquivalents, TotalDebt, and WorkingCapital.

Example:

balance, err := ticker.BalanceSheet("quarterly")
if assets, ok := balance.GetLatest("TotalAssets"); ok {
    fmt.Printf("Total Assets: %.2f\n", assets)
}

func (*Ticker) Calendar

func (t *Ticker) Calendar() (*models.Calendar, error)

Calendar returns upcoming calendar events for the ticker.

This includes dividend dates, earnings dates, and earnings estimates.

Example:

calendar, err := ticker.Calendar()
if err != nil {
    log.Fatal(err)
}
if calendar.ExDividendDate != nil {
    fmt.Printf("Ex-Dividend: %s\n", calendar.ExDividendDate.Format("2006-01-02"))
}
for _, date := range calendar.EarningsDate {
    fmt.Printf("Earnings: %s\n", date.Format("2006-01-02"))
}

func (*Ticker) CapitalGains

func (t *Ticker) CapitalGains() ([]models.CapitalGain, error)

CapitalGains returns capital gain distributions for the ticker.

func (*Ticker) CashFlow

func (t *Ticker) CashFlow(freq string) (*models.FinancialStatement, error)

CashFlow returns the cash flow statement data.

Parameters:

  • freq: "annual", "yearly", or "quarterly" (default: "annual")

Note: "yearly" is accepted as an alias for "annual" for Python yfinance compatibility.

The returned [models.FinancialStatement] contains fields like OperatingCashFlow, InvestingCashFlow, FinancingCashFlow, FreeCashFlow, and CapitalExpenditure.

Example:

cashFlow, err := ticker.CashFlow("annual")
if fcf, ok := cashFlow.GetLatest("FreeCashFlow"); ok {
    fmt.Printf("Free Cash Flow: %.2f\n", fcf)
}

func (*Ticker) ClearCache

func (t *Ticker) ClearCache()

ClearCache clears all cached data.

func (*Ticker) Close

func (t *Ticker) Close()

Close releases resources used by the Ticker. If the client was created by the Ticker, it will be closed.

func (*Ticker) Dividends

func (t *Ticker) Dividends() ([]models.Dividend, error)

Dividends returns the dividend history for the ticker.

Returns all historical dividend payments with dates and amounts.

func (*Ticker) EPSRevisions

func (t *Ticker) EPSRevisions() ([]models.EPSRevision, error)

EPSRevisions returns EPS revision data.

func (*Ticker) EPSTrend

func (t *Ticker) EPSTrend() ([]models.EPSTrend, error)

EPSTrend returns EPS trend data.

func (*Ticker) EarningsEstimate

func (t *Ticker) EarningsEstimate() ([]models.EarningsEstimate, error)

EarningsEstimate returns earnings estimates for upcoming periods. This method name matches Python yfinance's ticker.earnings_estimate property.

func (*Ticker) EarningsEstimates

func (t *Ticker) EarningsEstimates() ([]models.EarningsEstimate, error)

EarningsEstimates is a deprecated alias for EarningsEstimate. Deprecated: Use EarningsEstimate() instead for Python yfinance compatibility.

func (*Ticker) EarningsHistory

func (t *Ticker) EarningsHistory() (*models.EarningsHistory, error)

EarningsHistory returns historical earnings data.

func (*Ticker) FastInfo

func (t *Ticker) FastInfo() (*models.FastInfo, error)

FastInfo returns a FastInfo struct with commonly used data. This fetches data from the history endpoint which can be faster for some fields.

func (*Ticker) FinancialsJSON

func (t *Ticker) FinancialsJSON(statementType, freq string) ([]byte, error)

FinancialsJSON returns raw JSON for debugging.

func (*Ticker) GetHistoryMetadata

func (t *Ticker) GetHistoryMetadata() *models.ChartMeta

GetHistoryMetadata returns the cached history metadata.

func (*Ticker) GetNews

func (t *Ticker) GetNews() ([]models.NewsArticle, error)

GetNews is an alias for News with default parameters. It fetches 10 news articles of type "news".

Example:

news, err := ticker.GetNews()

func (*Ticker) GrowthEstimates

func (t *Ticker) GrowthEstimates() ([]models.GrowthEstimate, error)

GrowthEstimates returns growth estimates comparing stock to industry/sector/index.

func (*Ticker) History

func (t *Ticker) History(params models.HistoryParams) ([]models.Bar, error)

History fetches historical OHLCV data for the ticker.

The method returns a slice of [models.Bar] containing Open, High, Low, Close, Adjusted Close, and Volume data for each period.

Parameters can be configured via [models.HistoryParams]:

  • Period: Time range (1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max)
  • Interval: Data granularity (1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo)
  • Start/End: Specific date range (overrides Period)
  • PrePost: Include pre/post market data
  • AutoAdjust: Adjust prices for splits/dividends
  • Actions: Include dividend and split data in bars

Example:

bars, err := ticker.History(models.HistoryParams{
    Period:   "1mo",
    Interval: "1d",
})

func (*Ticker) HistoryPeriod

func (t *Ticker) HistoryPeriod(period string) ([]models.Bar, error)

HistoryPeriod is a convenience method to fetch history with just a period string.

Valid periods: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max

Uses daily interval with auto-adjustment enabled.

func (*Ticker) HistoryRange

func (t *Ticker) HistoryRange(start, end time.Time, interval string) ([]models.Bar, error)

HistoryRange fetches history for a specific date range.

Parameters:

  • start: Start date (inclusive)
  • end: End date (exclusive)
  • interval: Data granularity (1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo)

Uses auto-adjustment enabled by default.

func (*Ticker) IncomeStatement

func (t *Ticker) IncomeStatement(freq string) (*models.FinancialStatement, error)

IncomeStatement returns the income statement data.

Parameters:

  • freq: "annual", "yearly", or "quarterly" (default: "annual")

Note: "yearly" is accepted as an alias for "annual" for Python yfinance compatibility.

The returned [models.FinancialStatement] contains fields like TotalRevenue, GrossProfit, OperatingIncome, NetIncome, EBITDA, BasicEPS, and DilutedEPS.

Example:

income, err := ticker.IncomeStatement("annual")
if revenue, ok := income.GetLatest("TotalRevenue"); ok {
    fmt.Printf("Revenue: %.2f\n", revenue)
}

func (*Ticker) Info

func (t *Ticker) Info() (*models.Info, error)

Info fetches comprehensive company information for the ticker.

func (*Ticker) InsiderPurchases

func (t *Ticker) InsiderPurchases() (*models.InsiderPurchases, error)

InsiderPurchases returns insider purchase activity summary.

This summarizes net share purchases/sales by insiders over a period.

Example:

purchases, err := ticker.InsiderPurchases()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Net shares: %d (%s)\n", purchases.Net.Shares, purchases.Period)

func (*Ticker) InsiderRoster

func (t *Ticker) InsiderRoster() ([]models.InsiderHolder, error)

InsiderRoster returns the list of company insiders.

Deprecated: Use InsiderRosterHolders instead.

func (*Ticker) InsiderRosterHolders

func (t *Ticker) InsiderRosterHolders() ([]models.InsiderHolder, error)

InsiderRosterHolders returns the list of company insiders.

This includes insider names, positions, and their holdings.

Example:

roster, err := ticker.InsiderRosterHolders()
if err != nil {
    log.Fatal(err)
}
for _, insider := range roster {
    fmt.Printf("%s (%s): %d shares\n",
        insider.Name, insider.Position, insider.TotalShares())
}

func (*Ticker) InsiderTransactions

func (t *Ticker) InsiderTransactions() ([]models.InsiderTransaction, error)

InsiderTransactions returns the list of insider transactions.

This includes purchases, sales, and other transactions by company insiders.

Example:

transactions, err := ticker.InsiderTransactions()
if err != nil {
    log.Fatal(err)
}
for _, tx := range transactions {
    fmt.Printf("%s: %s %d shares on %s\n",
        tx.Insider, tx.Transaction, tx.Shares, tx.StartDate.Format("2006-01-02"))
}

func (*Ticker) InstitutionalHolders

func (t *Ticker) InstitutionalHolders() ([]models.Holder, error)

InstitutionalHolders returns the list of institutional holders.

Each holder includes the institution name, shares held, value, and percentage.

Example:

holders, err := ticker.InstitutionalHolders()
if err != nil {
    log.Fatal(err)
}
for _, h := range holders {
    fmt.Printf("%s: %d shares (%.2f%%)\n", h.Holder, h.Shares, h.PctHeld*100)
}

func (*Ticker) MajorHolders

func (t *Ticker) MajorHolders() (*models.MajorHolders, error)

MajorHolders returns the major holders breakdown.

This includes percentages held by insiders, institutions, and institutional count.

Example:

holders, err := ticker.MajorHolders()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Insiders: %.2f%%\n", holders.InsidersPercentHeld*100)
fmt.Printf("Institutions: %.2f%%\n", holders.InstitutionsPercentHeld*100)

func (*Ticker) MutualFundHolders

func (t *Ticker) MutualFundHolders() ([]models.Holder, error)

MutualFundHolders returns the list of mutual fund holders.

Each holder includes the fund name, shares held, value, and percentage.

Example:

holders, err := ticker.MutualFundHolders()
if err != nil {
    log.Fatal(err)
}
for _, h := range holders {
    fmt.Printf("%s: %d shares\n", h.Holder, h.Shares)
}

func (*Ticker) News

func (t *Ticker) News(count int, tab models.NewsTab) ([]models.NewsArticle, error)

News fetches news articles for the ticker.

Parameters:

  • count: Number of articles to fetch (default: 10)
  • tab: Type of news to fetch (default: NewsTabNews)

Example:

news, err := ticker.News(10, models.NewsTabNews)
if err != nil {
    log.Fatal(err)
}
for _, article := range news {
    fmt.Printf("%s: %s\n", article.Publisher, article.Title)
}

func (*Ticker) OptionChain

func (t *Ticker) OptionChain(date string) (*models.OptionChain, error)

OptionChain returns the option chain for a specific expiration date. If date is empty, returns the nearest expiration.

func (*Ticker) OptionChainAtExpiry

func (t *Ticker) OptionChainAtExpiry(date time.Time) (*models.OptionChain, error)

OptionChainAtExpiry is an alias for OptionChain with a specific date.

func (*Ticker) Options

func (t *Ticker) Options() ([]time.Time, error)

Options returns all available expiration dates for options.

func (*Ticker) OptionsJSON

func (t *Ticker) OptionsJSON() ([]byte, error)

OptionsJSON returns raw JSON response for debugging.

func (*Ticker) PriceTarget

func (t *Ticker) PriceTarget() (*models.PriceTarget, error)

PriceTarget is a deprecated alias for AnalystPriceTargets. Deprecated: Use AnalystPriceTargets() instead for Python yfinance compatibility.

func (*Ticker) Quote

func (t *Ticker) Quote() (*models.Quote, error)

Quote fetches the current quote for the ticker.

func (*Ticker) Recommendations

func (t *Ticker) Recommendations() (*models.RecommendationTrend, error)

Recommendations returns analyst recommendation trends.

func (*Ticker) RevenueEstimate

func (t *Ticker) RevenueEstimate() ([]models.RevenueEstimate, error)

RevenueEstimate returns revenue estimates for upcoming periods. This method name matches Python yfinance's ticker.revenue_estimate property.

func (*Ticker) RevenueEstimates

func (t *Ticker) RevenueEstimates() ([]models.RevenueEstimate, error)

RevenueEstimates is a deprecated alias for RevenueEstimate. Deprecated: Use RevenueEstimate() instead for Python yfinance compatibility.

func (*Ticker) Splits

func (t *Ticker) Splits() ([]models.Split, error)

Splits returns the stock split history for the ticker.

Returns all historical stock splits with dates and ratios.

func (*Ticker) Strikes

func (t *Ticker) Strikes() ([]float64, error)

Strikes returns available strike prices for options.

func (*Ticker) Symbol

func (t *Ticker) Symbol() string

Symbol returns the ticker symbol.

func (*Ticker) Valuation

func (t *Ticker) Valuation() (*models.ValuationMeasures, error)

Valuation returns the key-statistics valuation measures table.

This mirrors Python yfinance's ticker.valuation property added in v1.3.0.

func (*Ticker) ValuationMeasures

func (t *Ticker) ValuationMeasures() (*models.ValuationMeasures, error)

ValuationMeasures is an alias for Valuation.