Crate yfinance_rs 

yfinance-rs

An ergonomic, async-first Rust client for the unofficial Yahoo Finance API.

This crate provides a simple and efficient way to fetch financial data from Yahoo Finance. It is designed to feel familiar to users of the popular Python yfinance library, but leverages Rust’s powerful type system and async capabilities for performance and safety.

Features

Core Data

• Historical Data: Fetch daily, weekly, or monthly OHLCV data with automatic split/dividend adjustments.
• Real-time Quotes: Get live quote updates with detailed market information.
• Fast Quotes: Optimized quote fetching with essential data only (fast_info).
• Multi-Symbol Downloads: Concurrently download historical data for many symbols at once.
• Batch Quotes: Fetch quotes for multiple symbols efficiently.

Corporate Actions & Dividends

• Dividend History: Fetch complete dividend payment history with amounts and dates.
• Stock Splits: Get stock split history with split ratios.
• Capital Gains: Retrieve capital gains distributions (especially for mutual funds).
• All Corporate Actions: Comprehensive access to dividends, splits, and capital gains in one call.

Financial Statements & Fundamentals

• Income Statements: Access annual and quarterly income statements.
• Balance Sheets: Get annual and quarterly balance sheet data.
• Cash Flow Statements: Fetch annual and quarterly cash flow data.
• Earnings Data: Historical earnings, revenue estimates, and EPS data.
• Shares Outstanding: Historical data on shares outstanding (annual and quarterly).
• Corporate Calendar: Earnings dates, ex-dividend dates, and dividend payment dates.

Options & Derivatives

• Options Chains: Fetch expiration dates and full option chains (calls and puts).
• Option Contracts: Detailed option contract information including Greeks.

Analysis & Research

• Analyst Ratings: Get price targets, recommendations, and upgrade/downgrade history.
• Earnings Trends: Detailed earnings and revenue estimates from analysts.
• Recommendations Summary: Summary of current analyst recommendations.
• Upgrades/Downgrades: History of analyst rating changes.

Ownership & Holders

• Major Holders: Get major, institutional, and mutual fund holder data.
• Institutional Holders: Top institutional shareholders and their holdings.
• Mutual Fund Holders: Mutual fund ownership breakdown.
• Insider Transactions: Recent insider buying and selling activity.
• Insider Roster: Company insiders and their current holdings.
• Net Share Activity: Summary of insider purchase/sale activity.

ESG & Sustainability

• ESG Scores: Fetch detailed Environmental, Social, and Governance ratings.
• ESG Involvement: Specific ESG involvement and controversy data.

News & Information

• Company News: Retrieve the latest articles and press releases for a ticker.
• Company Profiles: Detailed information about companies, ETFs, and funds.
• Search: Find tickers by name or keyword.

Real-time Streaming

• WebSocket Streaming: Get live quote updates using WebSockets (preferred method).
• HTTP Polling: Fallback polling method for real-time data.
• Configurable Streaming: Customize update frequency and change-only filtering.

Advanced Features

• Data Repair: Automatic detection and repair of price outliers.
• Data Rounding: Control price precision and rounding.
• Missing Data Handling: Configurable handling of NA/missing values.
• Back Adjustment: Alternative price adjustment methods.
• Historical Metadata: Timezone and other metadata for historical data.
• ISIN Lookup: Get International Securities Identification Numbers.

Developer Experience

• Async API: Built on tokio and reqwest for non-blocking I/O.
• High-Level Ticker Interface: A convenient, yfinance-like struct for accessing all data for a single symbol.
• Builder Pattern: Fluent builders for constructing complex queries.
• Configurable Retries: Automatic retries with exponential backoff for transient network errors.
• Caching: Configurable caching behavior for API responses.
• Custom Timeouts: Configurable request timeouts and connection settings.

Quick Start

To get started, add yfinance-rs to your Cargo.toml:

[dependencies]
yfinance-rs = "0.1.2"
tokio = { version = "1", features = ["full"] }

Then, create a YfClient and use a Ticker to fetch data.

use yfinance_rs::{Interval, Range, Ticker, YfClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = YfClient::default();
    let ticker = Ticker::new(client, "AAPL".to_string());

    // Get the latest quote
    let quote = ticker.quote().await?;
    println!("Latest price for AAPL: ${:.2}", quote.regular_market_price.unwrap_or(0.0));

    // Get historical data for the last 6 months
    let history = ticker.history(Some(Range::M6), Some(Interval::D1), false).await?;
    if let Some(last_bar) = history.last() {
        println!("Last closing price: ${:.2} on timestamp {}", last_bar.close, last_bar.ts);
    }

    // Get analyst recommendations
    let recs = ticker.recommendations().await?;
    if let Some(latest_rec) = recs.first() {
        println!("Latest recommendation period: {}", latest_rec.period);
    }

    Ok(())
}

Re-exports

pub use analysis::EarningsTrendRow;

pub use analysis::PriceTarget;

pub use analysis::RecommendationRow;

pub use analysis::RecommendationSummary;

pub use analysis::UpgradeDowngradeRow;

pub use core::Action;

pub use core::Candle;

pub use core::HistoryMeta;

pub use core::HistoryResponse;

pub use core::Interval;

pub use core::Quote;

pub use core::Range;

pub use core::YfClient;

pub use core::YfClientBuilder;

pub use core::YfError;

pub use download::DownloadBuilder;

pub use download::DownloadResult;

pub use esg::EsgBuilder;

pub use esg::EsgInvolvement;

pub use esg::EsgScores;

pub use fundamentals::BalanceSheetRow;

pub use fundamentals::Calendar as FundCalendar;

pub use fundamentals::CashflowRow;

pub use fundamentals::Earnings;

pub use fundamentals::EarningsQuarter;

pub use fundamentals::EarningsQuarterEps;

pub use fundamentals::EarningsYear;

pub use fundamentals::FundamentalsBuilder;

pub use fundamentals::IncomeStatementRow;

pub use fundamentals::Num;

pub use fundamentals::ShareCount;

pub use history::HistoryBuilder;

pub use holders::HoldersBuilder;

pub use holders::InsiderRosterHolder;

pub use holders::InsiderTransaction;

pub use holders::InstitutionalHolder;

pub use holders::MajorHolder;

pub use holders::NetSharePurchaseActivity;

pub use news::NewsArticle;

pub use news::NewsBuilder;

pub use news::NewsTab;

pub use profile::Address;

pub use profile::Company;

pub use profile::Fund;

pub use profile::Profile;

pub use quote::QuotesBuilder;

pub use quote::quotes;

pub use search::SearchBuilder;

pub use search::SearchQuote;

pub use search::SearchResponse;

pub use stream::QuoteUpdate;

pub use stream::StreamBuilder;

pub use stream::StreamConfig;

pub use stream::StreamHandle;

pub use stream::StreamMethod;

pub use ticker::FastInfo;

pub use ticker::Info;

pub use ticker::OptionChain;

pub use ticker::OptionContract;

pub use ticker::Ticker;

Modules

analysis

Fetch analyst ratings, price targets, and upgrade/downgrade history.

core

Core components, including the YfClient and YfError. Core components of the yfinance-rs client.

download

Download historical data for multiple symbols concurrently.

esg

Fetch ESG (Environmental, Social, Governance) scores and involvement data.

fundamentals

Fetch financial statements (income, balance sheet, cash flow) and earnings data.

history

Fetch historical OHLCV data for a single symbol.

holders

Fetch holder information, including major, institutional, and insider holders.

news

Fetch news articles for a ticker.

profile

Retrieve company or fund profile information. Public profile types + loading strategy (API first, then scrape).

quote

Fetch quotes for multiple symbols.

search

Search for tickers by name or keyword.

stream

Stream real-time quote updates via WebSockets or polling.

ticker

A high-level interface for a single ticker, providing access to all data types.