Skip to content

screener

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

Package screener provides Yahoo Finance stock screener functionality.

Overview

The screener package allows you to filter stocks based on various criteria using Yahoo Finance's predefined screeners or custom queries.

Predefined Screeners

Yahoo Finance provides several predefined screeners:

  • day_gainers: Stocks with highest percentage gain today
  • day_losers: Stocks with highest percentage loss today
  • most_actives: Stocks with highest trading volume
  • aggressive_small_caps: Aggressive small cap stocks
  • growth_technology_stocks: Growth technology stocks
  • undervalued_growth_stocks: Undervalued growth stocks
  • undervalued_large_caps: Undervalued large cap stocks
  • most_shorted_stocks: Most shorted stocks
  • small_cap_gainers: Small cap gainers

Basic Usage

s, err := screener.New()
if err != nil {
    log.Fatal(err)
}
defer s.Close()

result, err := s.DayGainers(10)
if err != nil {
    log.Fatal(err)
}
for _, quote := range result.Quotes {
    fmt.Printf("%s: %.2f%%\n", quote.Symbol, quote.RegularMarketChangePercent)
}

Screener Methods

The Screener struct provides the following methods:

Predefined Screeners:

Custom Queries:

Custom Queries

Build custom queries using [models.ScreenerQuery]:

// Find US tech stocks with price > $50
query := models.NewEquityQuery(models.OpAND, []interface{}{
    models.NewEquityQuery(models.OpEQ, []interface{}{"region", "us"}),
    models.NewEquityQuery(models.OpEQ, []interface{}{"sector", "Technology"}),
    models.NewEquityQuery(models.OpGT, []interface{}{"intradayprice", 50}),
})
result, err := s.ScreenWithQuery(query, nil)

Query Operators

Available operators for custom queries:

  • OpEQ: Equals
  • OpGT: Greater than
  • OpLT: Less than
  • OpGTE: Greater than or equal
  • OpLTE: Less than or equal
  • OpBTWN: Between (requires min and max values)
  • OpAND: All conditions must match
  • OpOR: Any condition can match

Thread Safety

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

Index

Variables

PredefinedScreenerQueries maps predefined screener names to their query definitions. Matches Python's PREDEFINED_SCREENER_QUERIES from yfinance v1.3.0.

var PredefinedScreenerQueries map[string]PredefinedQuery

type Option

Option is a function that configures a Screener instance.

type Option func(*Screener)

func WithClient

func WithClient(c *client.Client) Option

WithClient sets a custom HTTP client.

type PredefinedQuery

PredefinedQuery holds a predefined screener query with its sort configuration.

type PredefinedQuery struct {
    SortField string
    SortAsc   bool
    Query     models.ScreenerQueryBuilder
}

type Screener

Screener provides Yahoo Finance stock screener functionality.

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

func New

func New(opts ...Option) (*Screener, error)

New creates a new Screener instance.

Example:

s, err := screener.New()
if err != nil {
    log.Fatal(err)
}
defer s.Close()

func (*Screener) Close

func (s *Screener) Close()

Close releases resources used by the Screener instance.

func (*Screener) DayGainers

func (s *Screener) DayGainers(count int) (*models.ScreenerResult, error)

DayGainers returns stocks with the highest percentage gain today.

Example:

result, err := s.DayGainers(10)
for _, quote := range result.Quotes {
    fmt.Printf("%s: +%.2f%%\n", quote.Symbol, quote.RegularMarketChangePercent)
}

func (*Screener) DayLosers

func (s *Screener) DayLosers(count int) (*models.ScreenerResult, error)

DayLosers returns stocks with the highest percentage loss today.

Example:

result, err := s.DayLosers(10)
for _, quote := range result.Quotes {
    fmt.Printf("%s: %.2f%%\n", quote.Symbol, quote.RegularMarketChangePercent)
}

func (*Screener) MostActives

func (s *Screener) MostActives(count int) (*models.ScreenerResult, error)

MostActives returns stocks with the highest trading volume today.

Example:

result, err := s.MostActives(10)
for _, quote := range result.Quotes {
    fmt.Printf("%s: %d shares\n", quote.Symbol, quote.RegularMarketVolume)
}

func (*Screener) Screen

func (s *Screener) Screen(screener models.PredefinedScreener, params *models.ScreenerParams) (*models.ScreenerResult, error)

Screen uses a predefined screener to find matching stocks.

Example:

result, err := s.Screen(models.ScreenerDayGainers, nil)
if err != nil {
    log.Fatal(err)
}
for _, quote := range result.Quotes {
    fmt.Printf("%s: %.2f%%\n", quote.Symbol, quote.RegularMarketChangePercent)
}

func (*Screener) ScreenWithQuery

func (s *Screener) ScreenWithQuery(query models.ScreenerQueryBuilder, params *models.ScreenerParams) (*models.ScreenerResult, error)

ScreenWithQuery uses a custom query to find matching stocks or funds. Accepts both *models.EquityQuery and *models.FundQuery. The quoteType is automatically determined from the query type: "EQUITY" for EquityQuery, "MUTUALFUND" for FundQuery.

Example:

// Find US stocks with market cap > $10B
q1, _ := models.NewEquityQuery("eq", []interface{}{"region", "us"})
q2, _ := models.NewEquityQuery("gt", []interface{}{"intradaymarketcap", 10000000000})
query, _ := models.NewEquityQuery("and", []interface{}{q1, q2})
result, err := s.ScreenWithQuery(query, nil)