finance_query/
lib.rs

1//! # finance-query
2//!
3//! A Rust library for fetching financial data from Yahoo Finance.
4//! Inspired by yfinance, with smart lazy loading for efficient data fetching.
5//!
6//! ## Quick Start
7//!
8//! ```no_run
9//! use finance_query::Ticker;
10//!
11//! #[tokio::main]
12//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
13//!     // Simple: Create a ticker with default configuration
14//!     let ticker = Ticker::new("AAPL").await?;
15//!
16//!     // First access to any quote property fetches ALL quote modules in one request
17//!     if let Some(financials) = ticker.financial_data().await? {
18//!         println!("Financial data: {:?}", financials);
19//!     }
20//!
21//!     // Subsequent accesses use cached data (no additional network calls)
22//!     if let Some(profile) = ticker.asset_profile().await? {
23//!         println!("Company profile: {:?}", profile);
24//!     }
25//!
26//!     // Chart data is fetched separately and cached by interval/range
27//!     let chart = ticker.chart(
28//!         finance_query::Interval::OneDay,
29//!         finance_query::TimeRange::OneMonth
30//!     ).await?;
31//!     println!("Candles: {}", chart.candles.len());
32//!
33//!     // Builder pattern: Fluent configuration
34//!     let ticker_jp = Ticker::builder("7203.T")
35//!         .lang("ja-JP")
36//!         .region_code("JP")
37//!         .timeout(std::time::Duration::from_secs(30))
38//!         .build()
39//!         .await?;
40//!
41//!     Ok(())
42//! }
43//! ```
44//!
45//! ## Lazy Loading
46//!
47//! The library uses lazy loading:
48//! - **Quote data**: All ~30 quote modules fetched together on first property access
49//! - **Chart data**: Fetched per (interval, range) combination and cached
50//! - **Recommendations**: Fetched once and cached
51//!
52//! This approach minimizes network requests while keeping memory usage efficient.
53
54#![warn(missing_docs)]
55#![warn(rustdoc::missing_crate_level_docs)]
56
57// === Modules ===
58// Public modules
59/// Error types and result definitions.
60pub mod error;
61/// Non-symbol-specific operations (search, lookup, screeners, market data, etc.).
62pub mod finance;
63
64// Internal modules
65mod auth;
66mod client;
67mod constants;
68mod endpoints;
69mod models;
70mod scrapers;
71mod ticker;
72mod tickers;
73
74// ============================================================================
75// High-level API - Primary interface for most use cases
76// ============================================================================
77pub use ticker::{Ticker, TickerBuilder};
78pub use tickers::{BatchChartsResponse, BatchQuotesResponse, Tickers, TickersBuilder};
79
80// ============================================================================
81// Error types and results
82// ============================================================================
83pub use error::{Result, YahooError};
84
85// ============================================================================
86// Options - Configure API requests
87// ============================================================================
88pub use finance::{LookupOptions, LookupType, SearchOptions};
89
90// ============================================================================
91// Parameter enums - Used with Ticker and finance methods
92// ============================================================================
93pub use constants::indices::Region as IndicesRegion;
94pub use constants::screener_query;
95pub use constants::screener_types::ScreenerType;
96pub use constants::sector_types::SectorType;
97pub use constants::{Frequency, Interval, Region, StatementType, TimeRange, ValueFormat};
98
99// ============================================================================
100// Response types - Top-level types returned by API methods
101// ============================================================================
102pub use models::{
103    chart::Chart, currencies::Currency, exchanges::Exchange, financials::FinancialStatement,
104    hours::MarketHours, indicators::IndicatorsSummary, industries::Industry, lookup::LookupResults,
105    market_summary::MarketSummaryQuote, news::News, options::Options, quote::Quote,
106    recommendation::Recommendation, screeners::ScreenerResults, search::SearchResults,
107    sectors::Sector, transcript::Transcript, transcript::TranscriptWithMeta,
108    trending::TrendingQuote,
109};
110
111// ============================================================================
112// Nested types - Commonly accessed fields within response types
113// ============================================================================
114pub use models::{
115    chart::{Candle, CapitalGain, ChartMeta, Dividend, Split},
116    hours::MarketTime,
117    lookup::LookupQuote,
118    market_summary::SparkData,
119    options::{Contracts, OptionChain, OptionContract, OptionsQuote},
120    quote::FormattedValue,
121    recommendation::SimilarSymbol,
122    screeners::ScreenerQuote,
123    search::{
124        ResearchReport, ResearchReports, SearchNews, SearchNewsList, SearchQuote, SearchQuotes,
125    },
126};
127
128// ============================================================================
129// Query builders - Types for constructing custom screener queries
130// ============================================================================
131pub use models::screeners::{QueryCondition, QueryGroup, QueryOperand, QueryValue, ScreenerQuery};
132
133// ============================================================================
134// Real-time streaming
135// ============================================================================
136// WebSocket-based real-time price streaming with a Flow-like Stream API.
137pub mod streaming;
138
139// ============================================================================
140// DataFrame support (requires "dataframe" feature)
141// ============================================================================
142// When enabled, structs with #[derive(ToDataFrame)] get a to_dataframe() method.
143// The derive macro auto-generates DataFrame conversion for all scalar fields.
144#[cfg(feature = "dataframe")]
145pub use finance_query_derive::ToDataFrame;
finance_query/lib.rs

finance_query/
lib.rs
