yahoo-finance

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

Fetch stock quotes, company profiles, historical OHLCV bars, financial statements,

options chains, analyst data, holder data, insider activity, market data, screeners,

dividends, and splits from Yahoo Finance's public web endpoints.

Files

Generated parity result files, coverage files, and chart HTML files are development

artifacts, not package source.

Dependencies

All Kit package dependencies in kit.toml are git dependencies.

The package declares the net capability because the public APIs make network

requests. The TA-Lib integration example also requires the native TA-Lib library

available to kit-ta-lib.

Installation

kit add gitlab.com/kit-lang/packages/kit-yahoo-finance.git

Usage

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 "Quote error: ${show e}"

  match YahooFinance.get-history "AAPL" Month3 Day1
    | Ok bars -> println "Retrieved ${Int.to-string (List.length bars)} daily bars"
    | Err e -> println "History error: ${show e}"

  match YahooFinance.get-company-profile "AAPL"
    | Ok profile ->
        println "${profile.name}"
        println "Sector: ${profile.sector}"
    | Err e -> println "Profile error: ${show e}"

main

Submodules

import Kit.YahooFinance as YahooFinance
import Kit.YahooFinance.Market as Market
import Kit.YahooFinance.Screener as Screener
import Kit.YahooFinance.Tickers as Tickers

The main module also re-exports Market, Screener, and Tickers as

YahooFinance.Market, YahooFinance.Screener, and YahooFinance.Tickers.

Developer Reference

Recommended Starting Points

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

• examples/basic-quote.kit for single quotes, batch quotes, and index quotes
• examples/analyst-data.kit for analyst targets, estimates, and holder data
• examples/company-profile.kit for quoteSummary company metadata
• examples/earnings-dates.kit for earnings summaries and recent EPS history
• examples/dataframe-integration.kit for tabular sorting and filtering
• examples/plot-integration.kit for price-history and analyst-estimate charts
• examples/ta-lib-integration.kit for technical indicators

API Reference

Quotes:

get-quote: String -> Result Quote YahooFinanceError
get-quotes: [String] -> Result [Quote] YahooFinanceError

Historical data:

get-history: String -> Range -> Interval -> Result [Bar] YahooFinanceError
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 and lookup:

search: String -> Result [SearchResult] YahooFinanceError
get-trending: String -> Result [String] YahooFinanceError
lookup-by-isin: String -> Result String YahooFinanceError
lookup-symbol: String -> Result [SearchResult] YahooFinanceError

Fundamentals:

get-company-profile: String -> Result CompanyProfile YahooFinanceError
get-income-statements: String -> StatementPeriod -> Result [IncomeStatement] YahooFinanceError
get-balance-sheets: String -> StatementPeriod -> Result [BalanceSheet] YahooFinanceError
get-cash-flow: String -> StatementPeriod -> Result [CashFlowStatement] YahooFinanceError

Analyst data:

get-recommendations: String -> Result [Recommendation] YahooFinanceError
get-rating-changes: String -> Result [RatingChange] YahooFinanceError
get-analyst-price-target: String -> Result AnalystPriceTarget YahooFinanceError
get-earnings-dates: String -> Result EarningsDateSummary YahooFinanceError
get-earnings-history: String -> Result [EarningsHistoryEntry] YahooFinanceError
get-earnings-estimates: String -> Result [EarningsEstimate] YahooFinanceError
get-revenue-estimates: String -> Result [RevenueEstimate] YahooFinanceError
get-growth-estimates: String -> Result [GrowthEstimate] YahooFinanceError
get-eps-trend: String -> Result [EpsTrend] YahooFinanceError
get-eps-revisions: String -> Result [EpsRevision] YahooFinanceError

Ownership, insider, and ESG data:

get-institutional-holders: String -> Result [InstitutionalHolder] YahooFinanceError
get-mutualfund-holders: String -> Result [MutualFundHolder] YahooFinanceError
get-insider-transactions: String -> Result [InsiderTransaction] YahooFinanceError
get-insider-roster: String -> Result [InsiderRosterEntry] YahooFinanceError
get-major-holders: String -> Result [MajorHolderBreakdown] YahooFinanceError
get-sustainability-data: String -> Result [SustainabilityMetric] YahooFinanceError

Dividends, splits, and options:

get-dividends: String -> Range -> Result [Dividend] YahooFinanceError
get-splits: String -> Range -> Result [Split] YahooFinanceError
get-options: String -> Result OptionChain YahooFinanceError
get-options-for-expiration: String -> Int -> Result OptionChain YahooFinanceError
get-options-expirations: String -> Result [Int] YahooFinanceError

Market module:

Market.get-status: String -> Result MarketStatus YahooFinanceError
Market.get-indices: () -> Result [MarketIndex] YahooFinanceError
Market.get-sector: String -> Result Sector YahooFinanceError
Market.get-industry: String -> Result Industry YahooFinanceError

Screener module:

Screener.new-query: () -> EquityQuery
Screener.add-filter: EquityQuery -> String -> FilterValue -> EquityQuery
Screener.add-sort: EquityQuery -> String -> Bool -> EquityQuery
Screener.set-limit: EquityQuery -> Int -> EquityQuery
Screener.set-offset: EquityQuery -> Int -> EquityQuery
Screener.screen: EquityQuery -> Result [ScreenResult] YahooFinanceError
Screener.day-gainers: () -> Result [ScreenResult] YahooFinanceError
Screener.day-losers: () -> Result [ScreenResult] YahooFinanceError
Screener.most-active: () -> Result [ScreenResult] YahooFinanceError
Screener.most-active-by-value: () -> Result [ScreenResult] YahooFinanceError
Screener.undervalued-large-caps: () -> Result [ScreenResult] YahooFinanceError
Screener.growth-stocks: () -> Result [ScreenResult] YahooFinanceError

Ticker helpers:

YahooFinance.sp500-ticker      # "^GSPC"
YahooFinance.dow30-ticker      # "^DJI"
YahooFinance.nasdaq-ticker     # "^IXIC"
YahooFinance.russell2000-ticker # "^RUT"

Tickers.apple                  # "AAPL"
Tickers.nvidia                 # "NVDA"
Tickers.mag7                   # ["AAPL", "MSFT", "GOOGL", ...]
Tickers.lookup: String -> Option String
Tickers.search: String -> [(String, String)]

Types

Many fundamentals and analyst fields are Option Float or Option Int because

Yahoo may omit fields or return null-like wrapper objects for some symbols.

Error Handling

All public network APIs return Result T YahooFinanceError.

import Kit.YahooFinance as YahooFinance

main = fn =>
  match YahooFinance.get-quote "INVALID"
    | Ok quote -> println "${quote.symbol}: ${Float.to-string quote.price}"
    | Err (NotFoundError {symbol}) -> println "Unknown symbol: ${symbol}"
    | Err (NetworkError {message}) -> println "Network issue: ${message}"
    | Err e -> println "Error: ${show e}"

main

Operational Notes

• Yahoo Finance does not provide an official public API for these endpoints.

Response formats and endpoint availability can change without notice.

• Market data may be delayed, commonly 15-20 minutes depending on exchange and

data type.

• The package uses browser-like headers and libcurl because Yahoo blocks many

non-browser request profiles.

• Some v7/v10 endpoints need crumb and cookie authentication. The implementation

acquires those through libcurl's cookie engine.

• Intraday intervals (Minute1 through Hour1) are only available for recent

ranges. Yahoo commonly limits intraday history to 7-60 days.

• Respect Yahoo's rate limits. Repeated rapid requests can produce HTTP 429 or

temporary IP-level blocking.

• Data is intended for personal, educational, and development use. Commercial

use may require licensing from Yahoo or the underlying exchanges.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic-quote.kit

Compile an example to a native binary:

kit build examples/basic-quote.kit
./basic-quote

Some examples hit live Yahoo endpoints and are marked @check(interactive) so

parity checks build them without comparing nondeterministic live output.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow:

kit dev

This will:

1. Format package files
2. Type check src/
3. Type check examples/
4. Run tests with coverage

Running Parity

Run interpreter/build parity checks for examples:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Kit sources with doc comments (##) generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts defined in kit.toml:

kit task clean

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/yahoo-finance/, making it

available for import as Kit.YahooFinance in other projects.

License

This package is released under the MIT License. See LICENSE for details.

Yahoo Finance is a service of Yahoo. This package is an unofficial client for

public Yahoo Finance web endpoints and is not affiliated with or endorsed by Yahoo.

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