yahoo-finance

Yahoo Finance API client for Kit - stock quotes, historical data, and fundamentals

Uses Kit's built-in HTTP and JSON capabilities with no external dependencies. Includes browser-like headers and retry logic to handle Yahoo Finance's rate limiting.

Files

Installation

kit add yahoo-finance

Quick Start

import Kit.YahooFinance as YahooFinance

main = fn =>
  match YahooFinance.get-quote "AAPL"
    | Ok quote ->
        println "${quote.symbol}: $${Float.to-string quote.price}"
        println "Change: ${Float.to-string quote.change-percent}%"
    | Err e -> println "Error: ${show e}"

Recommended Starting Points

If you are evaluating the package surface quickly, start with these examples:

• examples/analyst-data.kit for analyst price targets, earnings estimates, and holder data
• examples/company-profile.kit for quoteSummary-based company metadata
• examples/earnings-dates.kit for earnings-date summaries plus recent earnings history
• examples/dataframe-integration.kit for tabular sorting/filtering of quotes and analyst estimates
• examples/plot-integration.kit for price-history charts plus forward EPS/growth estimate charts

API Reference

Quotes

# Single quote
get-quote: String -> Result Quote YahooFinanceError

# Multiple quotes in one request
get-quotes: [String] -> Result [Quote] YahooFinanceError

Historical Data

# OHLCV bars with range and interval
get-history: String -> Range -> Interval -> Result [Bar] YahooFinanceError

# OHLCV bars with explicit Unix timestamp range
get-history-range: String -> Int -> Int -> Interval -> Result [Bar] YahooFinanceError

Range values: Day1, Day5, Month1, Month3, Month6, Year1, Year2, Year5, Year10, YTD, Max

Interval values: Minute1, Minute5, Minute15, Minute30, Hour1, Day1, Week1, Month1

Search

# Search symbols by name or ticker
search: String -> Result [SearchResult] YahooFinanceError

# Get trending tickers for a region (e.g., "US", "GB")
get-trending: String -> Result [String] YahooFinanceError

# Lookup a ticker directly from an ISIN
lookup-by-isin: String -> Result String YahooFinanceError

# Detailed symbol lookup by company name or partial ticker
lookup-symbol: String -> Result [SearchResult] YahooFinanceError

Fundamentals

# Company profile / summary metadata from quoteSummary price + assetProfile + defaultKeyStatistics
get-company-profile: String -> Result CompanyProfile YahooFinanceError

# Income statements (Annual or Quarterly)
get-income-statements: String -> StatementPeriod -> Result [IncomeStatement] YahooFinanceError

# Balance sheets
get-balance-sheets: String -> StatementPeriod -> Result [BalanceSheet] YahooFinanceError

# Cash flow statements
get-cash-flow: String -> StatementPeriod -> Result [CashFlowStatement] YahooFinanceError

Analyst Data

# Analyst recommendation summaries (buy/hold/sell counts by period)
get-recommendations: String -> Result [Recommendation] YahooFinanceError

# Analyst rating changes (upgrades/downgrades)
get-rating-changes: String -> Result [RatingChange] YahooFinanceError

# Analyst price target summary
get-analyst-price-target: String -> Result AnalystPriceTarget YahooFinanceError

# Upcoming earnings date summary
get-earnings-dates: String -> Result EarningsDateSummary YahooFinanceError

# Historical EPS estimate vs actual results
get-earnings-history: String -> Result [EarningsHistoryEntry] YahooFinanceError

# Forward EPS estimates by period
get-earnings-estimates: String -> Result [EarningsEstimate] YahooFinanceError

# Forward revenue estimates by period
get-revenue-estimates: String -> Result [RevenueEstimate] YahooFinanceError

# Comparative growth estimates vs industry, sector, and index
get-growth-estimates: String -> Result [GrowthEstimate] YahooFinanceError

# EPS trend snapshots across recent analyst windows
get-eps-trend: String -> Result [EpsTrend] YahooFinanceError

# EPS revision counts across recent analyst windows
get-eps-revisions: String -> Result [EpsRevision] YahooFinanceError

Ownership & Insider Data

# Institutional holder records
get-institutional-holders: String -> Result [InstitutionalHolder] YahooFinanceError

# Mutual fund holder records
get-mutualfund-holders: String -> Result [MutualFundHolder] YahooFinanceError

# Insider transaction history
get-insider-transactions: String -> Result [InsiderTransaction] YahooFinanceError

# Insider roster / current insider holdings summary
get-insider-roster: String -> Result [InsiderRosterEntry] YahooFinanceError

# Major holders breakdown
get-major-holders: String -> Result [MajorHolderBreakdown] YahooFinanceError

# Loose sustainability / ESG metrics
get-sustainability-data: String -> Result [SustainabilityMetric] YahooFinanceError

Dividends & Splits

# Dividend history for a given range
get-dividends: String -> Range -> Result [Dividend] YahooFinanceError

# Stock split history for a given range
get-splits: String -> Range -> Result [Split] YahooFinanceError

Options

# Full option chain (calls and puts)
get-options: String -> Result OptionChain YahooFinanceError

# Option chain for a specific expiration Unix timestamp
get-options-for-expiration: String -> Int -> Result OptionChain YahooFinanceError

# Available expiration Unix timestamps for a symbol
get-options-expirations: String -> Result [Int] YahooFinanceError

Index Ticker Constants

sp500-ticker     # "^GSPC" - S&P 500
dow30-ticker     # "^DJI"  - Dow Jones Industrial Average
nasdaq-ticker    # "^IXIC" - Nasdaq Composite
russell2000-ticker  # "^RUT"  - Russell 2000

Types

Fundamentals fields (revenue, assets, etc.) are Option Float since Yahoo may not return all fields.

Error Handling

All functions return Result T YahooFinanceError. Error variants:

Pattern match on specific error types for fine-grained handling:

import Kit.YahooFinance as YahooFinance

match YahooFinance.get-quote "INVALID"
  | Ok quote -> use-quote quote
  | Err (NotFoundError {symbol}) -> println "Unknown symbol: ${symbol}"
  | Err (NetworkError {message}) -> println "Network issue: ${message}"
  | Err e -> println "Error: ${show e}"

Examples

See the examples/ directory:

• basic-quote.kit - Single and batch quote lookups, index quotes
• analyst-data.kit - Analyst price targets, earnings estimates, and major holders
• earnings-dates.kit - Upcoming earnings dates with EPS/revenue summary and recent earnings history
• historical-chart.kit - OHLCV data with basic statistics
• fundamentals.kit - Income statements, balance sheets, cash flow
• options-chain.kit - Options data with ITM/OTM analysis
• search-symbols.kit - Symbol search and trending tickers
• dividends-splits.kit - Dividend and split history

Integration Examples

• ta-lib-integration.kit - Fetch history, compute SMA/EMA/RSI/Bollinger Bands (requires kit-ta-lib)
• dataframe-integration.kit - Load quotes and earnings estimates into DataFrames for sorting/filtering (requires kit-dataframe)
• plot-integration.kit - Candlestick and analyst-estimate charts from Yahoo data (requires kit-plot)

Notes

• Yahoo Finance does not offer an official public API. These endpoints are unofficial and may change.
• Real-time data may be delayed 15-20 minutes.
• The package includes browser-like User-Agent headers (required by Yahoo to avoid blocking).
• Retry logic (3 retries with exponential backoff) is built in.
• Intraday intervals (Minute1-Hour1) are only available for recent data (7-60 days).
• Data is for personal and educational use. Commercial use may require licensing from Yahoo.
• Respect rate limits to avoid IP blocks.

Exported Functions & Types

apple

Apple Inc.

microsoft

Microsoft Corporation

google

Alphabet Inc. (Google)

amazon

Amazon.com Inc.

meta

Meta Platforms Inc. (Facebook)

nvidia

NVIDIA Corporation

tesla

Tesla Inc.

broadcom

Broadcom Inc.

amd

Advanced Micro Devices Inc.

intel

Intel Corporation

ibm

International Business Machines

oracle

Oracle Corporation

salesforce

Salesforce Inc.

adobe

Adobe Inc.

netflix

Netflix Inc.

cisco

Cisco Systems Inc.

qualcomm

Qualcomm Inc.

uber

Uber Technologies Inc.

palantir

Palantir Technologies Inc.

shopify

Shopify Inc.

snowflake

Snowflake Inc.

jpmorgan

JPMorgan Chase & Co.

goldman-sachs

Goldman Sachs Group Inc.

bank-of-america

Bank of America Corporation

berkshire

Berkshire Hathaway Inc. (Class B)

visa

Visa Inc.

mastercard

Mastercard Inc.

morgan-stanley

Morgan Stanley

amex

American Express Company

unitedhealth

UnitedHealth Group Inc.

johnson-and-johnson

Johnson & Johnson

eli-lilly

Eli Lilly and Company

pfizer

Pfizer Inc.

merck

Merck & Co. Inc.

abbvie

AbbVie Inc.

walmart

Walmart Inc.

coca-cola

The Coca-Cola Company

pepsi

PepsiCo Inc.

mcdonalds

McDonald's Corporation

nike

Nike Inc.

disney

The Walt Disney Company

starbucks

Starbucks Corporation

costco

Costco Wholesale Corporation

home-depot

The Home Depot Inc.

procter-and-gamble

Procter & Gamble Company

exxon

Exxon Mobil Corporation

chevron

Chevron Corporation

att

AT&T Inc.

verizon

Verizon Communications Inc.

comcast

Comcast Corporation

boeing

Boeing Company

lockheed-martin

Lockheed Martin Corporation

caterpillar

Caterpillar Inc.

three-m

3M Company

spy

SPDR S&P 500 ETF Trust

qqq

Invesco QQQ Trust (Nasdaq 100)

dia

SPDR Dow Jones Industrial Average ETF

iwm

iShares Russell 2000 ETF

vti

Vanguard Total Stock Market ETF

voo

Vanguard S&P 500 ETF

arkk

ARK Innovation ETF

eem

iShares MSCI Emerging Markets ETF

bitcoin

Bitcoin (USD)

ethereum

Ethereum (USD)

solana

Solana (USD)

sp500

S&P 500 index

dow

Dow Jones Industrial Average

nasdaq

Nasdaq Composite

russell2000

Russell 2000

vix

CBOE Volatility Index (VIX)

mag7

Magnificent Seven tickers

tech-stocks

Popular technology stock tickers

finance-stocks

Popular finance stock tickers

healthcare-stocks

Popular healthcare stock tickers

consumer-stocks

Popular consumer stock tickers

popular-etfs

Popular ETF tickers

lookup

Look up a ticker symbol by company name. Case-insensitive exact match against known company names and aliases.

Parameters:

Returns:

String -> Option String

Tickers.lookup "Apple"      # => Some "AAPL"
Tickers.lookup "facebook"   # => Some "META"
Tickers.lookup "unknown"    # => None

search

Search for ticker symbols where the company name contains the query. Case-insensitive partial match. Returns all matching (name, symbol) pairs.

Parameters:

Returns:

String -> [(String, String)]

Tickers.search "bank"
# => [("bank of america", "BAC")]

Tickers.search "gold"
# => [("goldman sachs", "GS"), ("goldman", "GS")]

YahooFinanceError

Yahoo Finance error types.

Variants: - NetworkError: HTTP request failed - ParseError: JSON parsing failed - RateLimitError: Too many requests (HTTP 429) - NotFoundError: Symbol not found - InvalidSymbolError: Invalid ticker symbol format - ApiError: Error returned by Yahoo Finance API - NoDataError: No data available for the requested symbol/range

get-quote

Get a real-time quote for a symbol.

Parameters:

Returns:

String -> Result Quote YahooFinanceError

match YahooFinance.get-quote "AAPL"
  | Ok quote -> println "Price: ${Float.to-string quote.price}"
  | Err e -> println "Error: ${show e}"

get-quotes

Get quotes for multiple symbols.

Parameters:

Returns:

[String] -> Result [Quote] YahooFinanceError

match YahooFinance.get-quotes ["AAPL", "MSFT", "GOOGL"]
  | Ok quotes -> List.each quotes (fn(q) => println q.symbol)
  | Err e -> println "Error: ${show e}"

get-history

Get historical OHLCV data for a symbol.

Parameters:

Returns:

String -> Range -> Interval -> Result [Bar] YahooFinanceError

match YahooFinance.get-history "AAPL" Year1 Day1
  | Ok bars -> println "Got ${Int.to-string (List.length bars)} bars"
  | Err e -> println "Error: ${show e}"

get-history-range

Get historical data with explicit Unix timestamp range.

Parameters:

Returns:

String -> Int -> Int -> Interval -> Result [Bar] YahooFinanceError

start = 1704067200  # 2024-01-01
end = 1735689600    # 2025-01-01
match YahooFinance.get-history-range "AAPL" start end Day1
  | Ok bars -> println "Got ${Int.to-string (List.length bars)} bars"
  | Err e -> println "Error: ${show e}"

search

Search for symbols by name or ticker.

Parameters:

Returns:

String -> Result [SearchResult] YahooFinanceError

match YahooFinance.search "Apple"
  | Ok results -> List.each results (fn(r) => println "${r.symbol}: ${r.name}")
  | Err e -> println "Error: ${show e}"

get-trending

Get trending tickers for a region.

Parameters:

Returns:

String -> Result [String] YahooFinanceError

match YahooFinance.get-trending "US"
  | Ok tickers -> List.each tickers println
  | Err e -> println "Error: ${show e}"

get-company-profile

Get company profile and summary metadata for a symbol.

Parameters:

Returns:

String -> Result CompanyProfile YahooFinanceError

get-income-statements

Get income statements for a symbol.

Parameters:

Returns:

String -> StatementPeriod -> Result [IncomeStatement] YahooFinanceError

match YahooFinance.get-income-statements "AAPL" Annual
  | Ok statements -> List.each statements (fn(s) => println "Revenue: ${show s.total-revenue}")
  | Err e -> println "Error: ${show e}"

get-balance-sheets

Get balance sheets for a symbol.

Parameters:

Returns:

String -> StatementPeriod -> Result [BalanceSheet] YahooFinanceError

match YahooFinance.get-balance-sheets "AAPL" Annual
  | Ok sheets -> List.each sheets (fn(s) => println "Assets: ${show s.total-assets}")
  | Err e -> println "Error: ${show e}"

get-cash-flow

Get cash flow statements for a symbol.

Parameters:

Returns:

String -> StatementPeriod -> Result [CashFlowStatement] YahooFinanceError

match YahooFinance.get-cash-flow "AAPL" Annual
  | Ok statements -> List.each statements (fn(s) => println "FCF: ${show s.free-cash-flow}")
  | Err e -> println "Error: ${show e}"

get-recommendations

Get analyst recommendations for a symbol.

Parameters:

Returns:

String -> Result [Recommendation] YahooFinanceError

match YahooFinance.get-recommendations "AAPL"
  | Ok recs -> List.each recs (fn(r) => println "${r.period}: ${Int.to-string r.buy} buy")
  | Err e -> println "Error: ${show e}"

get-rating-changes

Get analyst rating changes (upgrades/downgrades) for a symbol.

Parameters:

Returns:

String -> Result [RatingChange] YahooFinanceError

match YahooFinance.get-rating-changes "AAPL"
  | Ok changes -> List.each changes (fn(c) => println "${c.firm}: ${c.action}")
  | Err e -> println "Error: ${show e}"

get-analyst-price-target

Get analyst price target summary for a symbol.

Parameters:

Returns:

String -> Result AnalystPriceTarget YahooFinanceError

match YahooFinance.get-analyst-price-target "AAPL"
  | Ok targets -> println "Mean target: ${show targets.mean}"
  | Err e -> println "Error: ${show e}"

get-earnings-history

Get historical earnings results for a symbol.

Parameters:

Returns:

String -> Result [EarningsHistoryEntry] YahooFinanceError

get-earnings-estimates

Get forward earnings estimates for upcoming quarters and years.

Parameters:

Returns:

String -> Result [EarningsEstimate] YahooFinanceError

get-revenue-estimates

Get forward revenue estimates for upcoming quarters and years.

Parameters:

Returns:

String -> Result [RevenueEstimate] YahooFinanceError

get-growth-estimates

Get comparative growth estimates for stock, industry, sector, and index.

Parameters:

Returns:

String -> Result [GrowthEstimate] YahooFinanceError

get-eps-trend

Get EPS trend snapshots across recent analyst revision windows.

Parameters:

Returns:

String -> Result [EpsTrend] YahooFinanceError

get-eps-revisions

Get EPS revision counts across recent analyst windows.

Parameters:

Returns:

String -> Result [EpsRevision] YahooFinanceError

get-major-holders

Get major holders breakdown for a symbol.

Parameters:

Returns:

String -> Result [MajorHolderBreakdown] YahooFinanceError

get-sustainability-data

Get loose sustainability / ESG metrics for a symbol.

Parameters:

Returns:

String -> Result [SustainabilityMetric] YahooFinanceError

get-earnings-dates

Get upcoming earnings date summary for a symbol.

Parameters:

Returns:

String -> Result EarningsDateSummary YahooFinanceError

get-institutional-holders

Get institutional holders for a symbol.

Parameters:

Returns:

String -> Result [InstitutionalHolder] YahooFinanceError

get-mutualfund-holders

Get mutual fund holders for a symbol.

Parameters:

Returns:

String -> Result [MutualFundHolder] YahooFinanceError

get-insider-transactions

Get insider transactions for a symbol.

Parameters:

Returns:

String -> Result [InsiderTransaction] YahooFinanceError

get-insider-roster

Get insider roster for a symbol.

Parameters:

Returns:

String -> Result [InsiderRosterEntry] YahooFinanceError

get-dividends

Get dividend history for a symbol.

Parameters:

Returns:

String -> Range -> Result [Dividend] YahooFinanceError

match YahooFinance.get-dividends "AAPL" Year5
  | Ok divs -> List.each divs (fn(d) => println "$${Float.to-string d.amount}")
  | Err e -> println "Error: ${show e}"

get-splits

Get stock split history for a symbol.

Parameters:

Returns:

String -> Range -> Result [Split] YahooFinanceError

match YahooFinance.get-splits "AAPL" Max
  | Ok splits -> List.each splits (fn(s) => println "${Int.to-string s.numerator}:${Int.to-string s.denominator}")
  | Err e -> println "Error: ${show e}"

get-options

Get option chain for a symbol.

Parameters:

Returns:

String -> Result OptionChain YahooFinanceError

match YahooFinance.get-options "AAPL"
  | Ok chain -> println "Calls: ${Int.to-string (List.length chain.calls)}"
  | Err e -> println "Error: ${show e}"

get-options-for-expiration

Get option chain for a specific expiration date.

Parameters:

Returns:

String -> Int -> Result OptionChain YahooFinanceError

# Get options expiring on March 15, 2024
expiration = 1710460800  # 2024-03-15 00:00:00 UTC
match YahooFinance.get-options-for-expiration "AAPL" expiration
  | Ok chain -> println "${Int.to-string (List.length chain.calls)} calls for expiration"
  | Err e -> println "Error: ${show e}"

get-options-expirations

Get available option expiration dates for a symbol.

Parameters:

Returns:

String -> Result [Int] YahooFinanceError

match YahooFinance.get-options-expirations "AAPL"
  | Ok dates ->
      println "Available expirations:"
      List.each dates (fn(d) => println "  ${Int.to-string d}")
  | Err e -> println "Error: ${show e}"

lookup-by-isin

Lookup a ticker symbol by ISIN (International Securities Identification Number).

Parameters:

Returns:

String -> Result String YahooFinanceError

match YahooFinance.lookup-by-isin "US0378331005"
  | Ok ticker -> println "ISIN corresponds to ticker: ${ticker}"
  | Err e -> println "Error: ${show e}"

lookup-symbol

Lookup symbols by company name or partial ticker.

Parameters:

Returns:

String -> Result [SearchResult] YahooFinanceError

match YahooFinance.lookup-symbol "Apple Inc"
  | Ok results ->
      List.each results (fn(r) =>
        println "${r.symbol}: ${r.name} (${r.exchange})"
      )
  | Err e -> println "Error: ${show e}"

Quote

Stock quote data with price, volume, and market cap.

Bar

OHLCV bar data from historical chart endpoint.

Range

Time range for historical data queries.

Interval

Interval for historical data granularity.

SearchResult

Search result from symbol search endpoint.

CompanyProfile

Company profile summary from quoteSummary.

StatementPeriod

Financial statement period (Annual or Quarterly).

IncomeStatement

Income statement data from quoteSummary.

BalanceSheet

Balance sheet data from quoteSummary.

CashFlowStatement

Cash flow statement data from quoteSummary.

Recommendation

Analyst recommendation summary for a period.

RatingChange

Analyst rating change (upgrade/downgrade).

AnalystPriceTarget

Analyst price target summary.

EarningsHistoryEntry

Historical earnings result (estimate vs actual).

EarningsEstimate

Forward earnings estimate for a reporting period.

RevenueEstimate

Forward revenue estimate for a reporting period.

GrowthEstimate

Comparative growth estimates for stock, industry, sector, and index.

EpsTrend

Forward EPS trend snapshots across recent analyst revision windows.

EpsRevision

Analyst EPS revision counts across recent windows.

MajorHolderBreakdown

Major holders breakdown entry.

SustainabilityMetric

Loose sustainability / ESG metric entry.

EarningsDateSummary

Upcoming earnings date summary from Yahoo calendar events.

InstitutionalHolder

Institutional holder summary.

MutualFundHolder

Mutual fund holder summary.

InsiderTransaction

Insider transaction record.

InsiderRosterEntry

Insider roster entry.

Dividend

Dividend event from the chart API.

Split

Stock split event from the chart API.

OptionContract

Option contract data.

OptionChain

Option chain for a symbol (calls and puts).

YahooFinanceError

Yahoo Finance error types.

sp500-ticker

S&P 500 index ticker.

dow30-ticker

Dow Jones Industrial Average ticker.

nasdaq-ticker

Nasdaq Composite ticker.

russell2000-ticker

Russell 2000 ticker.

Tickers

Well-known ticker symbols and company name lookup. Access individual tickers (e.g., Tickers.apple, Tickers.nvidia) or use Tickers.lookup for name-to-symbol resolution.

Market

Market, Sector, and Industry data module. Provides market status, sector performance, and industry information.

import Kit.YahooFinance as YahooFinance
match YahooFinance.Market.get-sector "technology"
  | Ok sector -> println "Tech sector: ${Float.to-string sector.performance-1d}%"
  | Err e -> println "Error: ${show e}"

Screener

Stock Screener module for building custom stock queries. Provides predefined screeners and custom query building.

import Kit.YahooFinance as YahooFinance
match YahooFinance.Screener.day-gainers
  | Ok results -> List.each results (fn(r) => println r.symbol)
  | Err e -> println "Error: ${show e}"

FilterValue

Filter value types for screener queries.

Variants: - Min Int: Minimum value filter - Max Int: Maximum value filter - Range {min: Int, max: Int}: Range filter - Eq String: Exact match filter - InList [String]: List membership filter

Filter

Single filter criterion for screener queries.

Fields: - field: The field to filter on (e.g., "marketCap", "trailingPE") - value: The filter value (Min, Max, Range, Eq, or InList)

Sort

Sort criterion for screener results.

Fields: - field: The field to sort by (e.g., "marketCap", "volume") - descending: true for descending order, false for ascending

EquityQuery

Equity screener query with filters and sort options.

Fields: - filters: List of filter criteria - sort: Optional sort criterion - limit: Maximum number of results (default: 25) - offset: Number of results to skip (for pagination)

ScreenResult

Screener result with quote and metadata.

Fields: - symbol: Stock ticker symbol - name: Company name - price: Current stock price - change-percent: Percentage change - market-cap: Market capitalization - volume: Trading volume - sector: Business sector - industry: Industry classification - region: Geographic region - exchange: Stock exchange

new-query

Create a new empty equity query.

() -> EquityQuery

query = Screener.new-query
  |> Screener.add-filter "region" "us"
  |> Screener.add-filter "marketCap" (Min 1000000000)

add-filter

Add a filter to an equity query.

Parameters:

Returns:

EquityQuery -> String -> FilterValue -> EquityQuery

query = Screener.new-query
  |> Screener.add-filter "region" (Eq "us")
  |> Screener.add-filter "marketCap" (Min 1000000000)
  |> Screener.add-filter "trailingPE" (Range {min: 5, max: 20})

add-sort

Add sort order to an equity query.

Parameters:

Returns:

EquityQuery -> String -> Bool -> EquityQuery

query = Screener.new-query
  |> Screener.add-sort "marketCap" true  # Sort by market cap descending

set-limit

Set result limit for an equity query.

Parameters:

Returns:

EquityQuery -> Int -> EquityQuery

set-offset

Set offset for pagination.

Parameters:

Returns:

EquityQuery -> Int -> EquityQuery

screen

Execute a screener query and return matching stocks.

Parameters:

Returns:

EquityQuery -> Result [ScreenResult] YahooFinanceError

query = Screener.new-query
  |> Screener.add-filter "region" (Eq "us")
  |> Screener.add-filter "marketCap" (Min 1000000000)
  |> Screener.add-sort "marketCap" true

match Screener.screen query
  | Ok results ->
      println "Found ${Int.to-string (List.length results)} stocks"
      List.each results (fn(r) => println "${r.symbol}: ${Float.to-string r.market-cap}")
  | Err e -> println "Error: ${show e}"

day-gainers

Get top gaining stocks for the day.

Returns:

() -> Result [ScreenResult] YahooFinanceError

match Screener.day-gainers
  | Ok results -> List.each results (fn(r) =>
      println "${r.symbol}: +${Float.to-string r.change-percent}%"
    )
  | Err e -> println "Error: ${show e}"

day-losers

Get top losing stocks for the day.

Returns:

() -> Result [ScreenResult] YahooFinanceError

match Screener.day-losers
  | Ok results -> List.each results (fn(r) =>
      println "${r.symbol}: ${Float.to-string r.change-percent}%"
    )
  | Err e -> println "Error: ${show e}"

most-active

Get most active stocks by volume.

Returns:

() -> Result [ScreenResult] YahooFinanceError

match Screener.most-active
  | Ok results -> List.each results (fn(r) =>
      println "${r.symbol}: Volume ${Int.to-string r.volume}"
    )
  | Err e -> println "Error: ${show e}"

most-active-by-value

Get most actively traded stocks by value (price × volume).

Returns:

() -> Result [ScreenResult] YahooFinanceError

match Screener.most-active-by-value
  | Ok results -> List.each results (fn(r) =>
      value = r.price * Float.from-int r.volume
      println "${r.symbol}: $${Float.to-string value}"
    )
  | Err e -> println "Error: ${show e}"

undervalued-large-caps

Get undervalued large-cap stocks (low P/E, high market cap).

Returns:

() -> Result [ScreenResult] YahooFinanceError

match Screener.undervalued-large-caps
  | Ok results -> List.each results (fn(r) =>
      println "${r.symbol}: Market Cap $${Float.to-string r.market-cap}"
    )
  | Err e -> println "Error: ${show e}"

growth-stocks

Get growth stocks (high revenue growth, mid-to-large cap).

Returns:

() -> Result [ScreenResult] YahooFinanceError

match Screener.growth-stocks
  | Ok results -> List.each results println
  | Err e -> println "Error: ${show e}"

MarketStatus

Market status for a specific market.

Fields: - market: Market code (e.g., "us_market") - status: "OPEN" or "CLOSED" - timezone: Timezone name - open-time: Market opening time - close-time: Market closing time - current-time: Current time string - is-open?: Whether the market is currently open

MarketIndex

Market index data (S&P 500, Dow, Nasdaq, etc.).

Fields: - symbol: Index symbol (e.g., "^GSPC", "^DJI") - name: Index name - price: Current index value - change: Point change - change-percent: Percentage change - volume: Trading volume - timestamp: Last update timestamp

Sector

Sector overview with top companies and performance.

Fields: - id: Sector identifier (e.g., "technology") - name: Sector name - description: Sector description - performance-1d: 1-day performance percentage - performance-1w: 1-week performance percentage - performance-1m: 1-month performance percentage - performance-1y: 1-year performance percentage - top-companies: List of top companies in the sector - industries: List of industries within the sector

Industry

Industry within a sector.

Fields: - id: Industry identifier (e.g., "software-application") - name: Industry name - sector-id: Parent sector identifier - performance-1d: 1-day performance percentage - performance-1w: 1-week performance percentage - performance-1m: 1-month performance percentage - performance-1y: 1-year performance percentage - top-companies: List of top companies in the industry - tickers: List of ticker symbols in the industry

CompanySummary

Company summary for sector/industry listings.

Fields: - symbol: Ticker symbol - name: Company name - market-cap: Market capitalization - performance-1d: 1-day performance percentage - price: Current stock price

IndustrySummary

Industry summary without full details.

Fields: - id: Industry identifier - name: Industry name - performance-1d: 1-day performance percentage

get-status

Get current market status and trading hours.

Parameters:

Returns:

String -> Result MarketStatus YahooFinanceError

match Market.get-status "us_market"
  | Ok status ->
      println "Market is ${if status.is-open then "OPEN" else "CLOSED"}"
      println "Current time: ${status.current-time}"
  | Err e -> println "Error: ${show e}"

get-indices

Get major market indices (S&P 500, Dow Jones, Nasdaq, etc.).

Returns:

() -> Result [MarketIndex] YahooFinanceError

match Market.get-indices
  | Ok indices ->
      List.each indices (fn(idx) =>
        println "${idx.name}: ${Float.to-string idx.change-percent}%"
      )
  | Err e -> println "Error: ${show e}"

get-sector

Get sector overview and performance data.

Parameters:

Returns:

String -> Result Sector YahooFinanceError

match Market.get-sector "technology"
  | Ok sector ->
      println "${sector.name} - 1D: ${Float.to-string sector.performance-1d}%"
      println "Top companies:"
      List.each sector.top-companies (fn(c) => println "  ${c.symbol}")
  | Err e -> println "Error: ${show e}"

get-industry

Get industry data and top companies.

Parameters:

Returns:

String -> Result Industry YahooFinanceError

match Market.get-industry "software-application"
  | Ok industry ->
      println "${industry.name} companies:"
      List.each industry.tickers println
  | Err e -> println "Error: ${show e}"

base-url

Base URL for Yahoo Finance API

yahoo-user-agent

User agent string for Yahoo Finance requests

init-session

Initialize a Yahoo Finance session by fetching cookies. Must be called before making authenticated requests.

Returns:

-> Result () YahooFinanceError

get-crumb

Get or fetch a crumb token for authenticated requests. The crumb is cached after first fetch.

Returns:

-> Result String YahooFinanceError

clear-crumb

Clear the cached crumb token. Useful after errors or when starting a new session.

-> ()

network-error

Construct a Yahoo Finance network error.

String -> YahooFinanceError

parse-error

Construct a Yahoo Finance parse error.

String -> YahooFinanceError

rate-limit-error

Construct a Yahoo Finance rate-limit error.

String -> YahooFinanceError

not-found-error

Construct a Yahoo Finance not-found error.

String -> YahooFinanceError

api-error

Construct a Yahoo Finance API error.

String -> String -> YahooFinanceError

no-data-error

Construct a Yahoo Finance no-data error.

String -> YahooFinanceError

curl-fetch

Basic curl fetch with error handling.

Parameters:

Returns:

String -> Result {status: Int, body: String} YahooFinanceError

fetch-with-auth

Fetch with authentication headers (legacy method).

Parameters:

Returns:

String -> Result {status: Int, body: String} YahooFinanceError

post-with-crumb

POST request to Yahoo Finance API with crumb authentication. Used for the new visualization endpoints.

Parameters:

Returns:

String -> String -> Result {status: Int, body: String} YahooFinanceError

Quote

Stock quote data from the /v7/finance/quote endpoint.

match YahooFinance.get-quote "AAPL"
  | Ok quote -> println "Price: ${Float.to-string quote.price}"
  | Err e -> println "Error: ${show e}"

Bar

OHLCV bar data from the /v8/finance/chart endpoint.

Fields: - timestamp: Unix timestamp in seconds - open, high, low, close: Price data (may be 0.0 if unavailable) - volume: Trading volume - adj-close: Split/dividend adjusted close price

Range

Time range for historical data queries.

YahooFinance.get-history "AAPL" Year1 Day1

Interval

Interval for historical data granularity.

Note: Intraday intervals (Minute1-Hour1) are only available for recent data (typically last 7-60 days depending on interval).

SearchResult

Search result from the /v1/finance/search endpoint.

CompanyProfile

Company profile summary from quoteSummary price + assetProfile + defaultKeyStatistics.

StatementPeriod

Financial statement period

IncomeStatement

Income statement data from quoteSummary.

Fields: - end-date: End date as Unix timestamp - total-revenue, cost-of-revenue, gross-profit: Revenue metrics - operating-income, net-income, ebitda: Profitability metrics

BalanceSheet

Balance sheet data from quoteSummary.

Fields: - end-date: End date as Unix timestamp - total-assets, total-liabilities, total-equity: Balance sheet totals - cash: Cash and cash equivalents - total-debt: Total debt outstanding

CashFlowStatement

Cash flow statement data from quoteSummary.

Fields: - end-date: End date as Unix timestamp - operating-cash-flow, investing-cash-flow, financing-cash-flow: Cash flow categories - free-cash-flow: Operating cash flow minus capital expenditures - capital-expenditures: Capital spending

Recommendation

Analyst recommendation summary for a period.

RatingChange

Analyst rating change (upgrade/downgrade).

AnalystPriceTarget

Analyst price target summary.

EarningsHistoryEntry

Historical earnings result (estimate vs actual).

EarningsEstimate

Forward earnings estimate for a reporting period.

RevenueEstimate

Forward revenue estimate for a reporting period.

GrowthEstimate

Comparative growth estimates for stock, industry, sector, and index.

EpsTrend

Forward EPS trend snapshots across recent analyst revision windows.

EpsRevision

Analyst EPS revision counts across recent windows.

MajorHolderBreakdown

Major holders breakdown entry (insider %, institution %, holder count, etc.).

SustainabilityMetric

Loose sustainability / ESG metric entry.

EarningsDateSummary

Upcoming earnings date summary from Yahoo calendar events.

InstitutionalHolder

Institutional holder summary.

MutualFundHolder

Mutual fund holder summary.

InsiderTransaction

Insider transaction record.

InsiderRosterEntry

Insider roster entry.

Dividend

Dividend event from the chart API.

Split

Stock split event from the chart API.

OptionContract

Option contract data.

OptionChain

Option chain for a symbol (calls and puts).

range-to-string

Convert Range to Yahoo Finance query string.

Range -> String

interval-to-string

Convert Interval to Yahoo Finance query string.

Interval -> String

sp500-ticker

S&P 500 index ticker

dow30-ticker

Dow Jones Industrial Average ticker

nasdaq-ticker

Nasdaq Composite ticker

russell2000-ticker

Russell 2000 ticker