# finance-query
> Generated by `cargo soothfast report`, derived from the current code and
> measurements rather than hand-written. Trust it over any prose.
## Public API
### `pub struct AnalystEstimate`
### `pub struct AnalystRecommendation`
### `pub struct AroonData`
### `pub enum AssetClass`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `define_batch_response!`
### `pub struct BollingerBands`
### `pub struct BollingerBandsData`
### `pub struct BullBearPowerData`
### `pub enum CalendarDetail`
### `pub struct CalendarEvent`
### `pub enum CalendarKind`
### `pub struct Candle`
### `pub enum CandlePattern`
### `pub struct Capability(u32)`
**Measured:** 68 instructions/iter, 3ns median, 0 allocs/iter
### `pub struct CapitalGain`
### `pub struct Chart`
**Measured:** 109149 instructions/iter, 8840ns median, 13 allocs/iter
### `pub struct ChartEvents`
### `pub struct ChartMeta`
### `pub struct CikEntry`
### `pub struct ClientHandle(pub(crate) Arc<YahooClient>)`
### `pub struct CommitmentsOfTraders`
### `domain_handle!`
### `pub struct CommodityQuote`
### `pub struct CompanyFacts`
**Measured:** 13931032 instructions/iter, 1279280ns median, 11899 allocs/iter
### `pub struct CompanyProfile`
### `pub enum ConditionValue`
### `pub struct CongressionalTrade`
### `pub struct Contracts(pub Vec<OptionContract>)`
### `pub struct CotObservation`
### `domain_handle!`
### `pub trait CryptoProvider: ProviderCore`
### `pub struct CryptoQuote`
### `pub struct Currency`
**Measured:** 223104 instructions/iter, 19332ns median, 8 allocs/iter
### `pub struct CustomId(u16)`
### `domain_handle!`
### `pub struct Dividend`
### `pub struct DividendAnalytics`
### `pub struct DonchianChannelsData`
### `pub struct EarningsCalendarEntry`
### `pub struct EarningsSurprise`
### `pub struct EarningsTranscript`
### `pub struct EconomicCatalog`
### `pub struct EconomicCategory`
### `domain_handle!`
### `pub trait EconomicProvider: ProviderCore`
### `pub struct EconomicRelease`
### `pub struct EconomicSeries`
### `pub struct EconomicSeriesMatch`
### `pub struct EdgarFiling`
### `pub struct EdgarFilingFile`
### `pub struct EdgarFilingIndex`
### `pub struct EdgarFilingIndexItem`
### `pub struct EdgarFilingRecent`
### `pub struct EdgarFilings`
### `pub struct EdgarSearchHit`
### `pub struct EdgarSearchHitsContainer`
### `pub struct EdgarSearchResults`
### `pub struct EdgarSearchSource`
### `pub struct EdgarSearchTotal`
### `pub struct EdgarSubmissions`
**Measured:** 5293321 instructions/iter, 532200ns median, 6784 allocs/iter
### `pub struct ElderRayData`
### `pub struct EmployeeCount`
### `pub enum EquityField`
### `pub type EquityScreenerQuery = ScreenerQuery<EquityField>`
### `pub enum ErrorCategory`
### `pub struct EtfCountryWeighting`
### `pub struct EtfHolding`
### `pub struct EtfProfile`
### `pub struct EtfSectorWeighting`
### `pub enum EventKind`
### `pub struct Exchange`
### `pub enum ExchangeCode`
### `pub struct ExchangeInfo`
### `pub struct ExecutiveCompensation`
### `pub struct FactConcept`
### `pub struct FactUnit`
### `pub struct FactsByTaxonomy(pub HashMap<String, FactConcept>)`
### `pub struct FailToDeliver`
### `pub struct FearAndGreed`
**Measured:** 15650 instructions/iter, 1293ns median, 3 allocs/iter
### `pub enum FearGreedLabel`
### `pub enum Fetch`
### `pub struct FilingSearchFilters`
### `pub struct FilingSearchHit`
### `pub struct FilingSection`
### `pub enum FilingSectionForm`
### `domain_handle!`
### `pub enum FinanceError`
### `pub struct FinancialRatiosTtm`
### `pub struct FinancialStatement`
**Measured:** 237220 instructions/iter, 20809ns median, 206 allocs/iter
### `domain_handle!`
### `pub trait ForexProvider: ProviderCore`
### `pub struct ForexQuote`
### `pub struct FormattedValue<T>`
### `pub enum Frequency`
### `pub enum FundField`
### `pub type FundScreenerQuery = ScreenerQuery<FundField>`
### `domain_handle!`
### `pub struct FuturesQuote`
### `pub struct GradingAction`
### `pub struct IchimokuData`
### `domain_handle!`
### `pub struct IndexConstituent`
### `pub struct IndexConstituentChange`
### `pub struct IndexQuote`
### `pub enum Indicator`
### `pub enum IndicatorError`
### `pub enum IndicatorResult`
### `pub struct IndicatorsSummary`
### `pub enum Region`
### `pub enum Industry`
### `pub struct IndustryData`
### `pub struct IndustryPe`
### `pub struct InsiderTrade`
### `pub struct InsiderTransaction`
### `pub struct InstitutionalHolding`
### `pub enum Interval`
### `pub struct IpoCalendarEntry`
### `pub struct KeltnerChannelsData`
### `pub struct KeyMetricsTtm`
### `pub enum LogicalOperator`
### `pub struct LookupOptions`
### `pub struct LookupQuote`
### `pub struct LookupResults`
### `pub enum LookupType`
### `pub struct MacdData`
### `pub struct MacdResult`
### `pub enum MajorIndex`
### `pub struct Market`
### `domain_handle!`
### `pub struct MarketCalendarEntry`
### `pub struct MarketHours`
**Measured:** 7536 instructions/iter, 673ns median, 10 allocs/iter
### `pub struct MarketSnapshot`
### `pub struct MarketSummaryQuote`
**Measured:** 262258 instructions/iter, 28206ns median, 228 allocs/iter
### `pub struct MarketTime`
### `pub enum MoverDirection`
### `pub struct MoverQuote`
### `pub struct News`
**Measured:** 45306 instructions/iter, 3764ns median, 53 allocs/iter
### `pub enum Operation`
### `pub enum Operator`
### `pub struct OptionChain`
### `pub struct OptionContract`
### `pub struct Options`
**Measured:** 12505 instructions/iter, 1033ns median, 6 allocs/iter
### `pub struct OptionsQuote`
### `pub enum PatternSentiment`
### `pub enum Period`
### `pub struct PressRelease`
### `pub struct PriceTargetConsensus`
### `pub struct PriceTargetSummary`
### `pub enum Provider`
### `pub struct ProviderFiling`
### `pub struct ProviderFilings`
### `pub struct ProviderHealth`
### `pub struct Providers`
### `pub struct ProvidersBuilder`
### `pub struct QueryCondition<F: ScreenerField>`
### `pub struct QueryGroup<F: ScreenerField>`
### `pub enum QueryOperand<F: ScreenerField>`
### `pub struct Quote<F: Format = Both>`
**Measured:** 9567936 instructions/iter, 968702ns median, 8235 allocs/iter
### `pub struct QuoteSummaryResponse`
### `pub enum QuoteType`
### `pub struct RatingConsensus`
### `pub struct Recommendation`
### `pub enum Region`
### `pub struct ResearchReport`
### `pub struct ResearchReports(pub Vec<ResearchReport>)`
### `pub type Result<T> = std::result::Result<T, FinanceError>`
### `pub struct RetryPolicy`
### `pub struct RiskFactor`
### `pub struct Routes`
### `pub enum Screener`
### `pub trait ScreenerField: Clone + Serialize + 'static`
### `pub trait ScreenerFieldExt: ScreenerField + Sized`
### `pub struct ScreenerFilters`
### `pub enum ScreenerFundCategory`
### `pub struct ScreenerMatch`
### `pub enum ScreenerPeerGroup`
### `pub struct ScreenerQuery<F: ScreenerField = EquityField>`
### `pub struct ScreenerQuote`
### `pub struct ScreenerResults`
**Measured:** 3849278 instructions/iter, 425083ns median, 4498 allocs/iter
### `pub struct SearchNews`
### `pub struct SearchNewsList(pub Vec<SearchNews>)`
### `pub struct SearchOptions`
### `pub struct SearchQuote`
### `pub struct SearchQuotes(pub Vec<SearchQuote>)`
### `pub struct SearchResults`
**Measured:** 56239 instructions/iter, 4876ns median, 55 allocs/iter
### `pub enum Sector`
### `pub struct SectorData`
### `pub struct SectorPe`
### `pub struct SectorPerformance`
### `pub struct SectorPerformanceHistory`
### `pub struct Sentiment`
### `pub enum SentimentLabel`
### `pub struct ShareFloat`
### `pub struct ShortInterest`
### `pub struct ShortVolume`
### `pub struct SimilarSymbol`
### `domain_handle!`
### `pub enum SortType`
### `pub struct Spark`
### `pub struct SparkData`
### `pub struct Split`
### `pub enum StatementType`
### `pub struct StochasticData`
### `pub struct SuperTrendData`
### `pub struct SymbolDetails`
### `pub struct SymbolMatch`
### `pub struct SymbolSentiment`
### `pub struct Ticker`
### `pub struct TickerBuilder`
### `pub struct Tickers`
### `pub struct TickersBuilder`
### `pub enum TimeRange`
### `pub struct Transcript`
### `pub struct TranscriptWithMeta`
### `pub struct TrendingQuote`
**Measured:** 18398 instructions/iter, 1348ns median, 24 allocs/iter
### `pub enum ValueFormat`
### `pub fn init(api_key: impl Into<String>) -> Result<()>`
Initialize the global Alpha Vantage client with an API key.
Must be called once before using any query functions. Subsequent calls return an error.
#### Arguments
* `api_key` - Your Alpha Vantage API key (free at <https://www.alphavantage.co/support/#api-key>)
#### Errors
Returns [`crate::FinanceError::InvalidParameter`] if already initialized.
### `pub fn init_with_timeout(api_key: impl Into<String>, timeout: Duration) -> Result<()>`
Initialize the Alpha Vantage client with a custom timeout.
### `pub struct EarningsCalendarEntryDTO`
A single earnings calendar entry.
### `pub struct IpoCalendarEntryDTO`
A single IPO calendar entry.
### `pub async fn fetch_commitments_of_traders_response(symbol: &str) -> Result<CommitmentsOfTraders>`
Fetch the canonical Commitments of Traders series for a futures symbol.
### `pub async fn coin(id: &str, vs_currency: &str) -> Result<CoinQuote>`
Fetch a single coin by its CoinGecko ID (e.g., `"bitcoin"`, `"ethereum"`).
Use <https://api.coingecko.com/api/v3/coins/list> to discover CoinGecko IDs.
#### Arguments
* `id` - CoinGecko coin ID
* `vs_currency` - Quote currency (e.g., `"usd"`)
### `pub async fn coins(vs_currency: &str, count: usize) -> Result<Vec<CoinQuote>>`
Fetch the top `count` cryptocurrencies by market cap.
#### Arguments
* `vs_currency` - Quote currency (e.g., `"usd"`, `"eur"`, `"btc"`)
* `count` - Number of coins to return (max 250)
#### Errors
Returns an error on network failure or if the CoinGecko API rate limit is exceeded.
### `pub async fn fetch_symbol_search_response(query: &str, limit: u32) -> Result<Vec<SymbolMatch>>`
Search CoinGecko's coin catalog by free-text query, as canonical
[`SymbolMatch`]es. `limit` truncates the result — CoinGecko's `/search`
takes no page size and returns every match in one response.
### `pub async fn fetch_crypto_global_response() -> Result<crate::models::crypto::GlobalCryptoStats>`
Fetch aggregate global cryptocurrency market statistics.
### `pub async fn fetch_crypto_trending_response() -> Result<Vec<crate::models::crypto::TrendingCoin>>`
Fetch coins trending in the last 24h as canonical [`TrendingCoin`](crate::models::crypto::TrendingCoin)s.
### `pub async fn company_facts(cik: u64) -> Result<CompanyFacts>`
Fetch structured XBRL financial data for a CIK.
Returns all extracted XBRL facts organized by taxonomy (us-gaap, ifrs, dei).
This can be a large response (several MB for major companies).
#### Example
```no_run
use finance_query::edgar;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
edgar::init("user@example.com")?;
let cik = edgar::resolve_cik("AAPL").await?;
let facts = edgar::company_facts(cik).await?;
println!("Entity: {:?}", facts.entity_name);
# Ok(())
# }
```
### `pub async fn filing_index(accession_number: &str) -> Result<EdgarFilingIndex>`
Fetch the filing index for a specific accession number.
This provides the file list for a filing, which can be used to locate
the primary HTML document and file sizes.
#### Example
```no_run
use finance_query::edgar;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
edgar::init("user@example.com")?;
let index = edgar::filing_index("0000320193-24-000123").await?;
println!("Files: {}", index.directory.item.len());
# Ok(())
# }
```
### `pub fn init(email: impl Into<String>) -> Result<()>`
Initialize the global EDGAR client with a contact email.
This function must be called once before using any EDGAR functions.
The SEC requires all automated requests to include a User-Agent header
with a contact email address.
#### Arguments
* `email` - Contact email address (included in User-Agent header)
#### Example
```no_run
use finance_query::edgar;
# fn example() -> Result<(), Box<dyn std::error::Error>> {
edgar::init("user@example.com")?;
# Ok(())
# }
```
#### Errors
Returns an error if EDGAR has already been initialized.
### `pub fn init_with_config( email: impl Into<String>, app_name: impl Into<String>, timeout: Duration, ) -> Result<()>`
Initialize the global EDGAR client with full configuration.
Use this for custom app name and timeout settings.
#### Arguments
* `email` - Contact email address (required by SEC)
* `app_name` - Application name (included in User-Agent)
* `timeout` - HTTP request timeout duration
#### Example
```no_run
use finance_query::edgar;
use std::time::Duration;
# fn example() -> Result<(), Box<dyn std::error::Error>> {
edgar::init_with_config(
"user@example.com",
"my-app",
Duration::from_secs(60),
)?;
# Ok(())
# }
```
### `pub async fn resolve_cik(symbol: &str) -> Result<u64>`
Resolve a ticker symbol to its SEC CIK number.
The ticker-to-CIK mapping is fetched once and cached process-wide.
Lookups are case-insensitive.
#### Example
```no_run
use finance_query::edgar;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
edgar::init("user@example.com")?;
let cik = edgar::resolve_cik("AAPL").await?;
assert_eq!(cik, 320193);
# Ok(())
# }
```
#### Errors
Returns an error if:
- EDGAR has not been initialized (call `init()` first)
- Symbol not found in SEC database
- Network request fails
### `pub async fn search( query: &str, forms: Option<&[&str]>, start_date: Option<&str>, end_date: Option<&str>, from: Option<usize>, size: Option<usize>, ) -> Result<EdgarSearchResults>`
Search SEC EDGAR filings by text content.
#### Arguments
* `query` - Search term or phrase
* `forms` - Optional form type filter (e.g., `&["10-K", "10-Q"]`)
* `start_date` - Optional start date (YYYY-MM-DD)
* `end_date` - Optional end date (YYYY-MM-DD)
* `from` - Optional pagination offset (default: 0)
* `size` - Optional page size (default: 100, max: 100)
#### Example
```no_run
use finance_query::edgar;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
edgar::init("user@example.com")?;
let results = edgar::search(
"artificial intelligence",
Some(&["10-K"]),
Some("2024-01-01"),
None,
Some(0),
Some(100),
).await?;
if let Some(hits_container) = &results.hits {
println!("Found {} results", hits_container.total.as_ref().and_then(|t| t.value).unwrap_or(0));
}
# Ok(())
# }
```
### `pub async fn submissions(cik: u64) -> Result<EdgarSubmissions>`
Fetch filing history and company metadata for a CIK.
Returns the most recent ~1000 filings inline, with references to
additional history files for older filings.
#### Example
```no_run
use finance_query::edgar;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
edgar::init("user@example.com")?;
let cik = edgar::resolve_cik("AAPL").await?;
let submissions = edgar::submissions(cik).await?;
println!("Company: {:?}", submissions.name);
# Ok(())
# }
```
### `pub struct InsiderTradeDTO`
Insider trading transaction record.
### `pub struct AnalystEstimateDTO`
Analyst estimate entry.
### `pub struct AnalystRecommendationDTO`
Analyst recommendation entry.
### `pub fn init(api_key: impl Into<String>) -> Result<()>`
Initialize the global FMP client with an API key.
Must be called once before using any query functions. Subsequent calls return an error.
#### Errors
Returns [`FinanceError::InvalidParameter`] if already initialized.
### `pub fn init_with_timeout(api_key: impl Into<String>, timeout: Duration) -> Result<()>`
Initialize the FMP client with a custom timeout.
### `pub fn init(api_key: impl Into<String>) -> Result<()>`
Initialize the global FRED client with an API key.
Must be called once before [`series`]. Subsequent calls return an error.
#### Arguments
* `api_key` - Your FRED API key (free at <https://fred.stlouisfed.org/docs/api/api_key.html>)
#### Errors
Returns [`FinanceError::InvalidParameter`] if already initialized.
### `pub fn init_with_timeout(api_key: impl Into<String>, timeout: Duration) -> Result<()>`
Initialize the FRED client with a custom timeout.
### `pub struct ReleaseDate`
A single scheduled economic-data release date from the FRED
`releases/dates` endpoint.
### `pub async fn release_dates() -> Result<Vec<ReleaseDate>>`
Fetch upcoming scheduled economic-data release dates (CPI, NFP, GDP, FOMC, …).
Returns releases scheduled from today onward, sorted ascending.
#### Errors
Returns [`FinanceError::InvalidParameter`] if FRED has not been initialized.
### `pub async fn series(series_id: &str) -> Result<MacroSeries>`
Fetch all observations for a FRED data series.
Common series IDs:
- `"FEDFUNDS"` — Federal Funds Rate
- `"CPIAUCSL"` — Consumer Price Index (all urban, seasonally adjusted)
- `"UNRATE"` — Unemployment Rate
- `"DGS10"` — 10-Year Treasury Constant Maturity Rate
- `"M2SL"` — M2 Money Supply
- `"GDP"` — US Gross Domestic Product
#### Errors
Returns [`FinanceError::InvalidParameter`] if FRED has not been initialized.
### `pub async fn treasury_yields(year: u32) -> Result<Vec<TreasuryYield>>`
Fetch US Treasury yield curve data for the given year.
No API key required. Data is published on each business day.
#### Arguments
* `year` - Calendar year (e.g., `2025`). Pass the current year for recent data.
### `pub async fn fetch_news_response(symbol: &str) -> Result<Vec<News>>`
Fetch canonical news articles for a symbol.
### `pub fn init(api_key: impl Into<String>) -> Result<()>`
Initialize the global Polygon client with an API key.
Must be called once before using any query functions. Subsequent calls return an error.
#### Errors
Returns [`FinanceError::InvalidParameter`] if already initialized.
### `pub fn init_with_timeout(api_key: impl Into<String>, timeout: Duration) -> Result<()>`
Initialize the Polygon client with a custom timeout.
### `pub struct LookupOptions`
Lookup configuration options
### `pub enum LookupType`
Asset types available for lookup
### `pub struct SearchOptions`
Search configuration options
### `pub fn init(api_key: impl Into<String>) -> Result<()>`
### `pub fn init_with_timeout(api_key: impl Into<String>, timeout: Duration) -> Result<()>`
### `pub async fn analyst_estimates(symbol: &str, period: Period) -> Result<Vec<AnalystEstimate>>`
### `pub async fn analyst_recommendations(symbol: &str) -> Result<Vec<AnalystRecommendation>>`
### `pub fn analyze(text: &str) -> Sentiment`
**Measured:** 924402 instructions/iter, 86810ns median, 976 allocs/iter
### `pub fn atr(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
### `pub struct BacktestComparison`
### `pub struct BacktestConfig`
### `pub struct BacktestConfigBuilder`
### `pub struct BacktestEngine`
### `pub enum BacktestError`
### `pub struct BacktestResult`
### `pub struct BayesianSearch`
**Measured:** 29268707 instructions/iter, 3072377ns median, 2382 allocs/iter
### `pub struct BenchmarkMetrics`
### `pub struct BollingerMeanReversion`
### `pub struct ComparisonReport`
### `pub struct ComparisonRow`
### `pub struct DonchianBreakout`
### `pub enum EnsembleMode`
### `pub struct EnsembleStrategy`
### `pub struct EquityPoint`
### `pub struct GridSearch`
**Measured:** 13134792 instructions/iter, 648320ns median, 3012 allocs/iter
### `pub struct MacdSignal`
### `pub struct MonteCarloConfig`
**Measured:** 1091478 instructions/iter, 177390ns median, 6 allocs/iter
### `pub enum MonteCarloMethod`
### `pub struct MonteCarloResult`
### `pub struct OptimizationReport`
### `pub struct OptimizationResult`
### `pub enum OptimizeMetric`
### `pub enum OrderType`
### `pub enum ParamRange`
### `pub enum ParamValue`
### `pub struct ParetoPoint`
### `pub struct ParetoReport`
### `pub struct PendingOrder`
### `pub struct PercentileStats`
### `pub struct PerformanceMetrics`
### `pub struct Position`
### `pub struct PositionExtremes`
### `pub enum PositionSide`
### `pub enum PositionSizing`
### `pub type Result<T> = std::result::Result<T, BacktestError>`
### `pub struct RsiReversal`
### `pub struct Signal`
### `pub enum SignalDirection`
### `pub struct SignalMetadata`
### `pub struct SignalRecord`
### `pub struct SignalStrength(f64)`
### `pub struct SizingContext`
### `pub struct SmaCrossover`
### `pub trait Strategy: Send + Sync`
### `pub struct StrategyBuilder<E = (), X = ()>`
**Measured:** 1077456 instructions/iter, 165408ns median, 328 allocs/iter
### `pub struct StrategyContext<'a>`
### `pub struct SuperTrendFollow`
### `pub struct Trade`
### `pub struct WalkForwardConfig`
### `pub struct WalkForwardReport`
### `pub struct WindowResult`
### `pub struct BacktestComparison`
Builder that accumulates [`BacktestResult`]s and ranks them.
#### Ordering
Call [`ranked_by`](BacktestComparison::ranked_by) to produce a
[`ComparisonReport`] sorted best-first by the chosen [`OptimizeMetric`].
### `pub fn ranked_by(self, metric: OptimizeMetric) -> ComparisonReport`
Rank all added results by `metric` and return a [`ComparisonReport`].
Results are sorted **best-first** (highest score wins for all metrics
except [`OptimizeMetric::MinDrawdown`], which is already negated
internally so that a lower drawdown yields a higher score).
### `pub struct ComparisonReport`
Ranked comparison of multiple backtest results produced by
[`BacktestComparison::ranked_by`].
### `pub struct ComparisonRow`
A single row in the comparison table — one strategy's key metrics.
### `pub struct Above<R: IndicatorRef>`
### `pub struct AboveRef<R1: IndicatorRef, R2: IndicatorRef>`
### `pub struct All<C: Condition>`
### `pub struct And<C1: Condition, C2: Condition>`
### `pub struct Any<C: Condition>`
### `pub struct Below<R: IndicatorRef>`
### `pub struct BelowRef<R1: IndicatorRef, R2: IndicatorRef>`
### `pub struct Between<R: IndicatorRef>`
### `pub trait Condition: Clone + Send + Sync + 'static`
A condition that can be evaluated on each candle.
Conditions are the building blocks of trading strategies.
They can be combined using `and()`, `or()`, and `not()` operations.
#### Example
```ignore
use finance_query::backtesting::condition::Condition;
fn my_custom_condition(ctx: &StrategyContext) -> bool {
// Custom logic here
true
}
```
### `pub struct ConditionBuilder<C: Condition>`
### `pub struct ConstantCondition(bool)`
A condition that always returns the same value.
Useful for testing or as a placeholder.
### `pub struct CrossesAbove<R: IndicatorRef>`
### `pub struct CrossesAboveRef<R1: IndicatorRef, R2: IndicatorRef>`
### `pub struct CrossesBelow<R: IndicatorRef>`
### `pub struct CrossesBelowRef<R1: IndicatorRef, R2: IndicatorRef>`
### `pub struct Equals<R: IndicatorRef>`
### `pub struct HasPosition`
### `pub struct HeldForBars`
### `pub struct HtfIndicatorSpec`
Describes an indicator that must be pre-computed on a resampled (HTF) candle series.
Returned by [`Condition::htf_requirements`] and processed by the engine to build
stretched arrays stored in `StrategyContext::indicators` under `htf_key`.
### `pub struct InLoss`
### `pub struct InProfit`
### `pub struct IsLong`
### `pub struct IsShort`
### `pub struct NoPosition`
### `pub struct Not<C: Condition>`
### `pub struct Or<C1: Condition, C2: Condition>`
### `pub struct StopLoss`
### `pub struct TakeProfit`
### `pub struct TrailingStop`
### `pub struct TrailingTakeProfit`
### `pub fn always_false() -> ConstantCondition`
Convenience function to create a condition that always returns false.
**Measured:** 250414 instructions/iter, 19411ns median, 6 allocs/iter
### `pub fn always_true() -> ConstantCondition`
Convenience function to create a condition that always returns true.
**Measured:** 4333659 instructions/iter, 420504ns median, 4045 allocs/iter
### `pub struct Above<R: IndicatorRef>`
Condition: indicator is above a threshold.
### `pub struct AboveRef<R1: IndicatorRef, R2: IndicatorRef>`
Condition: indicator is above another indicator.
### `pub struct Below<R: IndicatorRef>`
Condition: indicator is below a threshold.
### `pub struct BelowRef<R1: IndicatorRef, R2: IndicatorRef>`
Condition: indicator is below another indicator.
### `pub struct Between<R: IndicatorRef>`
Condition: indicator is between two thresholds.
True when `low < value < high`.
### `pub struct CrossesAbove<R: IndicatorRef>`
Condition: indicator crosses above a threshold.
True when the previous value was **at or below** the threshold (`prev <=
threshold`) and the current value is **strictly above** it (`curr >
threshold`). The inclusive previous-bar test prevents missing a crossover
when the value touches the threshold exactly before rising.
### `pub struct CrossesAboveRef<R1: IndicatorRef, R2: IndicatorRef>`
Condition: indicator crosses above another indicator.
True when the fast indicator was **at or below** the slow indicator on the
previous bar (`prev_fast <= prev_slow`) and is **strictly above** it on the
current bar (`curr_fast > curr_slow`).
#### Inclusive Previous Bar
The previous-bar test is inclusive (`<=`). This means the crossover fires
even if fast == slow on the prior bar, treating that touch as "not yet
crossed". This is the most common convention in technical analysis and
avoids missing a crossover when the lines converge exactly.
### `pub struct CrossesBelow<R: IndicatorRef>`
Condition: indicator crosses below a threshold.
True when the previous value was **at or above** the threshold (`prev >=
threshold`) and the current value is **strictly below** it (`curr <
threshold`). The inclusive previous-bar test prevents missing a crossover
when the value touches the threshold exactly before falling.
### `pub struct CrossesBelowRef<R1: IndicatorRef, R2: IndicatorRef>`
Condition: indicator crosses below another indicator.
True when the fast indicator was **at or above** the slow indicator on the
previous bar (`prev_fast >= prev_slow`) and is **strictly below** it on the
current bar (`curr_fast < curr_slow`).
#### Inclusive Previous Bar
The previous-bar test is inclusive (`>=`). See [`CrossesAboveRef`] for
rationale.
### `pub struct Equals<R: IndicatorRef>`
Condition: indicator equals a value (within tolerance).
### `pub struct All<C: Condition>`
A condition that evaluates to true when ALL inner conditions are true.
### `pub struct And<C1: Condition, C2: Condition>`
Condition: both conditions must be true (AND logic).
### `pub struct Any<C: Condition>`
A condition that evaluates to true when ANY inner condition is true.
### `pub struct ConditionBuilder<C: Condition>`
Builder for creating complex multi-condition combinations.
#### Example
```ignore
use finance_query::backtesting::condition::*;
use finance_query::backtesting::refs::*;
let conditions = ConditionBuilder::new()
.with_condition(rsi(14).below(30.0))
.with_condition(price().above_ref(sma(200)))
.with_condition(adx(14).above(25.0))
.all(); // All conditions must be true
// Or use any() for OR logic
let exit = ConditionBuilder::new()
.with_condition(rsi(14).above(70.0))
.with_condition(stop_loss(0.05))
.any(); // Any condition can be true
```
### `pub struct Not<C: Condition>`
Condition: negation of a condition (NOT logic).
### `pub struct Or<C1: Condition, C2: Condition>`
Condition: at least one condition must be true (OR logic).
### `pub fn has_position() -> HasPosition`
**Measured:** 4322667 instructions/iter, 415808ns median, 4045 allocs/iter
### `pub fn held_for_bars(min_bars: usize) -> HeldForBars`
**Measured:** 1519726 instructions/iter, 165795ns median, 1041 allocs/iter
### `pub fn in_loss() -> InLoss`
**Measured:** 4359954 instructions/iter, 420976ns median, 4045 allocs/iter
### `pub fn in_profit() -> InProfit`
**Measured:** 558438 instructions/iter, 49738ns median, 142 allocs/iter
### `pub fn is_long() -> IsLong`
**Measured:** 4317903 instructions/iter, 414241ns median, 4045 allocs/iter
### `pub fn is_short() -> IsShort`
**Measured:** 401363 instructions/iter, 36384ns median, 13 allocs/iter
### `pub fn no_position() -> NoPosition`
**Measured:** 401363 instructions/iter, 36402ns median, 13 allocs/iter
### `pub fn stop_loss(pct: f64) -> StopLoss`
**Measured:** 456653 instructions/iter, 44597ns median, 24 allocs/iter
### `pub fn take_profit(pct: f64) -> TakeProfit`
**Measured:** 443285 instructions/iter, 41509ns median, 13 allocs/iter
### `pub struct HasPosition`
Condition: check if we have any position.
### `pub struct HeldForBars`
Condition: position has been held for at least N bars.
### `pub struct InLoss`
Condition: position P/L is negative (in loss).
### `pub struct InProfit`
Condition: position P/L is positive (in profit).
### `pub struct IsLong`
Condition: check if we have a long position.
### `pub struct IsShort`
Condition: check if we have a short position.
### `pub struct NoPosition`
Condition: check if we have no position.
### `pub struct StopLoss`
Condition: position P/L is at or below the stop-loss threshold.
#### Execution Model
This condition evaluates at **bar close**: it fires when the closing price
implies a loss ≥ `pct`. The resulting exit signal is deferred to the **next
bar's open** (identical to all strategy-signal exits).
For intrabar detection (fill same bar at `min(open, stop_level)`), use
[`BacktestConfig::stop_loss_pct`](crate::backtesting::BacktestConfig::stop_loss_pct)
instead. A −10% intraday move that closes
at −3% will be caught by the config field but missed by this condition.
#### Example
```ignore
use finance_query::backtesting::condition::*;
let exit = stop_loss(0.05); // Exit if loss >= 5% at bar close
```
### `pub struct TakeProfit`
Condition: position P/L is at or above the take-profit threshold.
#### Execution Model
This condition evaluates at **bar close**: it fires when the closing price
implies a gain ≥ `pct`. The resulting exit signal is deferred to the **next
bar's open** (identical to all strategy-signal exits).
For intrabar detection (fill same bar at `max(open, target_level)`), use
[`BacktestConfig::take_profit_pct`](crate::backtesting::BacktestConfig::take_profit_pct) instead.
#### Example
```ignore
use finance_query::backtesting::condition::*;
let exit = take_profit(0.10); // Exit if gain >= 10% at bar close
```
### `pub struct TrailingStop`
Condition: trailing stop triggered when price retraces from peak/trough.
For long positions: tracks the highest price since entry and triggers
when price falls by `trail_pct` from that high.
For short positions: tracks the lowest price since entry and triggers
when price rises by `trail_pct` from that low.
#### Execution Model
The peak/trough is computed from bar **highs/lows** since entry, but the
trigger test uses the **bar close**. The exit signal is deferred to the
**next bar's open** (identical to all strategy-signal exits).
For intrabar enforcement, use [`BacktestConfig::trailing_stop_pct`](crate::backtesting::BacktestConfig::trailing_stop_pct) instead,
which fills on the same bar when the trailing level is breached intraday.
#### Example
```ignore
use finance_query::backtesting::condition::*;
// Exit if price drops 3% from highest point since entry
let exit = trailing_stop(0.03);
```
### `pub struct TrailingTakeProfit`
Condition: trailing take-profit triggered when profit retraces from peak.
For long positions: tracks the highest profit since entry and triggers
when profit falls by `trail_pct` from that peak profit.
For short positions: tracks the highest profit since entry and triggers
when profit falls by `trail_pct` from that peak profit.
This is useful for locking in gains - it only triggers after you've been
in profit and then profit starts declining.
#### Example
```ignore
use finance_query::backtesting::condition::*;
// Exit if profit drops 2% from highest profit achieved
let exit = trailing_take_profit(0.02);
```
### `pub fn has_position() -> HasPosition`
Create a condition that checks if we have any position.
### `pub fn held_for_bars(min_bars: usize) -> HeldForBars`
Create a condition that checks if position has been held for at least N bars.
### `pub fn in_loss() -> InLoss`
Create a condition that checks if position is at a loss.
### `pub fn in_profit() -> InProfit`
Create a condition that checks if position is profitable.
### `pub fn is_long() -> IsLong`
Create a condition that checks if we have a long position.
### `pub fn is_short() -> IsShort`
Create a condition that checks if we have a short position.
### `pub fn no_position() -> NoPosition`
Create a condition that checks if we have no position.
### `pub fn stop_loss(pct: f64) -> StopLoss`
Create a stop-loss condition.
#### Example
```ignore
use finance_query::backtesting::condition::*;
let exit = rsi(14).above(70.0).or(stop_loss(0.05));
```
### `pub fn take_profit(pct: f64) -> TakeProfit`
Create a take-profit condition.
#### Example
```ignore
use finance_query::backtesting::condition::*;
let exit = rsi(14).above(70.0).or(take_profit(0.15));
```
### `pub fn trailing_stop(trail_pct: f64) -> TrailingStop`
Create a trailing stop condition.
The trailing stop tracks the best price (highest for longs, lowest for shorts)
since position entry and triggers when price retraces by the specified percentage.
#### Example
```ignore
use finance_query::backtesting::condition::*;
// Exit if price drops 3% from the highest point since entry
let exit = trailing_stop(0.03);
```
### `pub fn trailing_take_profit(trail_pct: f64) -> TrailingTakeProfit`
Create a trailing take-profit condition.
This condition tracks the peak profit since entry and triggers when
profit drops by the specified percentage from that peak. It only triggers
after the position has been in profit.
#### Example
```ignore
use finance_query::backtesting::condition::*;
// Exit if profit drops 2% from peak profit
let exit = trailing_take_profit(0.02);
```
### `pub fn trailing_stop(trail_pct: f64) -> TrailingStop`
**Measured:** 596815 instructions/iter, 52696ns median, 92 allocs/iter
### `pub fn trailing_take_profit(trail_pct: f64) -> TrailingTakeProfit`
**Measured:** 605815 instructions/iter, 56025ns median, 72 allocs/iter
### `pub struct BacktestConfig`
Configuration for backtest execution.
Use `BacktestConfig::builder()` to construct with the builder pattern.
#### Example
```
use finance_query::backtesting::BacktestConfig;
let config = BacktestConfig::builder()
.initial_capital(50_000.0)
.commission_pct(0.001)
.slippage_pct(0.0005)
.allow_short(true)
.stop_loss_pct(0.05)
.take_profit_pct(0.10)
.build()
.unwrap();
```
### `pub fn calculate_position_size(&self, available_capital: f64, price: f64) -> f64`
Calculate position size based on available capital.
`price` **must** be the fully-adjusted entry price (after slippage and
spread) so that subsequent fill guards (`entry_value + costs > cash`)
do not over-allocate capital.
When [`commission_fn`](Self::commission_fn) is set the commission component cannot be
analytically solved for, so only spread and transaction-tax fractions
are deducted from the denominator; the fill-rejection guard catches any
remaining over-allocation.
### `pub struct BacktestConfigBuilder`
Builder for BacktestConfig
### `pub fn margin_interest_rate(mut self, rate: f64) -> Self`
Set the annual interest rate charged on a debit cash balance.
### `pub struct CommissionFn(Arc<dyn Fn(f64, f64) -> f64 + Send + Sync>)`
A custom commission function: `f(size, price) -> commission_amount`.
When set on [`BacktestConfig`] via [`BacktestConfigBuilder::commission_fn`],
it **replaces** the flat `commission` + percentage `commission_pct` fields.
Use it to model broker-specific fee schedules such as per-share fees with
a minimum, tiered rates, or Robinhood-style zero-commission structures.
#### Example
```
use finance_query::backtesting::BacktestConfig;
// IB-style: $0.005 per share, minimum $1.00 per order
let config = BacktestConfig::builder()
.commission_fn(|size, price| (size * 0.005_f64).max(1.00))
.build()
.unwrap();
```
### `pub enum PositionSizing`
How an entry's size is derived from available equity.
Every scheme targets a fraction of equity clamped to the risk budget
([`BacktestConfig::position_size_pct`], raised by
[`BacktestConfig::max_leverage`] when levered), and falls back to that budget
when its inputs are unavailable.
Scale-in signals carry an explicit fraction of their own and are not sized
by the active scheme.
### `pub struct SizingContext`
Market and trade-history inputs a [`PositionSizing`] scheme reads at entry.
A `None` field means the engine had no value to supply, and the scheme falls
back to [`BacktestConfig::position_size_pct`].
### `pub struct BacktestEngine`
Backtest execution engine.
Handles indicator pre-computation, position management, and trade execution.
### `pub fn run_with_dividends<S: Strategy>( &self, symbol: &str, candles: &[Candle], strategy: S, dividends: &[Dividend], ) -> Result<BacktestResult>`
Run a backtest and credit dividend income for any dividends paid while a
position is open.
`dividends` should be sorted by timestamp (ascending). The engine credits
each dividend whose ex-date falls on or before the current candle bar.
When [`BacktestConfig::reinvest_dividends`] is `true`, the income is also
used to notionally purchase additional shares at the ex-date close price.
### `pub enum BacktestError`
Backtest-specific errors
### `pub type Result<T> = std::result::Result<T, BacktestError>`
Result type for backtest operations
### `pub struct MonteCarloConfig`
Configuration for Monte Carlo simulation.
### `pub enum MonteCarloMethod`
Resampling method used for Monte Carlo simulation.
Each method makes different assumptions about trade return structure.
Choose based on your strategy's autocorrelation characteristics.
### `pub struct MonteCarloResult`
Results of the Monte Carlo simulation.
Each field gives the distribution of that metric across all simulations.
### `pub struct PercentileStats`
Percentile summary over the Monte Carlo simulations for a single metric.
### `pub struct BayesianSearch`
### `pub struct GridSearch`
### `pub struct OptimizationReport`
Optimisation report returned by both [`GridSearch`] and [`BayesianSearch`].
#### Overfitting Warning
All metrics are **in-sample** — the same candle data used to optimise the
parameters is used to score them. In-sample results almost always overstate
real-world performance.
**Always validate best parameters on unseen data** — use [`WalkForwardConfig`](super::walk_forward::WalkForwardConfig)
for an unbiased out-of-sample estimate, or reserve a held-out test period.
### `pub struct OptimizationResult`
Result of a single parameter set evaluation.
### `pub enum OptimizeMetric`
Which performance metric to optimise for.
All metrics are maximised internally; [`MinDrawdown`](OptimizeMetric::MinDrawdown) is negated so that
a smaller drawdown produces a higher score.
### `pub enum ParamRange`
Defines the search space for a single strategy parameter.
| Constructor | Compatible with | Typical use |
|-------------|-----------------|-------------|
| [`int_range(start, end, step)`](ParamRange::int_range) | GridSearch + BayesianSearch | Integer period with explicit grid step |
| [`float_range(start, end, step)`](ParamRange::float_range) | GridSearch + BayesianSearch | Float multiplier with explicit grid step |
| [`int_bounds(start, end)`](ParamRange::int_bounds) | GridSearch (step=1) + BayesianSearch | Integer period, let Bayesian sample freely |
| [`float_bounds(start, end)`](ParamRange::float_bounds) | **BayesianSearch only** | Continuous float range |
| [`Values(vec)`](ParamRange::Values) | GridSearch + BayesianSearch | Explicit list of values |
### `pub fn float_bounds(start: f64, end: f64) -> Self`
Continuous float bounds — **[`BayesianSearch`] only**.
A step of `0.0` intentionally makes [`GridSearch`] return an error, giving
a clear signal when the wrong optimiser is used with this range type.
### `pub fn float_range(start: f64, end: f64, step: f64) -> Self`
Stepped float range — compatible with both [`GridSearch`] and [`BayesianSearch`].
### `pub fn int_bounds(start: i64, end: i64) -> Self`
Continuous integer bounds for [`BayesianSearch`].
Equivalent to `int_range(start, end, 1)`. Also usable with [`GridSearch`]
(enumerates every integer in `[start, end]`), but prefer `int_range` with a
wider step when the grid would be very large.
### `pub fn int_range(start: i64, end: i64, step: i64) -> Self`
Stepped integer range — compatible with both [`GridSearch`] and [`BayesianSearch`].
### `pub enum ParamValue`
A single parameter value — either an integer period or a float multiplier.
### `pub struct ParetoPoint`
### `pub struct ParetoReport`
### `pub struct BayesianSearch`
Sequential model-based (Bayesian) parameter optimiser.
Finds near-optimal strategy parameters in a fraction of the evaluations
required by exhaustive [`GridSearch`](super::grid::GridSearch), making it practical for
high-dimensional spaces or continuous float ranges.
Returns the same [`OptimizationReport`] as [`GridSearch`](super::grid::GridSearch), so the two are
drop-in interchangeable and both work with [`WalkForwardConfig`](super::super::walk_forward::WalkForwardConfig).
#### Overfitting Warning
Results are **in-sample only**. Follow up with [`WalkForwardConfig`](super::super::walk_forward::WalkForwardConfig) or a
held-out test window to obtain an unbiased out-of-sample estimate.
### `pub struct GridSearch`
Exhaustive grid-search optimiser for backtesting strategy parameters.
Evaluates every combination of the supplied parameter ranges in parallel.
Use [`BayesianSearch`](super::BayesianSearch) instead when the cartesian product would exceed
a few thousand combinations or when float ranges without a step are needed.
#### Overfitting Warning
Results are **in-sample only**. Follow up with [`WalkForwardConfig`](super::super::walk_forward::WalkForwardConfig) or a
held-out test window to obtain an unbiased out-of-sample estimate.
### `pub fn run<S, F>( &self, symbol: &str, candles: &[Candle], config: &BacktestConfig, factory: F, ) -> Result<OptimizationReport> where S: Strategy + Send, F: Fn(&HashMap<String, ParamValue>) -> S + Send + Sync,`
Run the grid search.
`symbol` is used only for labelling in the returned results.
`factory` receives the current parameter map and returns a strategy
instance. Combinations that exceed the strategy's warmup period are
silently skipped.
Returns an error when the grid is empty or all combinations were skipped.
### `pub struct ParetoPoint`
One non-dominated parameter set and its score on each objective.
### `pub struct ParetoReport`
The Pareto front of a multi-objective search.
`total_evaluated == front.len() + dominated_count + non_finite_count`.
### `pub struct AllocationSnapshot`
### `pub struct PortfolioConfig`
### `pub struct PortfolioEngine`
### `pub struct PortfolioResult`
### `pub enum RebalanceMode`
### `pub struct SymbolData`
### `pub struct PortfolioConfig`
Configuration for multi-symbol portfolio backtesting.
### `pub enum RebalanceMode`
Controls how capital is divided among symbols when opening new positions.
### `pub struct PortfolioEngine`
Multi-symbol portfolio backtesting engine.
Runs all symbols on a shared capital pool, applying the configured
allocation strategy and position constraints simultaneously.
### `pub struct SymbolData`
Input data for a single symbol in the portfolio backtest.
### `pub struct AllocationSnapshot`
Snapshot of capital allocation at a single point in time.
### `pub struct PortfolioResult`
Results of a multi-symbol portfolio backtest.
### `pub struct Position`
An open position
### `pub fn close( self, exit_timestamp: i64, exit_price: f64, exit_commission: f64, exit_signal: Signal, ) -> Trade`
Close this position and create a Trade.
`dividend_income` accumulated during the hold is added to P&L and
preserved on the returned `Trade` for reporting purposes.
### `pub fn partial_close( &mut self, fraction: f64, exit_ts: i64, exit_price: f64, commission: f64, exit_tax: f64, signal: Signal, ) -> Trade`
Partially close this position and return a completed [`Trade`].
Closes `fraction` of the current position quantity, allocating a
proportional share of accumulated entry costs and dividend income to the
trade P&L. The remaining position stays open with reduced quantity,
dividend balances, and entry cost bases.
[`Trade::is_partial`] is `true` for all trades returned by this method.
For a full close prefer [`Position::close`](crate::backtesting::Position::close)
(or the crate-internal `close_with_tax` for tax-aware exits), which sets
`is_partial = false`. The engine's `scale_out_position` delegates
`fraction >= 1.0` to `close_position` for exactly this reason.
The caller is responsible for updating cash from the returned trade's
exit proceeds.
#### Arguments
* `fraction` – Portion of current quantity to close (`0.0..=1.0`).
* `exit_ts` – Timestamp of the fill.
* `exit_price` – Adjusted exit price (after slippage/spread).
* `commission` – Exit-side commission for this close.
* `exit_tax` – Exit-side transaction tax for this close.
* `signal` – Signal that triggered the partial exit.
### `pub fn scale_in( &mut self, fill_price: f64, additional_qty: f64, commission: f64, entry_tax: f64, )`
Add shares to this position (pyramid / scale-in).
Updates the weighted-average `entry_price` and `entry_quantity` to reflect
the blended cost basis and increments `scale_in_count`. The caller is
responsible for debiting the entry cost from available cash and for applying
slippage/spread to `fill_price` before calling this method.
#### Arguments
* `fill_price` – Adjusted entry price for the new shares.
* `additional_qty` – Number of shares to add. No-op if `<= 0.0`.
* `commission` – Commission paid for this add (already applied to cash).
* `entry_tax` – Transaction tax for this add (already applied to cash).
### `pub enum PositionSide`
Position direction
### `pub struct Trade`
A completed trade (closed position)
### `pub struct AccumulationDistributionRef`
### `pub struct AdxRef`
### `pub struct AlmaConfig`
### `pub struct AlmaRef`
### `pub struct AroonConfig`
### `pub struct AroonDownRef`
### `pub struct AroonUpRef`
### `pub struct AtrRef`
### `pub struct AwesomeOscillatorRef`
### `pub struct BalanceOfPowerRef`
### `pub struct BearPowerRef`
### `pub struct BollingerConfig`
### `pub struct BollingerLowerRef`
### `pub struct BollingerMiddleRef`
### `pub struct BollingerUpperRef`
### `pub struct BullPowerRef`
### `pub struct CandleBody`
### `pub struct CandleRange`
### `pub struct CciRef`
### `pub struct ChaikinOscillatorRef`
### `pub struct ChoppinessIndexRef`
### `pub struct ClosePrice`
### `pub struct CmfRef`
### `pub struct CmoRef`
### `pub struct CoppockCurveRef`
### `pub struct DemaRef`
### `pub struct DonchianConfig`
### `pub struct DonchianLowerRef`
### `pub struct DonchianMiddleRef`
### `pub struct DonchianUpperRef`
### `pub struct ElderBearPowerRef`
### `pub struct ElderBullPowerRef`
### `pub struct EmaRef`
### `pub struct GapPct`
### `pub struct HighPrice`
### `pub struct HmaRef`
### `pub struct HtfCondition<C: Condition>`
### `pub struct IchimokuBaseRef`
### `pub struct IchimokuConfig`
### `pub struct IchimokuConversionRef`
### `pub struct IchimokuLaggingRef`
### `pub struct IchimokuLeadingARef`
### `pub struct IchimokuLeadingBRef`
### `pub trait IndicatorRef: Clone + Send + Sync + 'static`
A reference to a value that can be compared in conditions.
This is the building block for creating conditions. Each indicator
reference knows:
- Its unique key for storing computed values
- What indicators it requires
- How to retrieve its value from the strategy context
#### Implementing Custom References
```ignore
use finance_query::backtesting::refs::IndicatorRef;
#[derive(Clone)]
struct MyCustomRef {
period: usize,
}
impl IndicatorRef for MyCustomRef {
fn key(&self) -> &str {
"my_custom_14" // pre-computed at construction time
}
fn required_indicators(&self) -> Vec<(String, Indicator)> {
vec![(self.key().to_string(), Indicator::Sma(self.period))]
}
fn value(&self, ctx: &StrategyContext) -> Option<f64> {
ctx.indicator(self.key())
}
fn prev_value(&self, ctx: &StrategyContext) -> Option<f64> {
ctx.indicator_prev(self.key())
}
}
```
### `pub trait IndicatorRefExt: IndicatorRef + Sized`
Extension trait that adds condition-building methods to all indicator references.
This trait provides a fluent API for building conditions from indicator values.
It is automatically implemented for all types that implement `IndicatorRef`.
#### Example
```ignore
use finance_query::backtesting::refs::*;
// All these methods are available on any IndicatorRef
let cond1 = rsi(14).above(70.0);
let cond2 = rsi(14).below(30.0);
let cond3 = rsi(14).crosses_above(30.0);
let cond4 = rsi(14).crosses_below(70.0);
let cond5 = rsi(14).between(30.0, 70.0);
let cond6 = sma(10).above_ref(sma(20));
let cond7 = sma(10).crosses_above_ref(sma(20));
```
### `pub struct IsBearish`
### `pub struct IsBullish`
### `pub struct KeltnerConfig`
### `pub struct KeltnerLowerRef`
### `pub struct KeltnerMiddleRef`
### `pub struct KeltnerUpperRef`
### `pub struct LowPrice`
### `pub struct MacdConfig`
### `pub struct MacdHistogramRef`
### `pub struct MacdLineRef`
### `pub struct MacdSignalRef`
### `pub struct McginleyDynamicRef`
### `pub struct MedianPrice`
### `pub struct MfiRef`
### `pub struct MomentumRef`
### `pub struct ObvRef`
### `pub struct OpenPrice`
### `pub struct ParabolicSarConfig`
### `pub struct ParabolicSarRef`
### `pub struct PriceChangePct`
### `pub struct RelativeVolume`
### `pub struct RocRef`
### `pub struct RsiRef`
### `pub struct SmaRef`
### `pub struct StochasticConfig`
### `pub struct StochasticDRef`
### `pub struct StochasticKRef`
### `pub struct StochasticRsiConfig`
### `pub struct StochasticRsiDRef`
### `pub struct StochasticRsiRef`
### `pub struct SupertrendConfig`
### `pub struct SupertrendUptrendRef`
### `pub struct SupertrendValueRef`
### `pub struct TemaRef`
### `pub struct TrueRangeRef`
### `pub struct TypicalPrice`
### `pub struct VolumeRef`
### `pub struct VwapRef`
### `pub struct VwmaRef`
### `pub struct WilliamsRRef`
### `pub struct WmaRef`
### `pub fn accumulation_distribution() -> AccumulationDistributionRef`
**Measured:** 575870 instructions/iter, 51773ns median, 23 allocs/iter
### `pub fn adx(period: usize) -> AdxRef`
**Measured:** 5311493 instructions/iter, 534007ns median, 4930 allocs/iter
### `pub fn alma(period: usize, offset: f64, sigma: f64) -> AlmaRef`
**Measured:** 5899258 instructions/iter, 590482ns median, 5019 allocs/iter
### `pub fn aroon(period: usize) -> AroonConfig`
**Measured:** 5642513 instructions/iter, 543952ns median, 4950 allocs/iter
### `pub fn atr(period: usize) -> AtrRef`
**Measured:** 5548473 instructions/iter, 536231ns median, 4996 allocs/iter
### `pub fn awesome_oscillator(fast: usize, slow: usize) -> AwesomeOscillatorRef`
**Measured:** 3090695 instructions/iter, 331324ns median, 2636 allocs/iter
### `pub fn balance_of_power(period: Option<usize>) -> BalanceOfPowerRef`
**Measured:** 574481 instructions/iter, 51851ns median, 25 allocs/iter
### `pub fn bear_power(period: usize) -> BearPowerRef`
**Measured:** 1545235 instructions/iter, 146196ns median, 806 allocs/iter
### `pub fn bollinger(period: usize, std_dev: f64) -> BollingerConfig`
**Measured:** 6100697 instructions/iter, 583512ns median, 4968 allocs/iter
### `pub fn bull_power(period: usize) -> BullPowerRef`
**Measured:** 5302885 instructions/iter, 518251ns median, 4238 allocs/iter
### `pub fn candle_body() -> CandleBody`
**Measured:** 254396 instructions/iter, 19861ns median, 6 allocs/iter
### `pub fn candle_range() -> CandleRange`
**Measured:** 5165267 instructions/iter, 506215ns median, 5043 allocs/iter
### `pub fn cci(period: usize) -> CciRef`
**Measured:** 3255676 instructions/iter, 319100ns median, 2605 allocs/iter
### `pub fn chaikin_oscillator() -> ChaikinOscillatorRef`
**Measured:** 646841 instructions/iter, 68931ns median, 26 allocs/iter
### `pub fn choppiness_index(period: usize) -> ChoppinessIndexRef`
**Measured:** 5819352 instructions/iter, 551600ns median, 5002 allocs/iter
### `pub fn close() -> ClosePrice`
**Measured:** 5190103 instructions/iter, 495912ns median, 5043 allocs/iter
### `pub fn cmf(period: usize) -> CmfRef`
**Measured:** 589599 instructions/iter, 51748ns median, 25 allocs/iter
### `pub fn cmo(period: usize) -> CmoRef`
**Measured:** 3082622 instructions/iter, 305691ns median, 2598 allocs/iter
### `pub fn coppock_curve(wma_period: usize, long_roc: usize, short_roc: usize) -> CoppockCurveRef`
**Measured:** 3343041 instructions/iter, 330451ns median, 2559 allocs/iter
### `pub fn dema(period: usize) -> DemaRef`
**Measured:** 5497724 instructions/iter, 531228ns median, 4875 allocs/iter
### `pub fn donchian(period: usize) -> DonchianConfig`
**Measured:** 5998093 instructions/iter, 583579ns median, 4976 allocs/iter
### `pub fn elder_bear_power(period: usize) -> ElderBearPowerRef`
**Measured:** 1538366 instructions/iter, 145101ns median, 806 allocs/iter
### `pub fn elder_bull_power(period: usize) -> ElderBullPowerRef`
**Measured:** 5215201 instructions/iter, 513829ns median, 4238 allocs/iter
### `pub fn ema(period: usize) -> EmaRef`
**Measured:** 5398604 instructions/iter, 532718ns median, 4963 allocs/iter
### `pub fn gap_pct() -> GapPct`
**Measured:** 2496160 instructions/iter, 263865ns median, 2489 allocs/iter
### `pub fn high() -> HighPrice`
**Measured:** 5191091 instructions/iter, 496377ns median, 5043 allocs/iter
### `pub fn hma(period: usize) -> HmaRef`
**Measured:** 5408149 instructions/iter, 539286ns median, 4957 allocs/iter
### `pub fn htf<C: Condition>(interval: Interval, cond: C) -> HtfCondition<C>`
**Measured:** 6531233 instructions/iter, 636240ns median, 7039 allocs/iter
### `pub struct HtfCondition<C: Condition>`
A condition that evaluates its inner condition on a resampled HTF candle series.
Created by [`htf()`] (UTC-aligned) or [`htf_region()`] (exchange-local calendar).
### `pub fn htf<C: Condition>(interval: Interval, cond: C) -> HtfCondition<C>`
Wrap a condition to be evaluated on a higher-timeframe candle series.
Bucket boundaries are UTC-aligned (offset = 0). For non-UTC exchanges use
[`htf_region()`] instead.
#### Arguments
* `interval` – Target higher timeframe (e.g. `Interval::OneWeek`)
* `cond` – Any condition to evaluate on the HTF candles
#### Example
```ignore
use finance_query::backtesting::refs::*;
use finance_query::Interval;
// Entry only when weekly price is above its 20-bar SMA
let weekly_uptrend = htf(Interval::OneWeek, price().above_ref(sma(20)));
let entry = ema(10).crosses_above_ref(ema(30)).and(weekly_uptrend);
```
### `pub fn htf_region<C: Condition>(interval: Interval, region: Region, cond: C) -> HtfCondition<C>`
Wrap a condition to be evaluated on a higher-timeframe candle series,
with bucket boundaries aligned to the exchange's local calendar.
Weekly and monthly boundaries are shifted by `region.utc_offset_secs()` so
that, for example, a Tokyo-listed stock's "Monday" starts at the correct
local midnight rather than UTC midnight.
#### Arguments
* `interval` – Target higher timeframe (e.g. `Interval::OneWeek`)
* `region` – Exchange region used to derive the UTC offset
* `cond` – Any condition to evaluate on the HTF candles
#### Example
```ignore
use finance_query::backtesting::refs::*;
use finance_query::{Interval, Region};
let weekly_trend = htf_region(Interval::OneWeek, Region::Japan, price().above_ref(sma(20)));
```
### `pub fn htf_region<C: Condition>(interval: Interval, region: Region, cond: C) -> HtfCondition<C>`
**Measured:** 6423194 instructions/iter, 638307ns median, 7039 allocs/iter
### `pub fn ichimoku() -> IchimokuConfig`
**Measured:** 6358216 instructions/iter, 618721ns median, 4836 allocs/iter
### `pub struct IchimokuBaseRef`
Ichimoku Base Line (Kijun-sen) reference.
### `pub struct IchimokuConfig`
Ichimoku Cloud configuration.
### `pub struct IchimokuConversionRef`
Ichimoku Conversion Line (Tenkan-sen) reference.
### `pub struct IchimokuLaggingRef`
Chikou Span reference: the close from `lagging` bars ago.
This is the price level the chikou span is compared against at decision
time, not the plot-aligned span itself — that array is stored shifted
forward for charting (slot `j` holds `close[j + lagging]`) and would leak
future closes if read directly at the current bar.
Reads base-timeframe candles directly, so inside an `htf()` wrapper it
still lags by base bars, not HTF bars.
### `pub struct IchimokuLeadingARef`
Ichimoku Leading Span A (Senkou Span A) reference.
### `pub struct IchimokuLeadingBRef`
Ichimoku Leading Span B (Senkou Span B) reference.
### `pub fn ichimoku() -> IchimokuConfig`
Create an Ichimoku Cloud configuration with default periods (9, 26, 26, 26).
Senkou Span B is not independently configurable here; it is always `2 * base`.
### `pub fn ichimoku_custom( conversion: usize, base: usize, lagging: usize, displacement: usize, ) -> IchimokuConfig`
Create an Ichimoku Cloud configuration with custom periods.
`lagging` is the Chikou Span back-displacement, not a Senkou Span B
period — Senkou Span B is always `2 * base` and is not independently
configurable here.
### `pub fn ichimoku_custom( conversion: usize, base: usize, lagging: usize, displacement: usize, ) -> IchimokuConfig`
**Measured:** 6314305 instructions/iter, 620909ns median, 4836 allocs/iter
### `pub fn is_bearish() -> IsBearish`
**Measured:** 255395 instructions/iter, 19785ns median, 6 allocs/iter
### `pub fn is_bullish() -> IsBullish`
**Measured:** 255395 instructions/iter, 19771ns median, 6 allocs/iter
### `pub fn keltner(period: usize, multiplier: f64, atr_period: usize) -> KeltnerConfig`
**Measured:** 5838019 instructions/iter, 605096ns median, 4972 allocs/iter
### `pub fn low() -> LowPrice`
**Measured:** 5194085 instructions/iter, 491171ns median, 5043 allocs/iter
### `pub fn macd(fast: usize, slow: usize, signal: usize) -> MacdConfig`
**Measured:** 3330642 instructions/iter, 341668ns median, 2541 allocs/iter
### `pub fn mcginley(period: usize) -> McginleyDynamicRef`
**Measured:** 5513907 instructions/iter, 533402ns median, 4963 allocs/iter
### `pub fn median_price() -> MedianPrice`
**Measured:** 5166265 instructions/iter, 495478ns median, 5043 allocs/iter
### `pub fn mfi(period: usize) -> MfiRef`
**Measured:** 5599564 instructions/iter, 537320ns median, 4998 allocs/iter
### `pub fn momentum(period: usize) -> MomentumRef`
**Measured:** 3106469 instructions/iter, 299791ns median, 2552 allocs/iter
### `pub struct AlmaConfig`
ALMA (Arnaud Legoux Moving Average) configuration.
### `pub struct AlmaRef`
ALMA reference.
### `pub struct DemaRef`
Double Exponential Moving Average reference.
### `pub struct EmaRef`
Exponential Moving Average reference.
### `pub struct HmaRef`
Hull Moving Average reference.
### `pub struct McginleyDynamicRef`
McGinley Dynamic indicator reference.
### `pub struct SmaRef`
Simple Moving Average reference.
### `pub struct TemaRef`
Triple Exponential Moving Average reference.
### `pub struct VwmaRef`
Volume Weighted Moving Average reference.
### `pub struct WmaRef`
Weighted Moving Average reference.
### `pub fn alma(period: usize, offset: f64, sigma: f64) -> AlmaRef`
Create an ALMA configuration.
### `pub fn dema(period: usize) -> DemaRef`
Create a Double Exponential Moving Average reference.
### `pub fn ema(period: usize) -> EmaRef`
Create an Exponential Moving Average reference.
### `pub fn hma(period: usize) -> HmaRef`
Create a Hull Moving Average reference.
### `pub fn mcginley(period: usize) -> McginleyDynamicRef`
Create a McGinley Dynamic indicator reference.
### `pub fn sma(period: usize) -> SmaRef`
Create a Simple Moving Average reference.
#### Example
```ignore
use finance_query::backtesting::refs::*;
let sma_20 = sma(20);
let golden_cross = sma(50).crosses_above_ref(sma(200));
```
### `pub fn tema(period: usize) -> TemaRef`
Create a Triple Exponential Moving Average reference.
### `pub fn vwma(period: usize) -> VwmaRef`
Create a Volume Weighted Moving Average reference.
### `pub fn wma(period: usize) -> WmaRef`
Create a Weighted Moving Average reference.
### `pub fn obv() -> ObvRef`
**Measured:** 633638 instructions/iter, 60214ns median, 30 allocs/iter
### `pub fn open() -> OpenPrice`
**Measured:** 5191091 instructions/iter, 496323ns median, 5043 allocs/iter
### `pub struct AwesomeOscillatorRef`
Awesome Oscillator reference (uses default 5/34 periods).
### `pub struct BalanceOfPowerRef`
Balance of Power reference.
### `pub struct CciRef`
Commodity Channel Index reference.
### `pub struct ChaikinOscillatorRef`
Chaikin Oscillator reference.
### `pub struct CmoRef`
Chande Momentum Oscillator reference.
### `pub struct CoppockCurveRef`
Coppock Curve reference.
### `pub struct MfiRef`
Money Flow Index reference.
### `pub struct MomentumRef`
Momentum indicator reference.
### `pub struct RocRef`
Rate of Change reference.
### `pub struct RsiRef`
Relative Strength Index reference.
### `pub struct StochasticConfig`
Stochastic Oscillator configuration.
### `pub struct StochasticDRef`
Stochastic %D line reference.
### `pub struct StochasticKRef`
Stochastic %K line reference.
### `pub struct StochasticRsiConfig`
Stochastic RSI configuration — entry point for building K or D line refs.
Use [`.k()`](StochasticRsiConfig::k) to reference the smoothed %K line and
[`.d()`](StochasticRsiConfig::d) for the %D signal line. Both resolve
against the same underlying `StochasticRsi` indicator computation, so only
one indicator fetch is registered regardless of which lines you use.
#### Example
```ignore
let srsi = stochastic_rsi(14, 14, 3, 3);
// K crosses above D — a common bullish signal
StrategyBuilder::new("StochRSI K/D Cross")
.entry(srsi.k().crosses_above_ref(srsi.d()))
.exit(srsi.k().crosses_below_ref(srsi.d()))
.build()
```
### `pub fn d(&self) -> StochasticRsiDRef`
Reference to the %D signal line (SMA of %K).
### `pub fn k(&self) -> StochasticRsiRef`
Reference to the smoothed %K line.
### `pub struct StochasticRsiDRef`
Stochastic RSI %D line reference (SMA of %K).
### `pub struct StochasticRsiRef`
Stochastic RSI %K line reference.
### `pub struct WilliamsRRef`
Williams %R reference.
### `pub fn awesome_oscillator(fast: usize, slow: usize) -> AwesomeOscillatorRef`
Create an Awesome Oscillator reference.
### `pub fn balance_of_power(period: Option<usize>) -> BalanceOfPowerRef`
Create a Balance of Power reference.
### `pub fn cci(period: usize) -> CciRef`
Create a Commodity Channel Index reference.
### `pub fn chaikin_oscillator() -> ChaikinOscillatorRef`
Create a Chaikin Oscillator reference.
### `pub fn cmo(period: usize) -> CmoRef`
Create a Chande Momentum Oscillator reference.
### `pub fn coppock_curve(wma_period: usize, long_roc: usize, short_roc: usize) -> CoppockCurveRef`
Create a Coppock Curve reference (uses default 10/14/11 periods).
### `pub fn mfi(period: usize) -> MfiRef`
Create a Money Flow Index reference.
### `pub fn momentum(period: usize) -> MomentumRef`
Create a Momentum indicator reference.
### `pub fn roc(period: usize) -> RocRef`
Create a Rate of Change reference.
### `pub fn rsi(period: usize) -> RsiRef`
Create a Relative Strength Index reference.
#### Example
```ignore
use finance_query::backtesting::refs::*;
let oversold = rsi(14).below(30.0);
let overbought = rsi(14).above(70.0);
let exit_oversold = rsi(14).crosses_above(30.0);
```
### `pub fn stochastic(k_period: usize, k_slow: usize, d_period: usize) -> StochasticConfig`
Create a Stochastic Oscillator configuration.
### `pub fn stochastic_rsi( rsi_period: usize, stoch_period: usize, k_period: usize, d_period: usize, ) -> StochasticRsiConfig`
Create a Stochastic RSI configuration.
Returns a [`StochasticRsiConfig`] from which you can obtain
[`StochasticRsiConfig::k()`] or [`StochasticRsiConfig::d()`] refs.
Calling `stochastic_rsi(...).k()` is equivalent to the previous API that
returned `StochasticRsiRef` directly.
### `pub fn williams_r(period: usize) -> WilliamsRRef`
Create a Williams %R reference.
### `pub fn parabolic_sar(step: f64, max: f64) -> ParabolicSarRef`
**Measured:** 5848186 instructions/iter, 589133ns median, 5056 allocs/iter
### `pub struct BearPowerRef`
Bear Power reference.
### `pub struct BullPowerRef`
Bull Power reference.
### `pub struct ElderBearPowerRef`
Elder Ray Bear Power reference.
### `pub struct ElderBullPowerRef`
Elder Ray Bull Power reference.
### `pub fn bear_power(period: usize) -> BearPowerRef`
Create a Bear Power reference.
### `pub fn bull_power(period: usize) -> BullPowerRef`
Create a Bull Power reference.
### `pub fn elder_bear_power(period: usize) -> ElderBearPowerRef`
Create an Elder Ray Bear Power reference.
### `pub fn elder_bull_power(period: usize) -> ElderBullPowerRef`
Create an Elder Ray Bull Power reference.
### `pub fn price() -> ClosePrice`
**Measured:** 5190103 instructions/iter, 496341ns median, 5043 allocs/iter
### `pub struct CandleBody`
Reference to the candle body size (absolute difference between open and close).
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Strong candle filter
let strong_body = candle_body().above(2.0);
```
### `pub struct CandleRange`
Reference to the candle range (high - low).
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Filter for high volatility candles
let wide_range = candle_range().above(5.0);
```
### `pub struct ClosePrice`
Reference to the close price.
#### Example
```ignore
use finance_query::backtesting::refs::*;
let close_above_sma = close().above_ref(sma(200));
```
### `pub struct GapPct`
Reference to the gap percentage (open vs previous close).
Returns: ((current_open - prev_close) / prev_close) * 100
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Gap up strategy
let gap_up = gap_pct().above(1.0);
// Gap down reversal
let gap_down = gap_pct().below(-2.0);
```
### `pub struct HighPrice`
Reference to the high price.
### `pub struct IsBearish`
Reference to whether the current candle is bearish (close < open).
Returns 1.0 if bearish, 0.0 if bullish or doji.
### `pub struct IsBullish`
Reference to whether the current candle is bullish (close > open).
Returns 1.0 if bullish, 0.0 if bearish or doji.
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Only enter on bullish candles
let bullish = is_bullish().above(0.5);
```
### `pub struct LowPrice`
Reference to the low price.
### `pub struct MedianPrice`
Reference to the median price: (high + low) / 2
### `pub struct OpenPrice`
Reference to the open price.
### `pub struct PriceChangePct`
Reference to the price change percentage from previous close.
Returns the percentage change: ((current_close - prev_close) / prev_close) * 100
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Enter on big moves (>2% change)
let big_move = price_change_pct().above(2.0);
// Exit on reversal
let reversal = price_change_pct().below(-1.5);
```
### `pub struct RelativeVolume`
Reference to relative volume (current volume / average volume over N periods).
Returns ratio: 1.0 = average, 2.0 = double average, etc.
#### Example
```ignore
use finance_query::backtesting::refs::*;
// High volume breakout (volume > 1.5x average)
let high_volume = relative_volume(20).above(1.5);
```
### `pub struct TypicalPrice`
Reference to the typical price: (high + low + close) / 3
### `pub struct VolumeRef`
Reference to the volume.
### `pub fn candle_body() -> CandleBody`
Get a reference to the candle body size.
### `pub fn candle_range() -> CandleRange`
Get a reference to the candle range (high - low).
### `pub fn close() -> ClosePrice`
Get a reference to the close price.
Alias for [`price()`].
### `pub fn gap_pct() -> GapPct`
Get a reference to the gap percentage (open vs previous close).
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Gap up entry
let gap_up = gap_pct().above(1.0);
```
### `pub fn high() -> HighPrice`
Get a reference to the high price.
### `pub fn is_bearish() -> IsBearish`
Returns 1.0 if the candle is bearish (close < open), 0.0 otherwise.
Use with `.above(0.5)` to check for bearish candle.
### `pub fn is_bullish() -> IsBullish`
Returns 1.0 if the candle is bullish (close > open), 0.0 otherwise.
Use with `.above(0.5)` to check for bullish candle.
### `pub fn low() -> LowPrice`
Get a reference to the low price.
### `pub fn median_price() -> MedianPrice`
Get a reference to the median price: (high + low) / 2.
### `pub fn open() -> OpenPrice`
Get a reference to the open price.
### `pub fn price() -> ClosePrice`
Get a reference to the close price.
#### Example
```ignore
use finance_query::backtesting::refs::*;
let above_sma = price().above_ref(sma(200));
let crosses_ema = close().crosses_above_ref(ema(50));
```
### `pub fn price_change_pct() -> PriceChangePct`
Get a reference to the price change percentage from previous close.
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Big move filter (>2% change)
let big_move = price_change_pct().above(2.0);
```
### `pub fn relative_volume(period: usize) -> RelativeVolume`
Get a reference to relative volume (current volume / N-period average volume).
#### Arguments
* `period` - Number of periods for the volume average
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Volume spike filter
let volume_spike = relative_volume(20).above(2.0);
```
### `pub fn typical_price() -> TypicalPrice`
Get a reference to the typical price: (high + low + close) / 3.
### `pub fn volume() -> VolumeRef`
Get a reference to the volume.
### `pub fn price_change_pct() -> PriceChangePct`
**Measured:** 2916804 instructions/iter, 293870ns median, 2489 allocs/iter
### `pub fn relative_volume(period: usize) -> RelativeVolume`
**Measured:** 5672919 instructions/iter, 542256ns median, 4949 allocs/iter
### `pub fn roc(period: usize) -> RocRef`
**Measured:** 2913687 instructions/iter, 299222ns median, 2587 allocs/iter
### `pub fn rsi(period: usize) -> RsiRef`
**Measured:** 5544087 instructions/iter, 532909ns median, 4994 allocs/iter
### `pub fn sma(period: usize) -> SmaRef`
**Measured:** 5402520 instructions/iter, 528137ns median, 4963 allocs/iter
### `pub fn stochastic(k_period: usize, k_slow: usize, d_period: usize) -> StochasticConfig`
**Measured:** 6136027 instructions/iter, 599872ns median, 4987 allocs/iter
### `pub fn stochastic_rsi( rsi_period: usize, stoch_period: usize, k_period: usize, d_period: usize, ) -> StochasticRsiConfig`
**Measured:** 6004542 instructions/iter, 595718ns median, 4831 allocs/iter
### `pub fn supertrend(period: usize, multiplier: f64) -> SupertrendConfig`
**Measured:** 6024926 instructions/iter, 605776ns median, 5021 allocs/iter
### `pub fn tema(period: usize) -> TemaRef`
**Measured:** 5404246 instructions/iter, 530425ns median, 4781 allocs/iter
### `pub struct AdxRef`
Average Directional Index reference.
### `pub struct AroonConfig`
Aroon indicator configuration.
### `pub struct AroonDownRef`
Aroon Down reference.
### `pub struct AroonUpRef`
Aroon Up reference.
### `pub struct ChoppinessIndexRef`
Choppiness Index reference.
### `pub struct MacdConfig`
MACD configuration for building MACD-related references.
### `pub struct MacdHistogramRef`
MACD Histogram reference.
### `pub struct MacdLineRef`
MACD Line reference.
### `pub struct MacdSignalRef`
MACD Signal Line reference.
### `pub struct ParabolicSarConfig`
Parabolic SAR configuration.
### `pub struct ParabolicSarRef`
Parabolic SAR reference.
### `pub struct SupertrendConfig`
SuperTrend configuration.
### `pub struct SupertrendUptrendRef`
SuperTrend uptrend indicator reference.
Returns 1.0 for uptrend, 0.0 for downtrend.
### `pub struct SupertrendValueRef`
SuperTrend value reference.
### `pub fn adx(period: usize) -> AdxRef`
Create an Average Directional Index reference.
#### Example
```ignore
use finance_query::backtesting::refs::*;
// Strong trend filter
let strong_trend = adx(14).above(25.0);
```
### `pub fn aroon(period: usize) -> AroonConfig`
Create an Aroon indicator configuration.
### `pub fn choppiness_index(period: usize) -> ChoppinessIndexRef`
Create a Choppiness Index reference.
### `pub fn macd(fast: usize, slow: usize, signal: usize) -> MacdConfig`
Create a MACD configuration.
#### Example
```ignore
use finance_query::backtesting::refs::*;
let m = macd(12, 26, 9);
let bullish = m.line().crosses_above_ref(m.signal_line());
let histogram_positive = m.histogram().above(0.0);
```
### `pub fn parabolic_sar(step: f64, max: f64) -> ParabolicSarRef`
Create a Parabolic SAR configuration.
### `pub fn supertrend(period: usize, multiplier: f64) -> SupertrendConfig`
Create a SuperTrend configuration.
### `pub fn true_range() -> TrueRangeRef`
**Measured:** 5341937 instructions/iter, 534192ns median, 5059 allocs/iter
### `pub fn typical_price() -> TypicalPrice`
**Measured:** 5607532 instructions/iter, 545255ns median, 5043 allocs/iter
### `pub struct AtrRef`
Average True Range reference.
### `pub struct BollingerConfig`
Bollinger Bands configuration.
### `pub struct BollingerLowerRef`
Bollinger lower band reference.
### `pub struct BollingerMiddleRef`
Bollinger middle band reference.
### `pub struct BollingerUpperRef`
Bollinger upper band reference.
### `pub struct DonchianConfig`
Donchian Channels configuration.
### `pub struct DonchianLowerRef`
Donchian lower channel reference.
### `pub struct DonchianMiddleRef`
Donchian middle channel reference.
### `pub struct DonchianUpperRef`
Donchian upper channel reference.
### `pub struct KeltnerConfig`
Keltner Channels configuration.
### `pub struct KeltnerLowerRef`
Keltner lower channel reference.
### `pub struct KeltnerMiddleRef`
Keltner middle channel reference.
### `pub struct KeltnerUpperRef`
Keltner upper channel reference.
### `pub struct TrueRangeRef`
True Range reference.
### `pub fn atr(period: usize) -> AtrRef`
Create an Average True Range reference.
### `pub fn bollinger(period: usize, std_dev: f64) -> BollingerConfig`
Create a Bollinger Bands configuration.
#### Example
```ignore
use finance_query::backtesting::refs::*;
let bb = bollinger(20, 2.0);
let at_lower_band = price().below_ref(bb.lower());
let at_upper_band = price().above_ref(bb.upper());
```
### `pub fn donchian(period: usize) -> DonchianConfig`
Create a Donchian Channels configuration.
### `pub fn keltner(period: usize, multiplier: f64, atr_period: usize) -> KeltnerConfig`
Create a Keltner Channels configuration.
### `pub fn true_range() -> TrueRangeRef`
Create a True Range reference.
### `pub fn volume() -> VolumeRef`
**Measured:** 5191091 instructions/iter, 495282ns median, 5043 allocs/iter
### `pub struct AccumulationDistributionRef`
Accumulation/Distribution reference.
### `pub struct CmfRef`
Chaikin Money Flow reference.
### `pub struct ObvRef`
On-Balance Volume reference.
### `pub struct VwapRef`
Volume Weighted Average Price reference.
### `pub fn accumulation_distribution() -> AccumulationDistributionRef`
Create an Accumulation/Distribution reference.
### `pub fn cmf(period: usize) -> CmfRef`
Create a Chaikin Money Flow reference.
### `pub fn obv() -> ObvRef`
Create an On-Balance Volume reference.
### `pub fn vwap() -> VwapRef`
Create a Volume Weighted Average Price reference.
### `pub fn vwap() -> VwapRef`
**Measured:** 5632130 instructions/iter, 535083ns median, 5060 allocs/iter
### `pub fn vwma(period: usize) -> VwmaRef`
**Measured:** 5367654 instructions/iter, 535564ns median, 4964 allocs/iter
### `pub fn williams_r(period: usize) -> WilliamsRRef`
**Measured:** 748884 instructions/iter, 60754ns median, 29 allocs/iter
### `pub fn wma(period: usize) -> WmaRef`
**Measured:** 5488244 instructions/iter, 522174ns median, 4969 allocs/iter
### `pub fn base_to_htf_index(base_candles: &[Candle], htf_candles: &[Candle]) -> Vec<Option<usize>>`
Map each base-timeframe index to the most recently *completed* HTF bar index.
A "completed" HTF bar is one whose timestamp (the last constituent bar's
timestamp) is less than or equal to the current base bar's timestamp.
Using `<=` rather than `<` ensures that on the final bar of an HTF period
(e.g. a Friday close for a weekly bar), the engine can immediately see the
now-finalized HTF candle. Using `<` would introduce an artificial one-bar
delay: on Friday, `htf.timestamp == base.timestamp`, so `<` fails and the
engine falls back to the prior week's data even though the weekly bar is
already complete.
`htf_candles` must have been produced by [`resample`] with the same
`utc_offset_secs` used for the base series so that bucket boundaries are
consistent.
Returns `None` for bars where no HTF bar has completed yet (e.g. during
the first HTF period).
**Measured:** 321100 instructions/iter, 22860ns median, 1 allocs/iter
### `pub fn resample(candles: &[Candle], interval: Interval, utc_offset_secs: i64) -> Vec<Candle>`
Resample `candles` from their base timeframe to `interval`.
`utc_offset_secs` shifts each candle's timestamp into the exchange's local
time before computing calendar bucket boundaries (weekly Monday start,
month boundary, etc.). Pass `0` for UTC-aligned bucketing (default for US
markets). Use [`Region::utc_offset_secs`](crate::constants::Region::utc_offset_secs) to obtain the correct value for
non-US exchanges.
#### Notes
- Calendar-aligned intervals (`OneWeek`, `OneMonth`, `ThreeMonths`) respect
`utc_offset_secs`. Weekly bars start on the local Monday.
- Sub-daily intervals use fixed-second buckets relative to local midnight.
**Measured:** 1451621 instructions/iter, 104332ns median, 11 allocs/iter
### `pub struct BacktestResult`
Complete backtest result
### `pub fn by_day_of_week(&self) -> HashMap<Weekday, PerformanceMetrics>`
Performance metrics broken down by day of week.
Each trade is attributed to the weekday on which it **closed**
(`exit_timestamp`). Only weekdays present in the trade log appear in
the result. Trades and equity-curve points with timestamps that cannot
be converted to a valid date are silently skipped.
#### Sharpe / Sortino annualisation
The equity curve is filtered to bars that fall on each specific
weekday, so consecutive equity points in each slice are roughly one
*week* apart (for a daily-bar backtest). `bars_per_year` is inferred
from the calendar span of each slice so that annualisation matches the
actual sampling frequency — **you do not need to adjust the config**.
The inferred value is approximately `52` for daily bars, `12` for
weekly bars, and so on.
#### Other caveats
The same open-position and signal-count caveats from
[`by_year`](Self::by_year) apply here.
### `pub fn by_month(&self) -> HashMap<(i32, u32), PerformanceMetrics>`
Performance metrics broken down by calendar month.
Each trade is attributed to the `(year, month)` in which it **closed**.
Uses the same equity-slicing approach as [`by_year`](Self::by_year);
the same caveats about open positions, partial periods, and signal
counts apply here as well.
### `pub fn by_year(&self) -> HashMap<i32, PerformanceMetrics>`
Performance metrics broken down by calendar year.
Each trade is attributed to the year in which it **closed**
(`exit_timestamp`). The equity curve is sliced to the bars that fall
within that calendar year, and the equity at the first bar of the year
serves as `initial_capital` for the period metrics.
Years with no closed trades are omitted from the result.
#### Caveats
- **Open positions**: a position that is open throughout the year
contributes to the equity-curve drawdown and Sharpe of that year but
does **not** appear in `total_trades` or `win_rate`, because those
are derived from closed trades only. Strategies with long holding
periods will show systematically low trade counts per year.
- **Partial years**: the first and last year of a backtest typically
cover fewer than 12 months. `annualized_return_pct`, `calmar_ratio`,
and `serenity_ratio` are set to `0.0` for slices shorter than half a
year (`< bars_per_year / 2` bars) to prevent geometric-compounding
distortion.
- **`total_signals` / `executed_signals`**: these fields are `0` in
period breakdowns because signal records are not partitioned per
period. Use [`BacktestResult::signals`] directly if needed.
### `pub struct EquityPoint`
Point on the equity curve
### `pub struct SignalRecord`
Record of a generated signal (for analysis)
### `pub struct BenchmarkMetrics`
Comparison of strategy performance against a benchmark.
Populated when a benchmark symbol is supplied to `backtest_with_benchmark`.
### `pub struct PerformanceMetrics`
Performance metrics summary
### `pub fn max_drawdown_percentage(&self) -> f64`
Maximum drawdown as a conventional percentage (0–100).
Equivalent to `self.max_drawdown_pct * 100.0`. Provided because
`max_drawdown_pct` is stored as a fraction (0.0–1.0) while most other
return fields use true percentages.
### `pub enum OrderType`
Order type controlling how a signal's entry is executed.
[`OrderType::Market`] (the default) preserves the existing behaviour:
fill at the next bar's open. The limit and stop variants queue the order
as a [`PendingOrder`] and fill when the bar's high/low reaches the
specified price level.
This enum is `#[non_exhaustive]` so that adding new order types (e.g.
`MarketOnClose`, `TrailingStopLimit`) in a future release is not a
breaking change for library consumers that match on it exhaustively.
### `pub struct PendingOrder`
A queued limit or stop entry order awaiting price-level execution.
Created by the engine when a strategy returns a [`Signal`] whose
[`Signal::order_type`] is not [`OrderType::Market`]. The engine checks
the order each subsequent bar until it fills or expires.
### `pub struct Signal`
A trading signal generated by a strategy
### `pub fn exit(timestamp: i64, price: f64) -> Self`
Create an exit signal
### `pub fn scale_in(fraction: f64, timestamp: i64, price: f64) -> Self`
Create a scale-in signal — add to an existing position.
`fraction` is the portion of current portfolio **equity** to allocate to
the additional shares. Must be in `0.0..=1.0`; values outside this range
are clamped by the engine. Has no effect if no position is currently open.
#### Example
```rust,no_run
use finance_query::backtesting::Signal;
// In a custom Strategy::on_candle implementation:
# let (ctx_timestamp, ctx_price) = (0i64, 0.0f64);
// Add 10% of current equity to the existing long position.
let signal = Signal::scale_in(0.10, ctx_timestamp, ctx_price);
```
### `pub fn scale_out(fraction: f64, timestamp: i64, price: f64) -> Self`
Create a scale-out signal — partially exit an existing position.
`fraction` is the portion of the current position **quantity** to close.
Must be in `0.0..=1.0`; values outside this range are clamped. A fraction
of `1.0` closes the entire position (equivalent to [`Signal::exit`]). Has
no effect if no position is currently open.
#### Example
```rust,no_run
use finance_query::backtesting::Signal;
// In a custom Strategy::on_candle implementation:
# let (ctx_timestamp, ctx_price) = (0i64, 0.0f64);
// Close half the current position to lock in partial profits.
let signal = Signal::scale_out(0.50, ctx_timestamp, ctx_price);
```
### `pub enum SignalDirection`
Trading signal direction
### `pub struct SignalMetadata`
Metadata attached to signals for analysis
### `pub struct SignalStrength(f64)`
Signal strength/confidence (0.0 to 1.0)
### `pub struct BollingerMeanReversion`
### `pub struct CustomStrategy<E: Condition, X: Condition>`
### `pub struct DonchianBreakout`
### `pub enum EnsembleMode`
### `pub struct EnsembleStrategy`
### `pub struct MacdSignal`
### `pub struct PositionExtremes`
Price extremes reached since the open position was entered.
The peak since entry belongs to the position, not to any one condition, so
the engine tracks it once per bar and every trailing condition reads the same
value instead of each keeping its own running scan.
### `pub struct RsiReversal`
### `pub struct SmaCrossover`
### `pub trait Strategy: Send + Sync`
Core strategy trait - implement this for custom strategies.
#### Example
```ignore
use finance_query::backtesting::{Strategy, StrategyContext, Signal};
use finance_query::indicators::Indicator;
struct MyStrategy {
sma_period: usize,
}
impl Strategy for MyStrategy {
fn name(&self) -> &str {
"My Custom Strategy"
}
fn required_indicators(&self) -> Vec<(String, Indicator)> {
vec![
(format!("sma_{}", self.sma_period), Indicator::Sma(self.sma_period)),
]
}
fn on_candle(&self, ctx: &StrategyContext) -> Signal {
let sma = ctx.indicator(&format!("sma_{}", self.sma_period));
let close = ctx.close();
match sma {
Some(sma_val) if close > sma_val && !ctx.has_position() => {
Signal::long(ctx.timestamp(), close)
}
Some(sma_val) if close < sma_val && ctx.is_long() => {
Signal::exit(ctx.timestamp(), close)
}
_ => Signal::hold(),
}
}
}
```
### `pub struct StrategyBuilder<E = (), X = ()>`
### `pub struct StrategyContext<'a>`
Context passed to strategy on each candle.
Provides access to historical data, current position, and pre-computed indicators.
### `pub fn crossed_above(&self, fast_name: &str, slow_name: &str) -> bool`
Check if crossover occurred (fast crosses above slow)
### `pub fn indicator(&self, name: &str) -> Option<f64>`
Get indicator value at current index
### `pub fn indicator_crossed_above(&self, name: &str, threshold: f64) -> bool`
Check if indicator crossed above a threshold.
Returns `true` when `prev <= threshold` **and** `current > threshold`.
The inclusive lower bound (`<=`) means a signal fires even when the
previous bar sat exactly on the threshold, the same inclusive-previous
convention [`crossed_above`](Self::crossed_above) uses for
indicator-vs-indicator crossings.
### `pub fn indicator_prev(&self, name: &str) -> Option<f64>`
Get indicator value at previous index
### `pub struct SuperTrendFollow`
### `pub struct CustomStrategy<E: Condition, X: Condition>`
A custom strategy built from conditions.
This strategy evaluates entry and exit conditions on each candle
and generates appropriate signals.
### `pub struct StrategyBuilder<E = (), X = ()>`
Builder for creating custom strategies with entry/exit conditions.
The builder enforces that both entry and exit conditions are provided
before a strategy can be built.
An optional regime filter can be set at any point in the chain via
[`.regime_filter()`](StrategyBuilder::regime_filter). When set, the filter
is evaluated on every bar; if it returns `false`, all entry signals are
suppressed. Exit signals are **never** blocked by the regime filter.
### `pub fn regime_filter<C: Condition>(mut self, condition: C) -> Self`
Set a market regime filter.
When set, entry signals (long and short) are suppressed on any bar
where the filter evaluates to `false`. Exit signals are **never**
blocked by the regime filter, ensuring open positions can always be
closed regardless of market conditions.
The regime filter's indicators are included in `required_indicators()`
and therefore pre-computed by the engine like any other indicator.
#### Example
```rust,no_run
use finance_query::backtesting::strategy::StrategyBuilder;
use finance_query::backtesting::refs::*;
// Only trade when price is above the 200-period SMA
let strategy = StrategyBuilder::new("Trend Following")
.regime_filter(sma(200).above_ref(sma(400)))
.entry(ema(10).crosses_above_ref(ema(30)))
.exit(ema(10).crosses_below_ref(ema(30)))
.build();
```
### `pub enum EnsembleMode`
Voting mode that determines how sub-strategy signals are combined.
### `pub struct EnsembleStrategy`
A strategy that aggregates signals from multiple sub-strategies.
Build with the fluent builder methods [`add`](Self::add), [`mode`](Self::mode),
then finalise with [`build`](Self::build).
All six [`SignalDirection`](crate::backtesting::SignalDirection) variants are
fully supported. In [`EnsembleMode::WeightedMajority`], `ScaleIn` and `ScaleOut`
participate in the vote with the same position guard as `Exit` — they are only
tallied when a position is open. In `Unanimous`, `AnySignal`, and
`StrongestSignal` modes they are treated like any other non-Hold direction.
### `pub fn add<S: Strategy + 'static>(mut self, strategy: S, weight: f64) -> Self`
Add a sub-strategy with the given weight.
Weight is only meaningful for [`EnsembleMode::WeightedMajority`]; other
modes ignore it. Negative weights are treated as zero.
### `pub fn build(self) -> Self`
Finalise the ensemble. Returns `self` (all configuration happens in the
builder methods).
### `pub fn mode(mut self, mode: EnsembleMode) -> Self`
Set the voting mode.
### `pub struct BollingerMeanReversion`
Bollinger Bands Mean Reversion Strategy
Goes long when price touches lower band (oversold).
Exits when price reaches middle or upper band.
Emits short signals when price touches upper band (execution gated by
[`BacktestConfig::allow_short`](crate::backtesting::BacktestConfig)).
#### Signal Strength
All entry signals emit at default strength (`1.0`). Strength is **not** scaled
by how far price has penetrated through the band. This differs from
[`RsiReversal`], which grades strength by RSI extremity. If you are relying
on [`BacktestConfig::min_signal_strength`](crate::backtesting::BacktestConfig::min_signal_strength) to filter signals in a portfolio
context, all Bollinger entries will pass the threshold equally.
### `pub struct DonchianBreakout`
Donchian Channel Breakout Strategy
Goes long when price breaks above upper channel (new high).
Exits when price breaks below lower channel (new low).
Emits short signals on downward breakouts (execution gated by
[`BacktestConfig::allow_short`](crate::backtesting::BacktestConfig)).
### `pub struct MacdSignal`
MACD Signal Strategy
Goes long when MACD line crosses above signal line.
Exits when MACD line crosses below signal line.
Emits short signals on bearish crossovers (execution gated by
[`BacktestConfig::allow_short`](crate::backtesting::BacktestConfig)).
### `pub struct RsiReversal`
RSI Reversal Strategy
Goes long when RSI crosses above oversold level.
Exits the long when RSI crosses back below the overbought level.
Emits short signals when RSI crosses below overbought (execution gated by
[`BacktestConfig::allow_short`](crate::backtesting::BacktestConfig)).
### `pub struct SmaCrossover`
SMA Crossover Strategy
Goes long when fast SMA crosses above slow SMA.
Exits when fast SMA crosses below slow SMA.
Emits short signals on bearish crossovers (execution gated by
[`BacktestConfig::allow_short`](crate::backtesting::BacktestConfig)).
### `pub struct SuperTrendFollow`
SuperTrend Following Strategy
Goes long when SuperTrend turns bullish (uptrend).
Emits short signals when SuperTrend turns bearish (execution gated by
[`BacktestConfig::allow_short`](crate::backtesting::BacktestConfig)).
### `pub struct WalkForwardConfig`
Configuration for a walk-forward parameter optimisation test.
Build with [`WalkForwardConfig::new`], configure window sizes with the
builder methods, then call [`WalkForwardConfig::run`].
### `pub fn new(grid: GridSearch, config: BacktestConfig) -> Self`
Create a new walk-forward config.
Defaults: `in_sample_bars = 252`, `out_of_sample_bars = 63`, `step_bars = None`.
### `pub fn run<S, F>( &self, symbol: &str, candles: &[Candle], factory: F, ) -> Result<WalkForwardReport> where S: Strategy + Clone + Send, F: Fn(&HashMap<String, ParamValue>) -> S, F: Send + Sync,`
Run the walk-forward test.
`symbol` is used only for labelling. `factory` receives the parameter
map selected by each in-sample optimisation and must return a fresh
strategy instance.
Returns an error if there is not enough data for at least one complete
window pair, or if the grid search or the out-of-sample simulation
fails on any window (fail-fast — a partial result is never returned).
### `pub struct WalkForwardReport`
Aggregate walk-forward report across all windows.
### `pub struct WindowResult`
Backtest results for a single walk-forward window pair.
### `pub struct CommitmentsOfTraders`
### `pub struct CotObservation`
### `pub async fn fetch_commitments_of_traders_response(symbol: &str) -> Result<CommitmentsOfTraders>`
### `pub enum Frequency`
Frequency for financial data (annual or quarterly)
The `alias`es mirror the shorthands [`FromStr`](std::str::FromStr) accepts, so
deserializing (axum query extraction, JSON) takes the same spellings parsing does.
### `pub enum Interval`
Chart intervals
The `alias`es mirror the spellings [`FromStr`](std::str::FromStr) accepts, so
deserializing (axum query extraction, JSON) takes the same spellings parsing does.
### `pub fn as_str(&self) -> &'static str`
Convert interval to Yahoo Finance API format
### `pub enum Region`
Supported regions for Yahoo Finance regional APIs
Each region has predefined language and region codes that work together.
Using the Region enum ensures correct lang/region pairing.
### `pub const fn utc_offset_secs(&self) -> i64`
UTC offset in seconds for the region's primary exchange.
Returns the standard-time (non-DST) UTC offset of each country's main
exchange. This is used by the backtesting engine to align higher-timeframe
resampling bucket boundaries to local calendar weeks and months, preventing
APAC and other non-UTC exchanges from having bars mis-bucketed into the
prior week due to UTC midnight falling inside their local trading day.
#### Note
DST transitions are not modelled. For exchanges in regions with DST
(e.g. NYSE, LSE) the boundary shift is at most ±1 hour and affects only
the transition candles. This is a deliberate simplification — exact DST
handling would require a timezone database dependency.
### `pub enum StatementType`
Statement types for financial data
The `alias`es mirror the spellings [`FromStr`](std::str::FromStr) accepts, so
deserializing (axum path/query extraction, JSON) takes the same spellings parsing does.
### `pub enum TimeRange`
Time ranges for chart data
The `alias`es mirror the spellings [`FromStr`](std::str::FromStr) accepts, so
deserializing (axum query extraction, JSON) takes the same spellings parsing does.
### `pub fn as_str(&self) -> &'static str`
Convert time range to Yahoo Finance API format
### `pub fn default_interval(&self) -> Interval`
A sensible default candle interval for this range, used by the
`history(range)` convenience on domain handles: finer granularity for
short ranges, coarser for long ones.
### `pub enum ValueFormat`
Value format for API responses
Controls how `FormattedValue<T>` fields are serialized in responses.
This allows API consumers to choose between raw numeric values,
human-readable formatted strings, or both.
The `alias`es mirror the shorthands [`FromStr`](std::str::FromStr) accepts, so
deserializing (axum query extraction, JSON) takes the same spellings parsing does.
### `pub enum ExchangeCode`
Typed exchange code for screener queries.
### `pub enum Region`
Region categories for world indices
The `alias`es mirror the shorthands [`FromStr`](std::str::FromStr) accepts, so
deserializing (axum query extraction, JSON) takes the same spellings parsing does.
### `pub enum Industry`
Typed industry identifier for the industry endpoint and custom screener queries.
See the module-level doc for usage.
### `pub fn as_slug(self) -> &'static str`
Returns the lowercase hyphenated slug used by `finance::industry()`.
#### Example
```
use finance_query::Industry;
assert_eq!(Industry::Semiconductors.as_slug(), "semiconductors");
assert_eq!(Industry::SoftwareApplication.as_slug(), "software-application");
```
### `pub enum Screener`
Predefined Yahoo Finance screener selector
Passed to `finance::screener()` or `client.get_screener()` to select one of the
15 built-in Yahoo Finance screeners (equity or fund).
The `alias`es mirror the shorthands [`FromStr`](std::str::FromStr) accepts, so
deserializing (axum path extraction, JSON) takes the same spellings parsing does.
### `pub enum Sector`
Market sector types available on Yahoo Finance
The `alias`es mirror the shorthands [`FromStr`](std::str::FromStr) accepts, so
deserializing (axum path extraction, JSON) takes the same spellings parsing does.
### `pub struct CoinQuote`
**Measured:** 352875 instructions/iter, 32746ns median, 205 allocs/iter
### `pub struct GlobalCryptoStats`
### `pub struct SymbolMatch`
### `pub struct TrendingCoin`
### `pub async fn coin(id: &str, vs_currency: &str) -> Result<CoinQuote>`
### `pub async fn coins(vs_currency: &str, count: usize) -> Result<Vec<CoinQuote>>`
### `pub async fn fetch_crypto_global_response() -> Result<crate::models::crypto::GlobalCryptoStats>`
### `pub async fn fetch_symbol_search_response(query: &str, limit: u32) -> Result<Vec<SymbolMatch>>`
### `pub async fn fetch_crypto_trending_response() -> Result<Vec<crate::models::crypto::TrendingCoin>>`
### `pub struct ChainAllocation`
### `pub struct ChainTvl`
### `pub struct ProtocolTvl`
### `pub struct StablecoinSupply`
### `pub struct TvlPoint`
### `pub async fn chains() -> Result<Vec<ChainTvl>>`
Fetch aggregate total value locked for every chain, largest first.
### `pub async fn stablecoins() -> Result<Vec<StablecoinSupply>>`
Fetch circulating supply for every tracked stablecoin, largest first.
Supplies are denominated in the coin's pegged asset — read `peg_type`
before summing across coins pegged to different currencies.
### `domain_handle!`
### `domain_handle!`
### `domain_handle!`
### `pub struct EconomicCatalog`
### `domain_handle!`
### `domain_handle!`
### `domain_handle!`
### `domain_handle!`
### `domain_handle!`
### `pub struct Market`
### `domain_handle!`
### `domain_handle!`
### `domain_handle!`
A commodity backed by configured data providers.
Created via [`Providers::commodity`](crate::Providers::commodity).
### `pub async fn quote(&self) -> Result<crate::models::commodities::CommodityQuote>`
Fetch the current quote for this commodity.
### `domain_handle!`
A cryptocurrency coin backed by configured data providers.
Created via [`Providers::crypto`](crate::Providers::crypto).
### `pub async fn quote(&self, vs_currency: &str) -> Result<crate::models::crypto::CryptoQuote>`
Fetch the current quote for this coin priced in `vs_currency` (e.g., `"usd"`).
### `pub async fn tvl(&self) -> Result<crate::models::crypto::defi::ProtocolTvl>`
Fetch total value locked for this handle read as a **DeFi protocol
slug** (e.g. `providers.crypto("aave")`).
Routed through `Capability::CRYPTO`; only DefiLlama serves it, so route
`CRYPTO` to include [`Provider::DefiLlama`](crate::Provider::DefiLlama).
The id is a protocol slug here, not a coin id — most DefiLlama slugs
happen to match their CoinGecko id, but not all do. The response is
cached on the handle, so a repeat call costs nothing.
### `pub async fn tvl_history(&self) -> Result<Vec<crate::models::crypto::defi::TvlPoint>>`
Fetch this protocol's full TVL history, oldest first.
Same routing and slug semantics as [`tvl`](Self::tvl).
### `domain_handle!`
Symbol discovery backed by configured data providers.
Unlike [`crate::finance::search`] — a Yahoo-only convenience shortcut —
this routes through [`Capability::DISCOVERY`], so it honours the provider
priority configured on [`Providers::builder`](crate::Providers::builder)
and falls back across providers.
Created via [`Providers::discovery`](crate::Providers::discovery).
### `pub async fn search(&self, query: &str, limit: u32) -> Result<Vec<SymbolMatch>>`
Search the configured providers' symbol universe.
Results are cached per `(query, limit)` pair.
### `pub struct EconomicCatalog`
The macro-economic series catalog: search and browse rather than fetch.
Routes through [`Capability::ECONOMIC`]. [`EconomicIndicator`] needs a
series id you already know; this handle is how you find one. FRED is
currently the only provider.
Created via [`Providers::economic_catalog`](crate::Providers::economic_catalog).
### `domain_handle!`
A macro-economic data series backed by configured data providers.
Created via [`Providers::economic`](crate::Providers::economic).
### `pub async fn series(&self) -> Result<crate::models::economic::EconomicSeries>`
Fetch the full data series for this economic indicator.
### `domain_handle!`
SEC filing data backed by configured data providers.
Created via [`Providers::filings`](crate::Providers::filings).
### `pub async fn get(&self) -> Result<crate::models::filings::ProviderFilings>`
Fetch SEC filings for this symbol.
### `pub async fn search_all( &self, query: &str, filters: crate::models::filings::FilingSearchFilters, ) -> Result<Vec<crate::models::filings::FilingSearchHit>>`
Full-text search across every filer via the FILINGS route (currently
EDGAR only). Not cached.
Searches filing *text*, so it answers "which filings mention this"
rather than "what has this company filed" — the query shape
[`get`](Self::get) cannot express.
### `domain_handle!`
A foreign-exchange currency pair backed by configured data providers.
Created via [`Providers::forex`](crate::Providers::forex).
### `pub async fn quote(&self) -> Result<crate::models::forex::ForexQuote>`
Fetch the current exchange rate for this currency pair.
### `domain_handle!`
A futures contract backed by configured data providers.
Created via [`Providers::futures`](crate::Providers::futures).
### `pub async fn commitments_of_traders( &self, ) -> Result<crate::models::futures::cot::CommitmentsOfTraders>`
Fetch weekly CFTC Commitments of Traders positioning for this futures
contract — long/short/spread broken down by trader category
(commercial hedgers, swap dealers, managed money, other reportables,
small traders).
Routed through `Capability::FUTURES`; only [`Provider::Cftc`](crate::Provider::Cftc)
serves it, so route `FUTURES` to include it. CFTC covers physical
commodities only (agriculture, energy, metals) via the disaggregated
futures-only report — the symbol is either a recognised Yahoo-style
continuous futures root (`"GC=F"`, `"CL=F"`, …) or a raw CFTC
`cftc_contract_market_code` passed straight through.
### `domain_handle!`
A stock market index backed by configured data providers.
Created via [`Providers::index`](crate::Providers::index).
### `pub async fn constituents(&self) -> Result<Vec<crate::models::indices::IndexConstituent>>`
Fetch the index's current constituents (major indices only). Not
cached — constituent lists change rarely but the call is uncommon.
### `pub struct Market`
Market-wide performance statistics backed by configured data providers.
Routes through [`crate::Capability::MARKET`]. Unlike [`crate::finance::sector`] and
[`crate::finance::market_summary`] — Yahoo-only convenience shortcuts — these
honour the configured provider priority.
Created via [`Providers::market`](crate::Providers::market).
### `pub async fn crypto_global(&self) -> Result<crate::models::crypto::GlobalCryptoStats>`
Fetch aggregate global cryptocurrency market statistics.
Routes through [`Capability::CRYPTO`](crate::providers::Capability::CRYPTO).
Currently CoinGecko only.
### `pub async fn crypto_trending(&self) -> Result<Vec<crate::models::crypto::TrendingCoin>>`
Fetch coins/nfts/categories trending in the last 24h.
Routes through [`Capability::CRYPTO`](crate::providers::Capability::CRYPTO).
Currently CoinGecko only.
### `pub async fn grouped_daily(&self, date: &str) -> Result<Vec<(String, Candle)>>`
Fetch grouped daily OHLCV bars for every stock ticker on `date`
(`YYYY-MM-DD`) in one call — "give me every ticker's OHLC for this
date" rather than one symbol at a time.
Routes through [`Capability::CHART`](crate::providers::Capability::CHART)
(the same capability backing per-symbol chart methods) rather than
`MARKET`, since it's OHLCV data rather than a performance statistic.
Currently Polygon only. Not cached — one date is one request either way.
### `domain_handle!`
Market-wide event calendars backed by configured data providers.
Routes through [`Capability::CALENDAR`]. Unlike
[`Ticker::calendar`](crate::Ticker::calendar), which builds a per-symbol
timeline, these span the whole market over a date range.
Created via [`Providers::calendar`](crate::Providers::calendar).
### `domain_handle!`
Snapshots for a watchlist spanning several asset classes, from one request.
Routes through [`Capability::QUOTE`]. Unlike
[`Tickers`](crate::Tickers) — which is equity-shaped and returns full quote
summaries — this takes provider-spelled symbols from any market (`"AAPL"`,
`"X:BTCUSD"`, `"I:SPX"`, `"C:EURUSD"`, `"O:NCLH221014C00005000"`) and
returns one flattened row each. Polygon is currently the only provider whose
snapshot endpoint spans markets.
Created via [`Providers::snapshot`](crate::Providers::snapshot).
### `pub async fn earnings_calendar() -> Result<Vec<EarningsCalendarEntry>>`
### `pub async fn company_facts(cik: u64) -> Result<CompanyFacts>`
### `pub async fn filing_index(accession_number: &str) -> Result<EdgarFilingIndex>`
### `pub fn init(email: impl Into<String>) -> Result<()>`
### `pub fn init_with_config( email: impl Into<String>, app_name: impl Into<String>, timeout: Duration, ) -> Result<()>`
### `pub async fn resolve_cik(symbol: &str) -> Result<u64>`
### `pub async fn search( query: &str, forms: Option<&[&str]>, start_date: Option<&str>, end_date: Option<&str>, from: Option<usize>, size: Option<usize>, ) -> Result<EdgarSearchResults>`
### `pub async fn submissions(cik: u64) -> Result<EdgarSubmissions>`
### `pub enum ErrorCategory`
Error category for logging and metrics
### `pub enum FinanceError`
Main error type for the library
### `pub type Result<T> = std::result::Result<T, FinanceError>`
Result type alias for library operations
### `pub struct FeedEntry`
A single entry from an RSS/Atom feed.
### `pub enum FeedSource`
A named or custom RSS/Atom feed source.
### `pub fn url(&self) -> String`
Return the URL for this feed source.
### `pub async fn fetch(source: FeedSource) -> Result<Vec<FeedEntry>>`
Fetch and parse a single feed source.
Returns an empty `Vec` (not an error) when the feed is reachable but empty.
### `pub async fn fetch_all(sources: impl IntoIterator<Item = FeedSource>) -> Result<Vec<FeedEntry>>`
Fetch multiple feed sources concurrently and merge the results.
Results are deduplicated by URL and sorted newest-first when dates are available.
Feeds that fail individually are skipped (not propagated as errors).
A single `reqwest::Client` is shared across all concurrent fetches within
this call, reusing connection pools and TLS state.
### `pub fn parse_bytes(bytes: &[u8], source_name: &str) -> Result<Vec<FeedEntry>>`
Parse already-fetched RSS/Atom bytes into entries, without a network round-trip.
Used internally by [`fetch`]/[`fetch_all`]; also useful for callers that
fetch feed bytes through their own HTTP client/cache/proxy, and for
offline parsing benchmarks/tests.
**Measured:** 64879 instructions/iter, 5685ns median, 48 allocs/iter
### `pub struct AnalystEstimate`
An analyst estimate entry (revenue, EBITDA, EPS forecasts).
### `pub struct AnalystRecommendation`
An analyst stock recommendation (buy/hold/sell counts).
### `pub struct EarningsCalendarEntry`
An upcoming earnings calendar entry.
### `pub struct InsiderTransaction`
An insider trading transaction record.
### `pub struct IpoCalendarEntry`
An upcoming IPO calendar entry.
### `pub struct LookupOptions`
### `pub enum LookupType`
### `pub enum Period`
Time period for analyst estimates.
### `pub struct SearchOptions`
### `pub async fn analyst_estimates(symbol: &str, period: Period) -> Result<Vec<AnalystEstimate>>`
Fetch analyst estimates for a symbol.
### `pub async fn analyst_recommendations(symbol: &str) -> Result<Vec<AnalystRecommendation>>`
Fetch analyst stock recommendations for a symbol.
### `pub async fn currencies() -> Result<Vec<crate::models::market::currencies::Currency>>`
Get list of available currencies
Returns currency information from Yahoo Finance.
#### Examples
```no_run
use finance_query::finance;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let currencies = finance::currencies().await?;
# Ok(())
# }
```
### `pub async fn custom_screener<F: crate::models::discovery::screeners::ScreenerField>( query: crate::models::discovery::screeners::ScreenerQuery<F>, ) -> Result<ScreenerResults>`
Execute a custom screener query
Allows flexible filtering of stocks/funds/ETFs based on various criteria.
Use [`EquityScreenerQuery`][crate::EquityScreenerQuery] for stock screeners
or [`FundScreenerQuery`][crate::FundScreenerQuery] for mutual fund screeners.
#### Arguments
* `query` - The custom screener query to execute
#### Examples
```no_run
use finance_query::{finance, EquityField, EquityScreenerQuery, ScreenerFieldExt};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Find US large-cap stocks with high volume
let query = EquityScreenerQuery::new()
.size(25)
.sort_by(EquityField::IntradayMarketCap, false)
.add_condition(EquityField::Region.eq_str("us"))
.add_condition(EquityField::AvgDailyVol3M.gt(200_000.0))
.add_condition(EquityField::IntradayMarketCap.gt(10_000_000_000.0));
let result = finance::custom_screener(query).await?;
println!("Found {} stocks", result.quotes.len());
# Ok(())
# }
```
### `pub async fn earnings_calendar() -> Result<Vec<EarningsCalendarEntry>>`
Fetch the upcoming earnings calendar (market-wide, not symbol-filtered).
### `pub async fn earnings_transcript( symbol: &str, quarter: Option<&str>, year: Option<i32>, ) -> Result<Transcript>`
Get earnings transcript for a symbol
Fetches the earnings call transcript, handling all the complexity internally:
1. Gets the company ID (quartrId) from the quote_type endpoint
2. Scrapes available earnings calls
3. Fetches the requested transcript
#### Arguments
* `symbol` - Stock symbol (e.g., "AAPL", "MSFT")
* `quarter` - Optional fiscal quarter (Q1, Q2, Q3, Q4). If None, gets latest.
* `year` - Optional fiscal year. If None, gets latest.
#### Examples
```no_run
use finance_query::finance;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Get the latest transcript
let latest = finance::earnings_transcript("AAPL", None, None).await?;
println!("Quarter: {} {}", latest.quarter(), latest.year());
// Get a specific quarter
let q4_2024 = finance::earnings_transcript("AAPL", Some("Q4"), Some(2024)).await?;
# Ok(())
# }
```
### `pub async fn earnings_transcripts( symbol: &str, limit: Option<usize>, ) -> Result<Vec<TranscriptWithMeta>>`
Get all earnings transcripts for a symbol
Fetches transcripts for all available earnings calls.
#### Arguments
* `symbol` - Stock symbol (e.g., "AAPL", "MSFT")
* `limit` - Optional maximum number of transcripts. If None, fetches all.
#### Examples
```no_run
use finance_query::finance;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Get all transcripts
let all = finance::earnings_transcripts("AAPL", None).await?;
// Get only the 5 most recent
let recent = finance::earnings_transcripts("AAPL", Some(5)).await?;
for t in &recent {
println!("{}: {} {}", t.title, t.transcript.quarter(), t.transcript.year());
}
# Ok(())
# }
```
### `pub async fn exchanges() -> Result<Vec<crate::models::market::exchanges::Exchange>>`
Get list of supported exchanges
Scrapes the Yahoo Finance help page for a list of supported exchanges
with their symbol suffixes and data delay information.
#### Examples
```no_run
use finance_query::finance;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let exchanges = finance::exchanges().await?;
for exchange in &exchanges {
println!("{} - {} ({})", exchange.country, exchange.market, exchange.suffix);
}
# Ok(())
# }
```
### `pub async fn fear_and_greed() -> Result<crate::models::sentiment::FearAndGreed>`
Fetch the current CNN Fear & Greed Index from Alternative.me.
Returns a 0–100 sentiment score and its classification. No API key required.
#### Examples
```no_run
use finance_query::finance;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let fg = finance::fear_and_greed().await?;
println!("Fear & Greed: {} ({})", fg.value, fg.classification.as_str());
# Ok(())
# }
```
### `pub async fn fear_and_greed_crypto( limit: u32, ) -> Result<Vec<crate::models::sentiment::FearAndGreed>>`
Fetch the crypto Fear & Greed Index from Alternative.me — current value
plus up to `limit - 1` historical readings (newest first).
Alternative.me's index specifically tracks crypto (Bitcoin) market
sentiment from volatility, momentum, social media, dominance, and
Google Trends signals. No API key required.
#### Arguments
* `limit` - Number of readings to return, newest first (`1` for just the
current value; e.g. `30` for the trailing month).
#### Examples
```no_run
use finance_query::finance;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let history = finance::fear_and_greed_crypto(7).await?;
let latest = &history[0];
println!("Crypto Fear & Greed: {} ({})", latest.value, latest.classification.as_str());
# Ok(())
# }
```
### `pub async fn hours(region: Option<Region>) -> Result<crate::models::market::hours::MarketHours>`
Get market hours/status
Returns the current status for various markets.
#### Arguments
* `region` - Optional region override. If None, uses default (US).
#### Examples
```no_run
use finance_query::{finance, Region};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Get US market hours (default)
let hours = finance::hours(None).await?;
// Get Japan market hours
let jp_hours = finance::hours(Some(Region::Japan)).await?;
# Ok(())
# }
```
### `pub async fn indices( region: Option<crate::constants::indices::Region>, ) -> Result<crate::tickers::BatchQuotesResponse>`
Get world market indices quotes
Returns quotes for major world indices, optionally filtered by region.
#### Arguments
* `region` - Optional region filter. If None, returns all world indices.
#### Examples
```no_run
use finance_query::{finance, IndicesRegion};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Get all world indices
let all = finance::indices(None).await?;
println!("Fetched {} indices", all.success_count());
// Get only Americas indices
let americas = finance::indices(Some(IndicesRegion::Americas)).await?;
# Ok(())
# }
```
### `pub async fn industry(industry_key: impl AsRef<str>) -> Result<IndustryData>`
Fetch detailed industry data from Yahoo Finance
Returns comprehensive industry information including overview, performance,
top companies, top performing companies, top growth companies, and research reports.
#### Arguments
* `industry_key` - The industry key/slug (e.g., "semiconductors", "software-infrastructure")
#### Examples
```no_run
use finance_query::finance;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let industry = finance::industry("semiconductors").await?;
println!("Industry: {} ({} companies)", industry.name,
industry.overview.as_ref().map(|o| o.companies_count.unwrap_or(0)).unwrap_or(0));
for company in industry.top_companies.iter().take(5) {
println!(" {} - {:?}", company.symbol, company.name);
}
# Ok(())
# }
```
### `pub async fn insider_trading(symbol: &str, limit: u32) -> Result<Vec<InsiderTransaction>>`
Fetch insider trading transactions for a symbol.
### `pub async fn ipo_calendar() -> Result<Vec<IpoCalendarEntry>>`
Fetch the upcoming IPO calendar (market-wide, not symbol-filtered).
### `pub async fn lookup( query: &str, options: &LookupOptions, ) -> Result<crate::models::discovery::lookup::LookupResults>`
Look up symbols by type (equity, ETF, mutual fund, index, future, currency, cryptocurrency)
Unlike search, lookup specializes in discovering tickers filtered by asset type.
Optionally fetches logo URLs via an additional API call.
#### Arguments
* `query` - Search term (company name, symbol, etc.)
* `options` - Lookup configuration options
#### Examples
```no_run
use finance_query::{finance, LookupOptions, LookupType, Region};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Simple lookup with defaults
let results = finance::lookup("Apple", &LookupOptions::default()).await?;
println!("Found {} results", results.result_count());
// Lookup equities with logos
let options = LookupOptions::new()
.lookup_type(LookupType::Equity)
.count(10)
.include_logo(true);
let results = finance::lookup("NVDA", &options).await?;
for quote in &results.quotes {
println!("{}: {:?}", quote.symbol, quote.logo_url);
}
# Ok(())
# }
```
### `pub async fn market_summary( region: Option<Region>, ) -> Result<Vec<crate::models::market::market_summary::MarketSummaryQuote>>`
Get market summary
Returns market summary with major indices, currencies, and commodities.
#### Arguments
* `region` - Optional region for localization. If None, uses default (US).
#### Examples
```no_run
use finance_query::{finance, Region};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Use default (US)
let summary = finance::market_summary(None).await?;
// Or specify a region
let summary = finance::market_summary(Some(Region::Canada)).await?;
# Ok(())
# }
```
### `pub async fn news() -> Result<Vec<crate::models::corporate::news::News>>`
Get general market news
#### Examples
```no_run
use finance_query::finance;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let news = finance::news().await?;
for article in news {
println!("{}: {}", article.source, article.title);
}
# Ok(())
# }
```
### `pub async fn screener(screener_type: Screener, count: u32) -> Result<ScreenerResults>`
Fetch data from a predefined Yahoo Finance screener
Returns stocks/funds matching the criteria of the specified screener type.
#### Arguments
* `screener_type` - The predefined screener to use
* `count` - Number of results to return (max 250)
#### Examples
```no_run
use finance_query::{finance, Screener};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Get top gainers
let gainers = finance::screener(Screener::DayGainers, 25).await?;
println!("Top gainers: {:#?}", gainers);
// Get most shorted stocks
let shorted = finance::screener(Screener::MostShortedStocks, 25).await?;
// Get growth technology stocks
let tech = finance::screener(Screener::GrowthTechnologyStocks, 25).await?;
# Ok(())
# }
```
### `pub async fn search(query: &str, options: &SearchOptions) -> Result<SearchResults>`
Search for stock symbols and companies
#### Arguments
* `query` - Search term (company name, symbol, etc.)
* `options` - Search configuration options
#### Examples
```no_run
use finance_query::{finance, SearchOptions, Region};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Simple search with defaults
let results = finance::search("Apple", &SearchOptions::default()).await?;
println!("Found {} results", results.result_count());
// Search with custom options
let options = SearchOptions::new()
.quotes_count(10)
.news_count(5)
.enable_research_reports(true)
.region(Region::Canada);
let results = finance::search("NVDA", &options).await?;
println!("Found {} quotes", results.quotes.len());
# Ok(())
# }
```
### `pub async fn sector(sector_type: Sector) -> Result<SectorData>`
Fetch detailed sector data from Yahoo Finance
Returns comprehensive sector information including overview, performance,
top companies, ETFs, mutual funds, industries, and research reports.
#### Arguments
* `sector_type` - The sector to fetch data for
#### Examples
```no_run
use finance_query::{finance, Sector};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let sector = finance::sector(Sector::Technology).await?;
println!("Sector: {} ({} companies)", sector.name,
sector.overview.as_ref().map(|o| o.companies_count.unwrap_or(0)).unwrap_or(0));
for company in sector.top_companies.iter().take(5) {
println!(" {} - {:?}", company.symbol, company.name);
}
# Ok(())
# }
```
### `pub async fn symbol_sentiment(symbol: &str) -> Result<crate::models::sentiment::SymbolSentiment>`
Fetch sentiment analysis for a symbol based on recent Polygon.io news.
### `pub async fn trending( region: Option<Region>, ) -> Result<Vec<crate::models::discovery::trending::TrendingQuote>>`
Get trending tickers for a region
Returns trending stocks for a specific region.
#### Arguments
* `region` - Optional region for localization. If None, uses default (US).
#### Examples
```no_run
use finance_query::{finance, Region};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Use default (US)
let trending = finance::trending(None).await?;
// Or specify a region
let trending = finance::trending(Some(Region::Canada)).await?;
# Ok(())
# }
```
### `pub fn init(api_key: impl Into<String>) -> Result<()>`
### `pub fn init_with_timeout(api_key: impl Into<String>, timeout: Duration) -> Result<()>`
### `pub struct Both`
### `pub struct Pretty`
### `pub struct Raw`
### `pub struct MacroObservation`
### `pub struct MacroSeries`
**Measured:** 1061290 instructions/iter, 107103ns median, 873 allocs/iter
### `pub struct ReleaseDate`
### `pub struct TreasuryYield`
**Measured:** 779612 instructions/iter, 73435ns median, 119 allocs/iter
### `pub fn init(api_key: impl Into<String>) -> Result<()>`
### `pub fn init_with_timeout(api_key: impl Into<String>, timeout: Duration) -> Result<()>`
### `pub async fn release_dates() -> Result<Vec<ReleaseDate>>`
### `pub async fn series(series_id: &str) -> Result<MacroSeries>`
### `pub async fn treasury_yields(year: u32) -> Result<Vec<TreasuryYield>>`
### `pub struct News`
### `pub async fn fetch_news_response(symbol: &str) -> Result<Vec<News>>`
### `pub struct AroonData`
### `pub struct AroonResult`
### `pub struct BollingerBands`
### `pub struct BollingerBandsData`
### `pub struct BullBearPowerData`
### `pub struct BullBearPowerResult`
### `pub enum CandlePattern`
### `pub struct DonchianChannelsData`
### `pub struct DonchianChannelsResult`
### `pub struct ElderRayData`
### `pub struct BullBearPowerResult`
### `pub struct FibonacciLevels`
### `pub struct IchimokuData`
### `pub struct IchimokuResult`
### `pub enum Indicator`
Enum representing all available technical indicators.
This enum is used with `Ticker::indicator()` to calculate specific indicators
over a given interval and time range.
### `pub fn warmup_bars(&self) -> usize`
Minimum number of data bars required before this indicator produces
meaningful output.
Used by the backtesting engine's `CustomStrategy` to automatically
compute the warmup period instead of parsing key-name suffixes.
#### Examples
```
use finance_query::indicators::Indicator;
assert_eq!(Indicator::Sma(20).warmup_bars(), 20);
assert_eq!(Indicator::Macd { fast: 12, slow: 26, signal: 9 }.warmup_bars(), 35);
assert_eq!(Indicator::Bollinger { period: 20, std_dev: 2.0 }.warmup_bars(), 20);
```
### `pub enum IndicatorError`
Error type for indicator calculations
### `pub enum IndicatorResult`
Result of an indicator calculation
Different indicators return different types of data:
- Simple indicators (SMA, EMA, RSI, ATR) return a time series of values
- Complex indicators (MACD, Bollinger Bands) return multiple series
### `pub enum Indicator`
### `pub struct IndicatorsSummary`
### `pub struct KeltnerChannelsData`
### `pub struct KeltnerChannelsResult`
### `pub struct MacdData`
### `pub struct MacdResult`
### `pub enum PatternSentiment`
### `pub struct PivotPoints`
### `pub type Result<T> = std::result::Result<T, IndicatorError>`
Result type for indicator calculations
### `pub struct StochasticData`
### `pub struct StochasticResult`
### `pub struct SuperTrendData`
### `pub struct SuperTrendResult`
### `pub struct ZigZagPoint`
### `pub fn accumulation_distribution( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], ) -> Result<Vec<Option<f64>>>`
**Measured:** 27672 instructions/iter, 3880ns median, 1 allocs/iter
### `pub fn accumulation_distribution( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], ) -> Result<Vec<Option<f64>>>`
Calculate Accumulation/Distribution (A/D).
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `volumes` - Volume data
#### Example
```
use finance_query::indicators::accumulation_distribution;
let highs = vec![10.0; 10];
let lows = vec![8.0; 10];
let closes = vec![9.0; 10];
let volumes = vec![100.0; 10];
let result = accumulation_distribution(&highs, &lows, &closes, &volumes).unwrap();
```
### `pub fn adx(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 1045401 instructions/iter, 101181ns median, 48 allocs/iter
### `pub fn adx(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Average Directional Index (ADX).
Measures trend strength (not direction).
Returns value between 0-100.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - Number of periods
#### Example
```
use finance_query::indicators::adx;
let highs = vec![10.0; 30];
let lows = vec![8.0; 30];
let closes = vec![9.0; 30];
let result = adx(&highs, &lows, &closes, 14).unwrap();
```
### `pub fn alma(data: &[f64], period: usize, offset: f64, sigma: f64) -> Result<Vec<Option<f64>>>`
**Measured:** 107851 instructions/iter, 6477ns median, 2 allocs/iter
### `pub fn alma(data: &[f64], period: usize, offset: f64, sigma: f64) -> Result<Vec<Option<f64>>>`
Calculate Arnaud Legoux Moving Average (ALMA).
Gaussian-weighted moving average with configurable offset and sigma.
Standard parameters: offset=0.85, sigma=6.0
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods
* `offset` - Offset parameter (0.0 to 1.0)
* `sigma` - Sigma parameter
#### Example
```
use finance_query::indicators::alma;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0];
let result = alma(&prices, 3, 0.85, 6.0).unwrap();
```
### `pub fn aroon(highs: &[f64], lows: &[f64], period: usize) -> Result<AroonResult>`
**Measured:** 194710 instructions/iter, 13813ns median, 9 allocs/iter
### `pub struct AroonResult`
Result of Aroon calculation
### `pub fn aroon(highs: &[f64], lows: &[f64], period: usize) -> Result<AroonResult>`
Calculate Aroon Indicator.
Aroon Up = ((period - periods since highest high) / period) * 100
Aroon Down = ((period - periods since lowest low) / period) * 100
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `period` - Number of periods
#### Example
```
use finance_query::indicators::aroon;
let highs = vec![10.0, 11.0, 12.0, 11.0, 10.0];
let lows = vec![8.0, 9.0, 10.0, 9.0, 8.0];
let result = aroon(&highs, &lows, 3).unwrap();
```
### `pub fn atr(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 57477 instructions/iter, 9726ns median, 2 allocs/iter
### `pub fn atr(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Average True Range (ATR).
ATR measures market volatility by calculating the average of true ranges over a period.
True range is the greatest of:
- Current high - Current low
- |Current high - Previous close|
- |Current low - Previous close|
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - Number of periods (typically 14)
#### Returns
Vector of ATR values. First `period` values will be None.
#### Example
```
use finance_query::indicators::atr;
let highs = vec![50.0, 51.0, 52.0, 51.5, 53.0, 54.0, 53.5, 55.0];
let lows = vec![48.0, 49.0, 50.0, 49.5, 51.0, 52.0, 51.5, 53.0];
let closes = vec![49.0, 50.5, 51.0, 50.0, 52.0, 53.0, 52.5, 54.0];
let result = atr(&highs, &lows, &closes, 3).unwrap();
assert_eq!(result.len(), 8);
assert!(result[2].is_some()); // ATR available after period
```
### `pub fn awesome_oscillator( highs: &[f64], lows: &[f64], fast: usize, slow: usize, ) -> Result<Vec<Option<f64>>>`
**Measured:** 52496 instructions/iter, 8433ns median, 4 allocs/iter
### `pub fn awesome_oscillator( highs: &[f64], lows: &[f64], fast: usize, slow: usize, ) -> Result<Vec<Option<f64>>>`
Calculate Awesome Oscillator (AO).
AO = SMA(median price, fast) - SMA(median price, slow)
Median price = (High + Low) / 2
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `fast` - Fast SMA period (default: 5)
* `slow` - Slow SMA period (default: 34)
#### Example
```
use finance_query::indicators::awesome_oscillator;
let highs = vec![10.0; 35];
let lows = vec![8.0; 35];
let result = awesome_oscillator(&highs, &lows, 5, 34).unwrap();
```
### `pub fn balance_of_power( opens: &[f64], highs: &[f64], lows: &[f64], closes: &[f64], period: Option<usize>, ) -> Result<Vec<Option<f64>>>`
**Measured:** 23362 instructions/iter, 1911ns median, 2 allocs/iter
### `pub fn balance_of_power( opens: &[f64], highs: &[f64], lows: &[f64], closes: &[f64], period: Option<usize>, ) -> Result<Vec<Option<f64>>>`
Calculate Balance of Power (BOP).
(Close - Open) / (High - Low)
#### Arguments
* `opens` - Open prices
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - Smoothing period (optional, default 14)
#### Example
```
use finance_query::indicators::balance_of_power;
let opens = vec![9.0; 10];
let highs = vec![10.0; 10];
let lows = vec![8.0; 10];
let closes = vec![9.5; 10];
let result = balance_of_power(&opens, &highs, &lows, &closes, Some(3)).unwrap();
```
### `pub struct BollingerBands`
Bollinger Bands result containing upper, middle, and lower bands.
### `pub fn bollinger_bands( data: &[f64], period: usize, std_dev_multiplier: f64, ) -> Result<BollingerBands>`
Calculate Bollinger Bands.
Bollinger Bands consist of a middle band (SMA) and upper/lower bands that are
standard deviations away from the middle band. They help identify volatility and
potential overbought/oversold conditions.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods for the SMA (typically 20)
* `std_dev_multiplier` - Number of standard deviations (typically 2.0)
#### Formula
- Middle Band = SMA(period)
- Upper Band = Middle Band + (std_dev_multiplier × standard deviation)
- Lower Band = Middle Band - (std_dev_multiplier × standard deviation)
#### Example
```
use finance_query::indicators::bollinger_bands;
let prices: Vec<f64> = (1..=30).map(|x| x as f64 + (x % 3) as f64).collect();
let result = bollinger_bands(&prices, 20, 2.0).unwrap();
assert_eq!(result.upper.len(), prices.len());
assert_eq!(result.middle.len(), prices.len());
assert_eq!(result.lower.len(), prices.len());
```
### `pub fn bollinger_bands( data: &[f64], period: usize, std_dev_multiplier: f64, ) -> Result<BollingerBands>`
**Measured:** 675327 instructions/iter, 68642ns median, 28 allocs/iter
### `pub fn bull_bear_power( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, ) -> Result<BullBearPowerResult>`
**Measured:** 29581 instructions/iter, 6941ns median, 3 allocs/iter
### `pub struct BullBearPowerResult`
Result of Bull Bear Power calculation
### `pub fn bull_bear_power( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, ) -> Result<BullBearPowerResult>`
Calculate Bull Bear Power.
Bull Power = High - EMA(period)
Bear Power = Low - EMA(period)
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - EMA period (default: 13)
#### Example
```
use finance_query::indicators::bull_bear_power;
let highs = vec![10.0; 20];
let lows = vec![8.0; 20];
let closes = vec![9.0; 20];
let result = bull_bear_power(&highs, &lows, &closes, 13).unwrap();
```
### `pub fn cci(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 149203 instructions/iter, 17006ns median, 2 allocs/iter
### `pub fn cci(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Commodity Channel Index (CCI).
CCI measures the variation of a security's price from its statistical mean.
Formula: CCI = (Typical Price - SMA of Typical Price) / (0.015 * Mean Deviation)
Typical Price = (High + Low + Close) / 3
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - Number of periods
#### Example
```
use finance_query::indicators::cci;
let highs = vec![10.0, 11.0, 12.0, 13.0];
let lows = vec![8.0, 9.0, 10.0, 11.0];
let closes = vec![9.0, 10.0, 11.0, 12.0];
let result = cci(&highs, &lows, &closes, 3).unwrap();
```
### `pub fn chaikin_oscillator( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], ) -> Result<Vec<Option<f64>>>`
**Measured:** 66908 instructions/iter, 15963ns median, 4 allocs/iter
### `pub fn chaikin_oscillator( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], ) -> Result<Vec<Option<f64>>>`
Calculate Chaikin Oscillator.
Difference between 3-day EMA and 10-day EMA of A/D line.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `volumes` - Volume data
#### Example
```
use finance_query::indicators::chaikin_oscillator;
let highs = vec![10.0; 20];
let lows = vec![8.0; 20];
let closes = vec![9.0; 20];
let volumes = vec![100.0; 20];
let result = chaikin_oscillator(&highs, &lows, &closes, &volumes).unwrap();
```
### `pub fn choppiness_index( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, ) -> Result<Vec<Option<f64>>>`
**Measured:** 281356 instructions/iter, 22736ns median, 8 allocs/iter
### `pub fn choppiness_index( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, ) -> Result<Vec<Option<f64>>>`
Calculate Choppiness Index.
Measures market choppiness (consolidation vs trending).
Returns value between 0-100.
Above 61.8 = choppy/consolidating
Below 38.2 = trending
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - Number of periods
#### Example
```
use finance_query::indicators::choppiness_index;
let highs = vec![10.0; 20];
let lows = vec![8.0; 20];
let closes = vec![9.0; 20];
let result = choppiness_index(&highs, &lows, &closes, 14).unwrap();
```
### `pub fn cmf( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], period: usize, ) -> Result<Vec<Option<f64>>>`
**Measured:** 50390 instructions/iter, 3974ns median, 2 allocs/iter
### `pub fn cmf( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], period: usize, ) -> Result<Vec<Option<f64>>>`
Calculate Chaikin Money Flow (CMF).
Measures buying/selling pressure over a period.
Returns value between -1 and 1.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `volumes` - Volume data
* `period` - Number of periods
#### Example
```
use finance_query::indicators::cmf;
let highs = vec![10.0, 11.0, 12.0, 11.0, 10.0];
let lows = vec![8.0, 9.0, 10.0, 9.0, 8.0];
let closes = vec![9.0, 10.0, 11.0, 10.0, 9.0];
let volumes = vec![100.0, 200.0, 150.0, 100.0, 50.0];
let result = cmf(&highs, &lows, &closes, &volumes, 3).unwrap();
```
### `pub fn cmo(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 61742 instructions/iter, 5142ns median, 2 allocs/iter
### `pub fn cmo(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Chande Momentum Oscillator (CMO).
Similar to RSI but uses sum of gains - sum of losses.
Returns value between -100 and 100.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods
#### Example
```
use finance_query::indicators::cmo;
let prices = vec![10.0, 11.0, 12.0, 11.0, 10.0];
let result = cmo(&prices, 3).unwrap();
```
### `pub fn coppock_curve( data: &[f64], long_roc: usize, short_roc: usize, wma_period: usize, ) -> Result<Vec<Option<f64>>>`
**Measured:** 74202 instructions/iter, 7681ns median, 3 allocs/iter
### `pub fn coppock_curve( data: &[f64], long_roc: usize, short_roc: usize, wma_period: usize, ) -> Result<Vec<Option<f64>>>`
Calculate Coppock Curve.
Combines two Rate-of-Change values with WMA smoothing:
`Coppock = WMA(ROC(long_roc) + ROC(short_roc), wma_period)`
#### Arguments
* `data` - Price data (typically close prices)
* `long_roc` - Long ROC period (default: 14)
* `short_roc` - Short ROC period (default: 11)
* `wma_period` - WMA smoothing period (default: 10)
#### Example
```
use finance_query::indicators::coppock_curve;
let prices = vec![10.0; 30];
let result = coppock_curve(&prices, 14, 11, 10).unwrap();
```
### `pub fn dema(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 40936 instructions/iter, 11810ns median, 3 allocs/iter
### `pub fn dema(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Double Exponential Moving Average (DEMA).
DEMA = 2 * EMA - EMA(EMA)
Reduces lag compared to simple EMA.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods
#### Formula
DEMA = 2 * EMA - EMA(EMA)
#### Example
```
use finance_query::indicators::dema;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0];
let result = dema(&prices, 3).unwrap();
```
### `pub fn donchian_channels( highs: &[f64], lows: &[f64], period: usize, ) -> Result<DonchianChannelsResult>`
**Measured:** 181271 instructions/iter, 11820ns median, 9 allocs/iter
### `pub struct DonchianChannelsResult`
Result of Donchian Channels calculation
### `pub fn donchian_channels( highs: &[f64], lows: &[f64], period: usize, ) -> Result<DonchianChannelsResult>`
Calculate Donchian Channels.
Upper Channel = Highest high over period
Lower Channel = Lowest low over period
Middle Channel = (Upper + Lower) / 2
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `period` - Number of periods
#### Example
```
use finance_query::indicators::donchian_channels;
let highs = vec![10.0, 11.0, 12.0, 11.0, 10.0];
let lows = vec![8.0, 9.0, 10.0, 9.0, 8.0];
let result = donchian_channels(&highs, &lows, 3).unwrap();
```
### `pub fn elder_ray( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, ) -> Result<ElderRayResult>`
**Measured:** 29582 instructions/iter, 6875ns median, 3 allocs/iter
### `pub fn elder_ray( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, ) -> Result<ElderRayResult>`
Calculate Elder Ray Index.
Similar to Bull Bear Power; uses EMA of the given period.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - EMA period (default: 13)
#### Example
```
use finance_query::indicators::elder_ray;
let highs = vec![10.0; 20];
let lows = vec![8.0; 20];
let closes = vec![9.0; 20];
let result = elder_ray(&highs, &lows, &closes, 13).unwrap();
```
### `pub fn ema(data: &[f64], period: usize) -> Vec<Option<f64>>`
**Measured:** 488120 instructions/iter, 85866ns median, 27 allocs/iter
### `pub fn ema(data: &[f64], period: usize) -> Vec<Option<f64>>`
Calculate Exponential Moving Average (EMA).
EMA gives more weight to recent prices, making it more responsive than SMA.
The first value is calculated as an SMA, then subsequent values use the EMA formula.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods for the moving average
#### Formula
- First EMA = SMA(period)
- Multiplier = 2 / (period + 1)
- EMA = (Close - Previous EMA) × Multiplier + Previous EMA
#### Example
```
use finance_query::indicators::ema;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0];
let result = ema(&prices, 3);
// First 2 values are None (insufficient data)
assert!(result[0].is_none());
assert!(result[1].is_none());
// Subsequent values are calculated using EMA formula
assert!(result[2].is_some());
```
### `pub fn fibonacci_pivot_points( highs: &[f64], lows: &[f64], closes: &[f64], ) -> Result<Vec<Option<PivotPoints>>>`
**Measured:** 24550 instructions/iter, 2393ns median, 1 allocs/iter
### `pub fn fibonacci_retracement( highs: &[f64], lows: &[f64], period: usize, ) -> Result<Vec<Option<FibonacciLevels>>>`
**Measured:** 184891 instructions/iter, 11595ns median, 9 allocs/iter
### `pub struct FibonacciLevels`
Fibonacci retracement levels between a swing high and swing low.
### `pub fn fibonacci_retracement( highs: &[f64], lows: &[f64], period: usize, ) -> Result<Vec<Option<FibonacciLevels>>>`
Calculate rolling Fibonacci retracement levels.
For each bar, the swing high/low are the highest high and lowest low over
the trailing `period` bars (inclusive), and the standard retracement
levels are interpolated between them (0% = swing high, 100% = swing low —
the conventional orientation for retracing a preceding up-move).
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `period` - Lookback window size (typically 50–100)
#### Example
```
use finance_query::indicators::fibonacci_retracement;
let highs = vec![10.0, 12.0, 11.0, 9.0, 13.0];
let lows = vec![8.0, 9.0, 8.5, 7.0, 10.0];
let result = fibonacci_retracement(&highs, &lows, 3).unwrap();
assert!(result[0].is_none());
assert!(result[2].is_some());
```
### `pub fn heikin_ashi(candles: &[Candle]) -> Result<Vec<Candle>>`
**Measured:** 133768 instructions/iter, 13734ns median, 9 allocs/iter
### `pub fn heikin_ashi(candles: &[Candle]) -> Result<Vec<Candle>>`
Transform standard OHLC candles into Heikin-Ashi candles.
Volume, timestamp, adjusted close, and provider id pass through
unchanged — only open/high/low/close are recomputed.
#### Example
```no_run
use finance_query::{Ticker, Interval, TimeRange};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let ticker = Ticker::new("AAPL").await?;
let chart = ticker.chart(Interval::OneDay, TimeRange::ThreeMonths).await?;
let ha_candles = chart.heikin_ashi()?;
# Ok(())
# }
```
### `pub fn hma(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 103233 instructions/iter, 12837ns median, 5 allocs/iter
### `pub fn hma(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Hull Moving Average (HMA).
HMA = WMA(2 * WMA(n/2) - WMA(n), sqrt(n))
Responsive moving average with reduced lag.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods
#### Formula
HMA = WMA(2 * WMA(n/2) - WMA(n), sqrt(n))
#### Example
```
use finance_query::indicators::hma;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0, 17.0, 18.0];
let result = hma(&prices, 4).unwrap();
```
### `pub fn ichimoku( highs: &[f64], lows: &[f64], closes: &[f64], conversion: usize, base: usize, lagging: usize, displacement: usize, ) -> Result<IchimokuResult>`
**Measured:** 535303 instructions/iter, 35915ns median, 27 allocs/iter
### `pub struct IchimokuResult`
Result of Ichimoku Cloud calculation
### `pub fn ichimoku( highs: &[f64], lows: &[f64], closes: &[f64], conversion: usize, base: usize, lagging: usize, displacement: usize, ) -> Result<IchimokuResult>`
Calculate Ichimoku Cloud.
Returns all five Ichimoku lines. Leading Span B uses `2 * base` bars.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `conversion` - Conversion line (Tenkan-sen) period (default: 9)
* `base` - Base line (Kijun-sen) period; also controls cloud displacement (default: 26)
* `lagging` - Lagging span (Chikou Span) back-displacement in bars (default: 26)
* `displacement` - Cloud forward displacement in bars (default: 26)
#### Example
```
use finance_query::indicators::ichimoku;
let highs = vec![10.0; 100];
let lows = vec![8.0; 100];
let closes = vec![9.0; 100];
let result = ichimoku(&highs, &lows, &closes, 9, 26, 26, 26).unwrap();
```
### `pub fn keltner_channels( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, atr_period: usize, multiplier: f64, ) -> Result<KeltnerChannelsResult>`
**Measured:** 98514 instructions/iter, 17350ns median, 5 allocs/iter
### `pub struct KeltnerChannelsResult`
Result of Keltner Channels calculation
### `pub fn keltner_channels( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, atr_period: usize, multiplier: f64, ) -> Result<KeltnerChannelsResult>`
Calculate Keltner Channels.
Middle Line = EMA(period)
Upper Channel = EMA + (multiplier * ATR)
Lower Channel = EMA - (multiplier * ATR)
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - EMA period
* `atr_period` - ATR period
* `multiplier` - ATR multiplier
#### Example
```
use finance_query::indicators::keltner_channels;
let highs = vec![10.0; 20];
let lows = vec![8.0; 20];
let closes = vec![9.0; 20];
let result = keltner_channels(&highs, &lows, &closes, 10, 10, 2.0).unwrap();
```
### `pub fn last_value(values: &[Option<f64>]) -> Option<f64>`
Helper function to extract the last non-None value from a vector.
Useful for converting historical indicator values to latest value only.
#### Example
```
use finance_query::indicators::last_value;
let values = vec![None, None, Some(10.0), Some(20.0)];
assert_eq!(last_value(&values), Some(20.0));
```
**Measured:** 23 instructions/iter, 2ns median, 0 allocs/iter
### `pub fn macd( data: &[f64], fast_period: usize, slow_period: usize, signal_period: usize, ) -> Result<MacdResult>`
**Measured:** 82597 instructions/iter, 19930ns median, 7 allocs/iter
### `pub struct MacdResult`
MACD calculation result containing the MACD line, signal line, and histogram.
### `pub fn macd( data: &[f64], fast_period: usize, slow_period: usize, signal_period: usize, ) -> Result<MacdResult>`
Calculate Moving Average Convergence Divergence (MACD).
MACD shows the relationship between two moving averages and helps identify trend changes.
Standard parameters are (12, 26, 9).
#### Arguments
* `data` - Price data (typically close prices)
* `fast_period` - Fast EMA period (typically 12)
* `slow_period` - Slow EMA period (typically 26)
* `signal_period` - Signal line EMA period (typically 9)
#### Formula
- MACD Line = 12-period EMA - 26-period EMA
- Signal Line = 9-period EMA of MACD Line
- Histogram = MACD Line - Signal Line
#### Example
```
use finance_query::indicators::macd;
let prices: Vec<f64> = (1..=50).map(|x| x as f64).collect();
let result = macd(&prices, 12, 26, 9).unwrap();
assert_eq!(result.macd_line.len(), prices.len());
assert_eq!(result.signal_line.len(), prices.len());
assert_eq!(result.histogram.len(), prices.len());
```
### `pub fn mcginley_dynamic(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 21714 instructions/iter, 12047ns median, 1 allocs/iter
### `pub fn mcginley_dynamic(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate McGinley Dynamic.
Adaptive moving average that automatically adjusts for market speed.
```text
MD[i] = MD[i-1] + (Price - MD[i-1]) / (N * (Price/MD[i-1])^4)
```
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods
#### Example
```
use finance_query::indicators::mcginley_dynamic;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0];
let result = mcginley_dynamic(&prices, 3).unwrap();
```
### `pub fn mfi( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], period: usize, ) -> Result<Vec<Option<f64>>>`
**Measured:** 94264 instructions/iter, 7331ns median, 3 allocs/iter
### `pub fn mfi( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], period: usize, ) -> Result<Vec<Option<f64>>>`
Calculate Money Flow Index (MFI).
Volume-weighted RSI. Returns value between 0-100.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `volumes` - Volume data
* `period` - Number of periods
#### Example
```
use finance_query::indicators::mfi;
let highs = vec![10.0, 11.0, 12.0, 11.0, 10.0];
let lows = vec![8.0, 9.0, 10.0, 9.0, 8.0];
let closes = vec![9.0, 10.0, 11.0, 10.0, 9.0];
let volumes = vec![100.0, 200.0, 150.0, 100.0, 50.0];
let result = mfi(&highs, &lows, &closes, &volumes, 3).unwrap();
```
### `pub fn momentum(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 8020 instructions/iter, 531ns median, 1 allocs/iter
### `pub fn momentum(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Momentum.
Simple difference between current price and price n periods ago.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods
#### Example
```
use finance_query::indicators::momentum;
let prices = vec![10.0, 11.0, 12.0, 13.0];
let result = momentum(&prices, 2).unwrap();
```
### `pub fn obv(closes: &[f64], volumes: &[f64]) -> Result<Vec<Option<f64>>>`
**Measured:** 313454 instructions/iter, 40980ns median, 14 allocs/iter
### `pub fn obv(closes: &[f64], volumes: &[f64]) -> Result<Vec<Option<f64>>>`
Calculate On-Balance Volume (OBV).
OBV is a cumulative indicator that adds volume on up days and subtracts volume on down days.
It measures buying and selling pressure.
#### Arguments
* `closes` - Close prices
* `volumes` - Trading volumes
#### Returns
Vector of cumulative OBV values.
#### Example
```
use finance_query::indicators::obv;
let closes = vec![100.0, 102.0, 101.0, 103.0, 105.0];
let volumes = vec![1000.0, 1200.0, 900.0, 1500.0, 2000.0];
let result = obv(&closes, &volumes).unwrap();
assert_eq!(result.len(), 5);
```
### `pub fn parabolic_sar( highs: &[f64], lows: &[f64], closes: &[f64], acceleration: f64, maximum: f64, ) -> Result<Vec<Option<f64>>>`
**Measured:** 24998 instructions/iter, 2249ns median, 1 allocs/iter
### `pub fn parabolic_sar( highs: &[f64], lows: &[f64], closes: &[f64], acceleration: f64, maximum: f64, ) -> Result<Vec<Option<f64>>>`
Calculate Parabolic SAR.
Stop and Reverse indicator for trend-following.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `acceleration` - Acceleration factor (e.g., 0.02)
* `maximum` - Maximum acceleration (e.g., 0.2)
#### Example
```
use finance_query::indicators::parabolic_sar;
let highs = vec![10.0, 11.0, 12.0, 13.0];
let lows = vec![8.0, 9.0, 10.0, 11.0];
let closes = vec![9.0, 10.0, 11.0, 12.0];
let result = parabolic_sar(&highs, &lows, &closes, 0.02, 0.2).unwrap();
```
### `pub fn patterns(candles: &[Candle]) -> Vec<Option<CandlePattern>>`
**Measured:** 1184450 instructions/iter, 94756ns median, 1 allocs/iter
### `pub enum CandlePattern`
A detected candlestick pattern.
Returned per-bar by [`patterns`]. Each bar carries at most one pattern;
three-bar patterns take precedence over two-bar, which take precedence over
one-bar.
### `pub enum PatternSentiment`
Directional bias of a candlestick pattern.
### `pub fn patterns(candles: &[Candle]) -> Vec<Option<CandlePattern>>`
Detect candlestick patterns for each bar in `candles`.
Returns a `Vec<Option<CandlePattern>>` of the same length as the input.
`Some(pattern)` means a pattern was detected on that bar; `None` means no
pattern matched. Input must be in chronological order (oldest candle first).
When multiple patterns are technically valid for the same bar, the most
specific (widest lookback) pattern wins: three-bar patterns take precedence
over two-bar, which take precedence over one-bar.
#### Example
```no_run
use finance_query::{Ticker, Interval, TimeRange};
use finance_query::indicators::{patterns, CandlePattern, PatternSentiment};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let ticker = Ticker::new("AAPL").await?;
let chart = ticker.chart(Interval::OneDay, TimeRange::SixMonths).await?;
let signals = patterns(&chart.candles);
let bullish: Vec<_> = signals
.iter()
.enumerate()
.filter(|(_, s)| s.map(|p| p.sentiment() == PatternSentiment::Bullish).unwrap_or(false))
.collect();
println!("{} bullish patterns detected", bullish.len());
# Ok(())
# }
```
### `pub fn pivot_points( highs: &[f64], lows: &[f64], closes: &[f64], ) -> Result<Vec<Option<PivotPoints>>>`
**Measured:** 26053 instructions/iter, 2837ns median, 1 allocs/iter
### `pub struct PivotPoints`
Pivot point support/resistance levels for a single bar.
### `pub fn fibonacci_pivot_points( highs: &[f64], lows: &[f64], closes: &[f64], ) -> Result<Vec<Option<PivotPoints>>>`
Calculate Fibonacci pivot points.
Uses the same central pivot as the standard variant, but Fibonacci
retracement ratios (38.2%, 61.8%, 100%) of the previous bar's range for
the support/resistance levels instead of the classic multiples.
#### Formula
- Pivot = (High + Low + Close) / 3
- R1/S1 = Pivot ± 0.382×Range, R2/S2 = Pivot ± 0.618×Range, R3/S3 = Pivot ± 1.000×Range
#### Example
```
use finance_query::indicators::fibonacci_pivot_points;
let highs = vec![10.0, 12.0, 11.0];
let lows = vec![8.0, 9.0, 8.5];
let closes = vec![9.0, 11.0, 10.0];
let result = fibonacci_pivot_points(&highs, &lows, &closes).unwrap();
assert!(result[0].is_none());
assert!(result[1].is_some());
```
### `pub fn pivot_points( highs: &[f64], lows: &[f64], closes: &[f64], ) -> Result<Vec<Option<PivotPoints>>>`
Calculate classic (standard) pivot points.
Each bar's levels are derived from the **previous** bar's high/low/close;
the first bar has no prior bar and is therefore `None`.
#### Formula
- Pivot = (High + Low + Close) / 3
- R1 = 2×Pivot − Low, S1 = 2×Pivot − High
- R2 = Pivot + (High − Low), S2 = Pivot − (High − Low)
- R3 = High + 2×(Pivot − Low), S3 = Low − 2×(High − Pivot)
#### Example
```
use finance_query::indicators::pivot_points;
let highs = vec![10.0, 12.0, 11.0];
let lows = vec![8.0, 9.0, 8.5];
let closes = vec![9.0, 11.0, 10.0];
let result = pivot_points(&highs, &lows, &closes).unwrap();
assert!(result[0].is_none());
assert!(result[1].is_some());
```
### `pub fn roc(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 16876 instructions/iter, 1633ns median, 1 allocs/iter
### `pub fn roc(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Rate of Change (ROC).
Percentage change over period.
ROC = ((Price - Price[n periods ago]) / Price[n periods ago]) * 100
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods
#### Example
```
use finance_query::indicators::roc;
let prices = vec![10.0, 11.0, 12.0, 13.0];
let result = roc(&prices, 2).unwrap();
```
### `pub fn rsi(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 1190431 instructions/iter, 122627ns median, 52 allocs/iter
### `pub fn rsi(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Relative Strength Index (RSI).
RSI measures the magnitude of recent price changes to evaluate overbought or oversold conditions.
Values range from 0 to 100, with readings above 70 indicating overbought and below 30 indicating oversold.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods (typically 14)
#### Formula
1. Calculate price changes (current - previous)
2. Separate into gains (positive changes) and losses (negative changes, absolute value)
3. Calculate average gain and average loss using EMA
4. RS = Average Gain / Average Loss
5. RSI = 100 - (100 / (1 + RS))
#### Example
```
use finance_query::indicators::rsi;
let prices = vec![44.0, 44.34, 44.09, 43.61, 44.33, 44.83, 45.10, 45.42,
45.84, 46.08, 45.89, 46.03, 45.61, 46.28, 46.28];
let result = rsi(&prices, 14).unwrap();
// First 14 values will be None (need period + 1 for calculation)
assert!(result[13].is_none());
// RSI values start from index 14
assert!(result[14].is_some());
```
### `pub fn sma(data: &[f64], period: usize) -> Vec<Option<f64>>`
**Measured:** 2200136 instructions/iter, 377016ns median, 1 allocs/iter
### `pub fn sma(data: &[f64], period: usize) -> Vec<Option<f64>>`
Calculate Simple Moving Average (SMA).
Returns a vector where each element is the average of the previous `period` values.
The first `period - 1` elements will be `None` since there's insufficient data.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods for the moving average
#### Formula
SMA = (P1 + P2 + ... + Pn) / n
Where:
- P = Price at each period
- n = Number of periods
#### Example
```
use finance_query::indicators::sma;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0];
let result = sma(&prices, 3);
// First 2 values are None (insufficient data)
assert!(result[0].is_none());
assert!(result[1].is_none());
// Third value: (10 + 11 + 12) / 3 = 11.0
assert_eq!(result[2], Some(11.0));
```
### `pub fn stochastic( highs: &[f64], lows: &[f64], closes: &[f64], k_period: usize, k_slow: usize, d_period: usize, ) -> Result<StochasticResult>`
**Measured:** 226828 instructions/iter, 17146ns median, 11 allocs/iter
### `pub struct StochasticResult`
Result of Stochastic Oscillator calculation
### `pub fn stochastic( highs: &[f64], lows: &[f64], closes: &[f64], k_period: usize, k_slow: usize, d_period: usize, ) -> Result<StochasticResult>`
Calculate Stochastic Oscillator.
Returns (%K, %D) where:
- Raw %K = (Close − Lowest Low) / (Highest High − Lowest Low) × 100
- Slow %K = SMA(Raw %K, k_slow) — set `k_slow = 1` for no smoothing
- %D = SMA(Slow %K, d_period)
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `k_period` - Lookback period for raw %K (number of bars)
* `k_slow` - Smoothing period applied to raw %K before computing %D; `1` = no smoothing
* `d_period` - Period for %D signal line (SMA of slow %K)
#### Example
```
use finance_query::indicators::stochastic;
let highs = vec![10.0, 11.0, 12.0, 13.0, 14.0];
let lows = vec![8.0, 9.0, 10.0, 11.0, 12.0];
let closes = vec![9.0, 10.0, 11.0, 12.0, 13.0];
let result = stochastic(&highs, &lows, &closes, 3, 1, 2).unwrap();
```
### `pub fn stochastic_rsi( data: &[f64], rsi_period: usize, stoch_period: usize, k_period: usize, d_period: usize, ) -> Result<StochasticResult>`
**Measured:** 288917 instructions/iter, 27395ns median, 12 allocs/iter
### `pub fn stochastic_rsi( data: &[f64], rsi_period: usize, stoch_period: usize, k_period: usize, d_period: usize, ) -> Result<StochasticResult>`
Calculate Stochastic RSI.
Applies the Stochastic formula to RSI values, then optionally smooths the
result into %K and %D lines — matching the TradingView "Stoch RSI" indicator.
Steps:
1. Compute RSI with `rsi_period`.
2. Apply Stochastic formula over `stoch_period` bars of the RSI series → raw StochRSI.
3. Smooth raw StochRSI with SMA(`k_period`) → %K. Use `k_period = 1` to skip smoothing.
4. Smooth %K with SMA(`d_period`) → %D. Use `d_period = 1` to skip.
#### Arguments
* `data` - Price data (typically close prices)
* `rsi_period` - Period for RSI calculation (e.g. 14)
* `stoch_period` - Lookback period for Stochastic formula on RSI (e.g. 14)
* `k_period` - SMA smoothing period for %K (e.g. 3; use 1 for no smoothing)
* `d_period` - SMA smoothing period for %D (e.g. 3; use 1 for no smoothing)
#### Example
```
use finance_query::indicators::stochastic_rsi;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0, 17.0, 18.0];
let result = stochastic_rsi(&prices, 3, 3, 3, 3).unwrap();
```
### `pub struct AroonData`
Aroon indicator data
### `pub struct BollingerBandsData`
Bollinger Bands data
### `pub struct BullBearPowerData`
Bull Bear Power indicator data
### `pub struct DonchianChannelsData`
Donchian Channels data
### `pub struct ElderRayData`
Elder Ray Index data
### `pub struct IchimokuData`
Ichimoku Cloud data
### `pub struct IndicatorsSummary`
Summary of all calculated technical indicators
### `pub struct KeltnerChannelsData`
Keltner Channels data
### `pub struct MacdData`
MACD indicator data
### `pub struct StochasticData`
Stochastic Oscillator data
### `pub struct SuperTrendData`
SuperTrend indicator data
### `pub fn supertrend( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, multiplier: f64, ) -> Result<SuperTrendResult>`
**Measured:** 118930 instructions/iter, 13679ns median, 4 allocs/iter
### `pub struct SuperTrendResult`
Result of SuperTrend calculation
### `pub fn supertrend( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, multiplier: f64, ) -> Result<SuperTrendResult>`
Calculate SuperTrend.
Trend-following indicator based on ATR.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - ATR period
* `multiplier` - ATR multiplier
#### Example
```
use finance_query::indicators::supertrend;
let highs = vec![10.0; 20];
let lows = vec![8.0; 20];
let closes = vec![9.0; 20];
let result = supertrend(&highs, &lows, &closes, 10, 3.0).unwrap();
```
### `pub fn tema(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 58081 instructions/iter, 18157ns median, 4 allocs/iter
### `pub fn tema(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Triple Exponential Moving Average (TEMA).
TEMA = 3 * EMA - 3 * EMA(EMA) + EMA(EMA(EMA))
Further reduces lag compared to DEMA.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods
#### Formula
TEMA = 3 * EMA - 3 * EMA(EMA) + EMA(EMA(EMA))
#### Example
```
use finance_query::indicators::tema;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0, 17.0, 18.0];
let result = tema(&prices, 3).unwrap();
```
### `pub fn true_range(highs: &[f64], lows: &[f64], closes: &[f64]) -> Result<Vec<Option<f64>>>`
**Measured:** 18089 instructions/iter, 1251ns median, 1 allocs/iter
### `pub fn true_range(highs: &[f64], lows: &[f64], closes: &[f64]) -> Result<Vec<Option<f64>>>`
Calculate True Range.
TR = max(high - low, |high - prev_close|, |low - prev_close|)
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
#### Example
```
use finance_query::indicators::true_range;
let highs = vec![10.0, 11.0, 12.0];
let lows = vec![8.0, 9.0, 10.0];
let closes = vec![9.0, 10.0, 11.0];
let result = true_range(&highs, &lows, &closes).unwrap();
```
### `pub fn vwap( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], ) -> Result<Vec<Option<f64>>>`
**Measured:** 31671 instructions/iter, 3858ns median, 1 allocs/iter
### `pub fn vwap( highs: &[f64], lows: &[f64], closes: &[f64], volumes: &[f64], ) -> Result<Vec<Option<f64>>>`
Calculate Volume Weighted Average Price (VWAP).
VWAP is the average price weighted by volume. It's commonly used as a trading benchmark.
Formula: VWAP = Σ(Typical Price × Volume) / Σ(Volume)
where Typical Price = (High + Low + Close) / 3
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `volumes` - Trading volumes
#### Returns
Vector of cumulative VWAP values.
#### Example
```
use finance_query::indicators::vwap;
let highs = vec![102.0, 104.0, 103.0, 105.0];
let lows = vec![100.0, 101.0, 100.5, 102.0];
let closes = vec![101.0, 103.0, 102.0, 104.0];
let volumes = vec![1000.0, 1200.0, 900.0, 1500.0];
let result = vwap(&highs, &lows, &closes, &volumes).unwrap();
assert_eq!(result.len(), 4);
```
### `pub fn vwma(data: &[f64], volumes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 49541 instructions/iter, 3062ns median, 1 allocs/iter
### `pub fn vwma(data: &[f64], volumes: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Volume Weighted Moving Average (VWMA).
Prices weighted by volume over the given period.
#### Arguments
* `data` - Price data (typically close prices)
* `volumes` - Volume data
* `period` - Number of periods
#### Formula
VWMA = Sum(Price * Volume) / Sum(Volume)
#### Example
```
use finance_query::indicators::vwma;
let prices = vec![10.0, 10.0, 10.0];
let volumes = vec![100.0, 100.0, 100.0];
let result = vwma(&prices, &volumes, 2).unwrap();
```
### `pub fn williams_r( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, ) -> Result<Vec<Option<f64>>>`
**Measured:** 180141 instructions/iter, 11822ns median, 7 allocs/iter
### `pub fn williams_r( highs: &[f64], lows: &[f64], closes: &[f64], period: usize, ) -> Result<Vec<Option<f64>>>`
Calculate Williams %R.
Similar to Stochastic but inverted scale.
%R = (Highest High - Close) / (Highest High - Lowest Low) * -100
Returns value between -100 and 0.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `closes` - Close prices
* `period` - Number of periods
#### Example
```
use finance_query::indicators::williams_r;
let highs = vec![10.0, 11.0, 12.0, 13.0];
let lows = vec![8.0, 9.0, 10.0, 11.0];
let closes = vec![9.0, 10.0, 11.0, 12.0];
let result = williams_r(&highs, &lows, &closes, 3).unwrap();
```
### `pub fn wma(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
**Measured:** 31001 instructions/iter, 4469ns median, 7 allocs/iter
### `pub fn wma(data: &[f64], period: usize) -> Result<Vec<Option<f64>>>`
Calculate Weighted Moving Average (WMA).
WMA gives more weight to recent prices in the calculation.
More recent prices have linearly increasing weights.
#### Arguments
* `data` - Price data (typically close prices)
* `period` - Number of periods for the WMA
#### Returns
Vector of WMA values. Early values (before `period` data points) are None.
#### Example
```
use finance_query::indicators::wma;
let prices = vec![10.0, 11.0, 12.0, 13.0, 14.0, 15.0];
let result = wma(&prices, 3).unwrap();
// First 2 values are None (need 3 periods)
assert_eq!(result[0], None);
assert_eq!(result[1], None);
// Third value: (10*1 + 11*2 + 12*3) / (1+2+3) = 58/6 = 11.333...
assert!(result[2].is_some());
```
### `pub fn zigzag(highs: &[f64], lows: &[f64], deviation_pct: f64) -> Result<Vec<ZigZagPoint>>`
**Measured:** 19859 instructions/iter, 1462ns median, 4 allocs/iter
### `pub struct ZigZagPoint`
A single confirmed ZigZag swing point.
### `pub fn zigzag(highs: &[f64], lows: &[f64], deviation_pct: f64) -> Result<Vec<ZigZagPoint>>`
Calculate ZigZag swing points from high/low series using a percentage
reversal threshold.
Starting from the first bar, price must move by at least `deviation_pct`
(e.g. `5.0` for 5%) away from the running extreme before a reversal is
confirmed and a pivot recorded. Consecutive pivots always alternate
between highs and lows. The final unconfirmed extreme (the most recent
swing-in-progress) is included as the last point.
#### Arguments
* `highs` - High prices
* `lows` - Low prices
* `deviation_pct` - Minimum reversal size as a percentage (e.g. `5.0` = 5%)
#### Example
```
use finance_query::indicators::zigzag;
let highs = vec![100.0, 110.0, 90.0, 120.0, 80.0];
let lows = vec![100.0, 110.0, 90.0, 120.0, 80.0];
let pivots = zigzag(&highs, &lows, 5.0).unwrap();
assert_eq!(pivots.len(), 4);
assert!(pivots[0].is_high);
assert!(!pivots[1].is_high);
```
### `pub async fn insider_trading(symbol: &str, limit: u32) -> Result<Vec<InsiderTransaction>>`
### `pub async fn ipo_calendar() -> Result<Vec<IpoCalendarEntry>>`
### `pub struct CalendarEvent`
A single upcoming financial event.
### `pub enum EventKind`
The kind of financial event, with its event-specific payload.
### `pub enum CalendarDetail`
The event-specific payload of a [`MarketCalendarEntry`].
### `pub enum CalendarKind`
Which market-wide calendar to fetch.
### `pub struct MarketCalendarEntry`
One market-wide calendar entry.
The `kind`-specific payload lives in [`MarketCalendarEntry::detail`].
### `pub struct Candle`
A single OHLCV candle/bar
Note: This struct cannot be manually constructed - obtain via `Ticker::chart()`.
### `pub struct Chart`
Fully typed chart data
Aggregates chart metadata and candles into a single convenient structure.
This is the recommended type for serialization and API responses.
Used for both single symbol and batch historical data requests.
Note: This struct cannot be manually constructed - use `Ticker::chart()` to obtain chart data.
### `pub fn pivot_points( &self, ) -> crate::indicators::Result<Vec<Option<crate::indicators::PivotPoints>>>`
Calculate classic (standard) Pivot Points.
Each bar's levels are derived from the **previous** bar's
high/low/close; the first bar is `None`.
### `pub struct DividendAnalytics`
Computed analytics derived from a symbol's dividend history.
Obtain via [`Ticker::dividend_analytics`](crate::Ticker::dividend_analytics).
### `pub struct CapitalGain`
Public capital gain data
Note: This struct cannot be manually constructed - obtain via `Ticker::capital_gains()`.
### `pub struct ChartEvents`
Chart events containing dividends, splits, and capital gains
Events are deserialized from HashMaps, then lazily converted to sorted vectors
on first access and cached for subsequent calls.
### `pub struct Dividend`
Public dividend data
Note: This struct cannot be manually constructed - obtain via `Ticker::dividends()`.
### `pub struct Split`
Public stock split data
Note: This struct cannot be manually constructed - obtain via `Ticker::splits()`.
### `pub struct ChartMeta`
Metadata for chart data
Note: This struct cannot be manually constructed - obtain via `Ticker::chart()`.
### `pub struct Spark`
Sparkline data for a single symbol.
Contains lightweight chart data optimized for sparkline rendering,
with only timestamps and close prices.
Note: This struct cannot be manually constructed - obtain via `Tickers::spark()`.
### `pub struct CommodityQuote`
A commodity price quote (e.g., gold, silver, crude oil).
Obtain via [`Providers::commodity`](crate::Providers::commodity)`(symbol).quote()`.
### `pub struct AssetProfile`
Company asset profile and information
### `pub struct CompanyOfficer`
Company officer information
### `pub struct CalendarEvents`
Calendar events including earnings and dividend dates
### `pub struct EarningsCalendar`
Earnings calendar information
### `pub struct Earnings`
Earnings data including charts and forecasts
### `pub struct EarningsChart`
Earnings chart showing quarterly data
### `pub struct FinancialsChart`
Financial chart showing revenue and earnings over time
### `pub struct QuarterlyEarnings`
Quarterly earnings entry
### `pub struct QuarterlyFinancials`
Quarterly financial data entry
### `pub struct YearlyFinancials`
Yearly financial data entry
### `pub struct EarningsHistory`
Historical earnings data
### `pub struct EarningsHistoryEntry`
Single historical earnings entry
### `pub struct EarningsTranscript`
One earnings call transcript.
### `pub struct EarningsEstimate`
Earnings estimate data
### `pub struct EarningsTrend`
Earnings trend and estimates
### `pub struct EarningsTrendPeriod`
Earnings trend for a specific period
### `pub struct EpsRevisions`
EPS revision data
### `pub struct EpsTrend`
EPS trend over time
### `pub struct RevenueEstimate`
Revenue estimate data
### `pub struct Benchmark`
Benchmark information
### `pub struct EquityPerformance`
Equity performance data comparing stock returns to benchmark
### `pub struct PerformanceOverview`
Performance metrics across multiple time periods
### `pub struct FundOwner`
Individual fund owner
### `pub struct FundOwnership`
Fund ownership data
### `pub struct AnnualReturn`
Single year's return data
### `pub struct AnnualTotalReturns`
Annual total returns by year
### `pub struct FundPerformance`
Fund performance data including returns, risk metrics, and historical performance
### `pub struct PastQuarterlyReturns`
Past quarterly returns
### `pub struct PerformanceOverview`
Performance overview with key return metrics
### `pub struct PerformanceOverviewCat`
Category average performance overview
### `pub struct RiskOverviewStatistics`
Risk overview statistics
### `pub struct RiskOverviewStatisticsCat`
Category average risk overview statistics
### `pub struct RiskStatistic`
Risk statistics for a specific time period
### `pub struct TrailingReturns`
Trailing returns at market price
### `pub struct TrailingReturnsCat`
Category average trailing returns
### `pub struct TrailingReturnsNav`
Trailing returns at NAV (Net Asset Value)
### `pub struct FeesExpenses`
Fees and expenses for a fund
### `pub struct FeesExpensesCat`
Average fees and expenses for funds in the same category
### `pub struct FundProfile`
Fund profile information including management, fees, and expenses
### `pub struct ManagementInfo`
Fund management information
### `pub struct EmployeeCount`
Employee headcount as reported on one filing.
### `pub struct ExecutiveCompensation`
One executive's reported compensation for one fiscal year.
### `pub struct InsiderHolder`
Individual insider holder information
### `pub struct InsiderHolders`
Insider holders data
### `pub struct InsiderTransaction`
Individual insider transaction
### `pub struct InsiderTransactions`
Insider transaction history
### `pub struct InstitutionOwner`
Individual institutional owner
### `pub struct InstitutionOwnership`
Institutional ownership data
### `pub struct MajorHoldersBreakdown`
Breakdown of ownership by different types of holders
### `pub struct NetSharePurchaseActivity`
Net share purchase activity by insiders
### `pub struct News`
A news article
### `pub struct PressRelease`
A company press release.
### `pub struct Recommendation`
Fully typed recommendation data
Aggregates the queried symbol and its recommendations into a single
convenient structure. This is the recommended type for serialization
and API responses.
Note: This struct cannot be manually constructed - use `Ticker::recommendations()` to obtain recommendations.
### `pub struct SimilarSymbol`
A similar/recommended symbol with score
Note: This struct cannot be manually constructed - obtain via `Ticker::recommendations()`.
### `pub struct RecommendationPeriod`
Recommendations for a specific time period
### `pub struct RecommendationTrend`
Analyst recommendation trends
### `pub struct SecExhibit`
SEC filing exhibit
### `pub struct SecFiling`
Individual SEC filing
### `pub struct SecFilings`
SEC filings data
### `pub struct SummaryProfile`
Company profile information
Contains address, contact information, sector, industry, and business description.
### `pub struct BondRating`
Bond rating distribution
### `pub struct EquityHoldings`
Equity holdings valuation metrics
### `pub struct Holding`
Individual holding in the fund
### `pub struct SectorWeighting`
Sector weighting distribution (single sector from Yahoo's array format)
### `pub struct TopHoldings`
Fund holdings including asset allocation, top holdings, and sector weightings
### `pub struct Paragraph`
A paragraph (section spoken by one speaker).
### `pub struct Sentence`
A sentence within a paragraph.
### `pub struct SpeakerData`
Information about a speaker.
### `pub struct SpeakerMapping`
Mapping of a speaker ID to speaker information.
### `pub struct Transcript`
Full transcript response from Yahoo Finance.
### `pub struct TranscriptContent`
Transcript content including speakers and full transcript.
### `pub struct TranscriptData`
Full transcript data with paragraphs.
### `pub struct TranscriptMetadata`
Metadata about the transcript.
### `pub struct TranscriptWithMeta`
Transcript with metadata from the earnings call list.
Used when fetching multiple transcripts.
### `pub struct Word`
A word with timing and confidence information.
### `pub struct GradeChange`
Individual analyst rating change
### `pub struct UpgradeDowngradeHistory`
Analyst upgrade/downgrade history
### `pub struct CoinQuote`
A cryptocurrency quote from CoinGecko.
Obtain via [`crypto::coins`](crate::crypto::coins) or [`crypto::coin`](crate::crypto::coin).
### `pub struct CryptoQuote`
A provider-agnostic cryptocurrency quote.
Obtain via [`Providers::crypto`](crate::Providers::crypto) then
[`.quote()`](crate::domains::CryptoCoin::quote). Supported providers:
Alpha Vantage, CoinGecko, FMP, Polygon.
### `pub struct GlobalCryptoStats`
Aggregate global cryptocurrency market statistics, from CoinGecko's `/global`.
Obtain via [`Market::crypto_global`](crate::domains::Market::crypto_global).
### `pub struct TrendingCoin`
A coin trending in the last 24h, from CoinGecko's `/search/trending`.
Obtain via [`Market::crypto_trending`](crate::domains::Market::crypto_trending).
### `pub struct ChainAllocation`
One chain's share of a protocol's TVL.
### `pub struct ChainTvl`
Aggregate value locked on one blockchain.
Obtain via [`defi::chains`](crate::defi::chains).
### `pub struct ProtocolTvl`
Total value locked in a DeFi protocol, with the metadata needed to
identify it.
Obtain via [`CryptoCoin::tvl`](crate::CryptoCoin::tvl).
### `pub struct StablecoinSupply`
Circulating supply of one stablecoin.
Obtain via [`defi::stablecoins`](crate::defi::stablecoins).
### `pub struct TvlPoint`
One point of a protocol's TVL history.
Obtain via [`CryptoCoin::tvl_history`](crate::CryptoCoin::tvl_history).
### `pub enum SecurityIdKind`
The kind of identifier being resolved.
Maps onto OpenFIGI's `idType` values.
### `pub struct SecurityMapping`
One instrument matching a security identifier.
A single CUSIP or ISIN maps to **many** instruments — one per venue the
security trades on — which is why resolution returns a list. Entries that
share a `composite_figi` are the same security on different venues; the
`share_class_figi` groups share classes across countries.
Obtain via [`openfigi::resolve_cusip`](crate::openfigi::resolve_cusip) and
friends.
### `pub struct LookupQuote`
A quote/document result from symbol lookup
### `pub struct LookupResults`
Response wrapper for lookup endpoint
### `pub struct ExchangeInfo`
A tradable exchange.
### `pub struct ScreenerFilters`
Filters for a provider-routed screener query.
All fields are optional; unset filters are omitted from the request. Build
with [`ScreenerFilters::new`] and the chainable setters.
### `pub fn new() -> Self`
An empty filter set — matches the provider's default universe.
### `pub struct ScreenerMatch`
A symbol matched by a screener query.
### `pub struct SymbolDetails`
Detailed reference data for a single symbol.
### `pub struct SymbolMatch`
A symbol matched by a search or listing query.
### `pub enum ConditionValue`
The value portion of a typed screener condition.
This cleanly separates the filter value from the field name, replacing the
old `Vec<QueryValue>` approach where the field string was mixed into the same
array as the comparison values.
### `pub enum LogicalOperator`
Logical operator for combining multiple screener conditions.
### `pub enum Operator`
Comparison operator for screener query conditions.
### `pub struct QueryCondition<F: ScreenerField>`
A typed filter condition for a screener query.
Created via [`ScreenerFieldExt`] methods on a field enum variant. The custom
[`Serialize`] impl produces the exact format Yahoo Finance expects:
`{"operator": "gt", "operands": ["fieldname", value]}`.
#### Example
```
use finance_query::{EquityField, ScreenerFieldExt};
let volume_filter = EquityField::AvgDailyVol3M.gt(200_000.0);
let region_filter = EquityField::Region.eq_str("us");
let pe_filter = EquityField::PeRatio.between(10.0, 25.0);
```
### `pub struct QueryGroup<F: ScreenerField>`
A group of query operands combined with a logical operator.
Groups can be nested to form complex AND/OR trees.
### `pub enum QueryOperand<F: ScreenerField>`
An operand within a query group — either a leaf condition or a nested group.
### `pub trait ScreenerField: Clone + Serialize + 'static`
A typed screener field usable in custom query conditions, sorting, and
response field selection.
Both [`EquityField`](super::fields::EquityField) and
[`FundField`](super::fields::FundField) implement this trait.
The `Serialize` bound ensures field values can be included in the JSON body
sent to Yahoo Finance (e.g., in `sortField` and `includeFields`). The
serialization always produces the raw Yahoo API field name string.
### `pub trait ScreenerFieldExt: ScreenerField + Sized`
Fluent condition-building methods on any [`ScreenerField`] type.
This blanket trait is automatically implemented for all types that implement
[`ScreenerField`], including [`EquityField`](super::fields::EquityField) and
[`FundField`](super::fields::FundField).
#### Example
```
use finance_query::{EquityField, ScreenerFieldExt};
// Numeric comparisons
let cond = EquityField::PeRatio.between(10.0, 25.0);
let cond = EquityField::AvgDailyVol3M.gt(500_000.0);
let cond = EquityField::EsgScore.gte(50.0);
// String equality
let cond = EquityField::Region.eq_str("us");
let cond = EquityField::Exchange.eq_str("NMS");
```
### `pub enum EquityField`
Typed field names for equity custom screener queries.
Variants marked as *display-only* (`Ticker`, `CompanyShortName`) are used
in `include_fields` to request those columns in the response. They do not
support meaningful numeric or string filters via Yahoo's API.
All other variants support filtering via [`ScreenerFieldExt`](super::condition::ScreenerFieldExt)
methods. Categorical fields (`Region`, `Sector`, `Industry`, `Exchange`, `PeerGroup`) use
[`eq_str`](super::condition::ScreenerFieldExt::eq_str); all others use numeric operators.
#### Example
```
use finance_query::{EquityField, EquityScreenerQuery, ScreenerFieldExt};
let query = EquityScreenerQuery::new()
.sort_by(EquityField::IntradayMarketCap, false)
.add_condition(EquityField::Region.eq_str("us"))
.add_condition(EquityField::PeRatio.between(10.0, 25.0))
.add_condition(EquityField::AvgDailyVol3M.gt(200_000.0))
.include_fields(vec![
EquityField::Ticker,
EquityField::CompanyShortName,
EquityField::IntradayPrice,
EquityField::PeRatio,
]);
```
### `pub enum FundField`
Typed field names for mutual fund custom screener queries.
Use with [`FundScreenerQuery`](super::query::FundScreenerQuery) and
[`ScreenerFieldExt`](super::condition::ScreenerFieldExt).
#### Example
```
use finance_query::{FundField, FundScreenerQuery, ScreenerFieldExt};
let query = FundScreenerQuery::new()
.sort_by(FundField::PerformanceRating, false)
.add_condition(FundField::RiskRating.lte(3.0))
.include_fields(vec![
FundField::Ticker,
FundField::CompanyShortName,
FundField::IntradayPrice,
FundField::PerformanceRating,
]);
```
### `pub type EquityScreenerQuery = ScreenerQuery<EquityField>`
Type alias for equity (stock) screener queries.
Use [`EquityField`] variants to build conditions.
### `pub type FundScreenerQuery = ScreenerQuery<FundField>`
Type alias for mutual fund screener queries.
Use [`FundField`] variants to build conditions.
### `pub enum QuoteType`
Quote type for custom screener queries.
Yahoo Finance only supports `EQUITY` and `MUTUALFUND` for custom screener queries.
The `alias`es mirror the spellings [`FromStr`](std::str::FromStr) accepts, so
deserializing a request body takes the same spellings parsing does.
### `pub struct ScreenerQuery<F: ScreenerField = EquityField>`
A typed custom screener query for Yahoo Finance.
The type parameter `F` determines which field set is valid for this query.
Use the type aliases for the common cases:
- [`EquityScreenerQuery`] — for stock screeners
- [`FundScreenerQuery`] — for mutual fund screeners
#### Example
```
use finance_query::{EquityField, EquityScreenerQuery, ScreenerFieldExt};
// Find US large-cap value stocks
let query = EquityScreenerQuery::new()
.size(25)
.sort_by(EquityField::IntradayMarketCap, false)
.add_condition(EquityField::Region.eq_str("us"))
.add_condition(EquityField::AvgDailyVol3M.gt(200_000.0))
.add_condition(EquityField::PeRatio.between(10.0, 25.0))
.add_condition(EquityField::IntradayMarketCap.gt(10_000_000_000.0))
.include_fields(vec![
EquityField::Ticker,
EquityField::CompanyShortName,
EquityField::IntradayPrice,
EquityField::PeRatio,
EquityField::IntradayMarketCap,
]);
```
### `pub fn add_or_conditions(mut self, conditions: Vec<QueryCondition<F>>) -> Self`
Add multiple conditions that are OR'd together.
#### Example
```
use finance_query::{EquityField, EquityScreenerQuery, ScreenerFieldExt};
// Accept US or GB region
let query = EquityScreenerQuery::new()
.add_or_conditions(vec![
EquityField::Region.eq_str("us"),
EquityField::Region.eq_str("gb"),
]);
```
### `pub enum SortType`
Sort direction for screener results.
The `alias`es mirror the spellings [`FromStr`](std::str::FromStr) accepts, so
deserializing a request body takes the same spellings parsing does.
### `pub struct ScreenerQuote`
Quote data from a Yahoo Finance screener
This struct contains the fields returned by Yahoo Finance's predefined
screener endpoint. It includes comprehensive quote data for filtering
and displaying screened stocks/funds.
### `pub struct ScreenerResults`
Flattened, user-friendly response for screener results
Returned by the screeners API with a clean structure:
```json
{
"quotes": [...],
"type": "most_actives",
"description": "Stocks ordered in descending order by intraday trade volume",
"lastUpdated": 1234567890,
"total": 100
}
```
This removes Yahoo Finance's nested wrapper structure and internal metadata.
### `pub enum ScreenerFundCategory`
Morningstar fund category for mutual fund screener queries.
Use with [`FundField::CategoryName`](super::fields::FundField::CategoryName) and
[`ScreenerFieldExt::eq_str`](super::condition::ScreenerFieldExt::eq_str).
#### Example
```
use finance_query::{FundField, FundScreenerQuery, ScreenerFieldExt, ScreenerFundCategory};
let query = FundScreenerQuery::new()
.add_condition(FundField::CategoryName.eq_str(ScreenerFundCategory::UsLargeGrowth));
```
### `pub enum ScreenerPeerGroup`
Equity peer group for screener queries.
Use with [`EquityField::PeerGroup`](super::fields::EquityField::PeerGroup) and
[`ScreenerFieldExt::eq_str`](super::condition::ScreenerFieldExt::eq_str).
These are Yahoo Finance's proprietary peer group classifications used to group
stocks for comparison purposes. Values are broader than [`Industry`](crate::Industry)
names.
#### Example
```
use finance_query::{EquityField, EquityScreenerQuery, ScreenerFieldExt, ScreenerPeerGroup};
let query = EquityScreenerQuery::new()
.add_condition(EquityField::PeerGroup.eq_str(ScreenerPeerGroup::Semiconductors));
```
### `pub struct SearchNews`
A news result from search
When the `dataframe` feature is enabled, scalar fields can be converted
to a DataFrame. Complex fields (thumbnail, related_tickers) are automatically skipped.
### `pub struct SearchNewsList(pub Vec<SearchNews>)`
A collection of search news with DataFrame support.
This wrapper allows `search_results.news.to_dataframe()` syntax while still
acting like a `Vec<SearchNews>` for iteration, indexing, etc.
### `pub struct SearchQuote`
A quote result from symbol search
### `pub struct SearchQuotes(pub Vec<SearchQuote>)`
A collection of search quotes with DataFrame support.
This wrapper allows `search_results.quotes.to_dataframe()` syntax while still
acting like a `Vec<SearchQuote>` for iteration, indexing, etc.
### `pub struct ResearchReport`
A research report result from search
### `pub struct ResearchReports(pub Vec<ResearchReport>)`
A collection of research reports with DataFrame support.
This wrapper allows `search_results.research_reports.to_dataframe()` syntax while still
acting like a `Vec<ResearchReport>` for iteration, indexing, etc.
### `pub struct SearchResults`
Response wrapper for search endpoint
### `pub struct NewsThumbnail`
Thumbnail image with multiple resolutions
### `pub struct ThumbnailResolution`
Individual thumbnail resolution
### `pub struct TrendingQuote`
A trending stock/symbol quote
### `pub struct EconomicSeries`
A provider-agnostic economic data series with metadata.
Obtain via [`Providers::economic`](crate::Providers::economic) then
[`.series()`](crate::domains::EconomicIndicator::series). Supported providers:
Alpha Vantage, Polygon, FRED.
### `pub struct MacroObservation`
A single observation in a FRED data series.
### `pub struct MacroSeries`
A FRED macro-economic time series with all its observations.
Obtain via [`fred::series`](crate::fred::series).
### `pub struct TreasuryYield`
One day of US Treasury yield curve rates.
Maturities with no published rate on a given date are `None`.
Obtain via [`fred::treasury_yields`](crate::fred::treasury_yields).
### `pub struct EconomicCategory`
A node in the provider's series category tree.
### `pub struct EconomicRelease`
A publication that releases economic series on a schedule.
### `pub struct EconomicSeriesMatch`
A series matching a catalog search.
### `pub struct CikEntry`
An entry from the SEC ticker-to-CIK mapping.
Maps a stock ticker symbol to its SEC CIK number and company name.
### `pub struct CompanyFacts`
Complete company facts response containing all XBRL financial data.
Facts are organized by taxonomy (e.g., `us-gaap`, `ifrs-full`, `dei`).
Use the convenience methods to access common taxonomies.
#### Example
```no_run
# use finance_query::CompanyFacts;
# fn example(facts: CompanyFacts) {
// Get US-GAAP revenue data
if let Some(revenue) = facts.get_us_gaap_fact("Revenue") {
for (unit, values) in &revenue.units {
println!("Unit: {}, data points: {}", unit, values.len());
}
}
# }
```
### `pub struct FactConcept`
A single XBRL concept (e.g., "Revenue") with all reported values.
Values are organized by unit of measure (e.g., "USD", "shares", "pure").
### `pub struct FactUnit`
A single data point for an XBRL fact.
Represents one reported value from a specific filing and period.
### `pub struct FactsByTaxonomy(pub HashMap<String, FactConcept>)`
Facts within a single taxonomy (e.g., "us-gaap").
Maps concept names (e.g., "Revenue", "Assets") to their [`FactConcept`].
### `pub struct EdgarFilingIndex`
Filing index response for a specific EDGAR accession.
### `pub struct EdgarFilingIndexDirectory`
Directory metadata for an EDGAR filing.
### `pub struct EdgarFilingIndexItem`
Single file entry within an EDGAR filing index.
### `pub struct FilingSearchFilters`
Which parts of a full-text search to constrain.
### `pub struct FilingSearchHit`
One filing matching a full-text search.
### `pub struct CongressionalTrade`
One legislator stock-trade disclosure filed under the STOCK Act.
### `pub struct FailToDeliver`
One SEC fails-to-deliver record for a settlement date.
### `pub struct InsiderTrade`
One transaction line from a Form 3, 4, or 5.
### `pub struct InstitutionalHolding`
One position from a 13F-HR information table.
### `pub struct ProviderFiling`
A single SEC filing entry from a provider.
### `pub struct ProviderFilings`
A collection of SEC filings from a provider (e.g., Polygon EDGAR).
Obtain via [`Ticker::filings`](crate::Ticker::filings).
### `pub struct EdgarSearchHit`
A single search result hit from EDGAR full-text search (Elasticsearch format).
### `pub struct EdgarSearchHitsContainer`
Container for search hits with metadata.
### `pub struct EdgarSearchResults`
Full-text search results from SEC EDGAR.
### `pub struct EdgarSearchSource`
Source data for a search hit containing the actual filing information.
### `pub struct EdgarSearchTotal`
Total count information for search results.
### `pub struct FilingSection`
One section of an SEC filing's text.
### `pub enum FilingSectionForm`
Which filing form to fetch sectioned text for.
### `pub struct RiskFactor`
A risk factor extracted from SEC filings.
### `pub struct EdgarFiling`
A single SEC filing with metadata.
Derived from the parallel arrays in [`EdgarFilingRecent`] via
[`to_filings()`](EdgarFilingRecent::to_filings).
### `pub struct EdgarFilingFile`
Reference to an additional filing history file for older filings.
### `pub struct EdgarFilingRecent`
Recent filings data stored as parallel arrays.
EDGAR returns filing data as parallel arrays (each field is a `Vec` of the same length).
Use [`to_filings()`](EdgarFilingRecent::to_filings) to convert to a `Vec<EdgarFiling>`.
### `pub fn to_filings(&self) -> Vec<EdgarFiling>`
Convert parallel arrays into a vector of individual filings.
#### Example
```no_run
# use finance_query::EdgarSubmissions;
# fn example(submissions: EdgarSubmissions) {
if let Some(filings) = &submissions.filings {
if let Some(recent) = &filings.recent {
for filing in recent.to_filings() {
println!("{}: {} ({})", filing.filing_date, filing.form, filing.primary_doc_description);
}
}
}
# }
```
### `pub struct EdgarFilings`
Container for recent filings and links to older filing history files.
### `pub struct EdgarSubmissions`
Full submissions response for a company from SEC EDGAR.
Contains company metadata and filing history. The `filings` field holds
the most recent ~1000 filings inline, with links to older history files.
### `pub struct ForexQuote`
A forex currency pair quote (e.g., EUR/USD).
Obtain via [`Providers::forex`](crate::Providers::forex) then
[`.quote()`](crate::domains::ForexPair::quote).
### `pub struct Both`
Full format — fields hold `FormattedValue<T>` with `raw`, `fmt`, and `long_fmt`.
Obtain via [`Ticker::quote`](crate::Ticker::quote) with the default `Both`
format parameter. This is the form that can be deserialized directly from
Yahoo Finance JSON.
### `pub trait Format: sealed::Sealed + Clone + std::fmt::Debug + PartialEq + 'static`
Marker trait that controls how [`FormattedValue`](crate::FormattedValue) fields are typed.
Sealed — only [`Both`], [`Raw`], and [`Pretty`] implement this trait.
### `pub struct Pretty`
Pretty format — fields hold an `Option<String>` with the human-readable representation.
Obtain via [`Quote::into_pretty`](crate::Quote::into_pretty).
Falls back to `long_fmt` when `fmt` is absent.
### `pub struct Raw`
Raw format — fields hold `T` directly (e.g. `f64`, `i64`). **This is the default.**
Obtain via [`Ticker::quote()`](crate::Ticker::quote) (the default return type),
[`Quote::into_raw`](crate::Quote::into_raw), or
[`Quote::as_raw`](crate::Quote::as_raw). No `Option`-wrapping of the value itself;
the `Option` at the field level reflects missing data from the API.
### `pub trait Sealed`
Blocks external crates from implementing [`Format`](super::Format);
only this module can name `Sealed`, so it can only be satisfied here.
### `pub struct BalanceSheetHistory`
Balance sheet history (annual statements)
### `pub struct BalanceSheetHistoryQuarterly`
Balance sheet history (quarterly statements)
### `pub struct CashflowStatementHistory`
Cash flow statement history (annual statements)
### `pub struct CashflowStatementHistoryQuarterly`
Cash flow statement history (quarterly statements)
### `pub struct CompanyProfile`
A company's identity and classification profile.
### `pub struct PriceTargetConsensus`
Consensus analyst price target for a symbol.
### `pub struct PriceTargetSummary`
Price-target activity over trailing windows: how many targets were published
and their average, per window.
### `pub struct RatingConsensus`
Consensus rating rollup — the analyst panel's grade distribution plus the
provider's headline recommendation.
### `pub struct DefaultKeyStatistics<F: Format = Both>`
Default key statistics for a symbol
Contains extensive statistical data including valuation metrics, share data, and financial ratios.
The type parameter `F` controls how numeric fields are represented:
- `DefaultKeyStatistics` / `DefaultKeyStatistics<Both>` — **default**; fields hold `FormattedValue<T>`
- `DefaultKeyStatistics<Raw>` — fields hold `T` directly (e.g. `Option<f64>`)
- `DefaultKeyStatistics<Pretty>` — fields hold `Option<String>` (human-readable)
### `pub struct EarningsSurprise`
One reported earnings result versus the analyst estimate.
### `pub struct EtfCountryWeighting`
One country's weight inside an ETF's portfolio.
### `pub struct EtfHolding`
One position inside an ETF's portfolio.
### `pub struct EtfProfile`
Profile and composition of an exchange-traded fund.
### `pub struct EtfSectorWeighting`
One sector's weight inside an ETF's portfolio.
### `pub struct FinancialData<F: Format = Both>`
Financial data and key metrics
Contains financial ratios, margins, cash flow, and analyst recommendations.
The type parameter `F` controls how numeric fields are represented:
- `FinancialData` / `FinancialData<Both>` — **default**; fields hold `FormattedValue<T>`
- `FinancialData<Raw>` — fields hold `T` directly (e.g. `Option<f64>`)
- `FinancialData<Pretty>` — fields hold `Option<String>` (human-readable)
### `pub struct GradingAction`
A single analyst upgrade/downgrade/initiation action.
### `pub struct IncomeStatementHistory`
Income statement history (annual statements)
### `pub struct IncomeStatementHistoryQuarterly`
Income statement history (quarterly statements)
### `pub struct FinancialStatement`
A flattened, user-friendly financial statement
Transforms Yahoo Finance's complex nested response into a simple structure:
```json
{
"symbol": "AAPL",
"statementType": "income",
"frequency": "annual",
"statement": {
"TotalRevenue": { "2024-09-30": 391035000000, "2023-09-30": 383285000000 },
"NetIncome": { "2024-09-30": 100913000000, "2023-09-30": 96995000000 }
}
}
```
This matches the Python finance-query API response format.
### `pub struct ShareFloat`
Share float and shares outstanding.
### `pub struct ShortInterest`
A short-interest data point (bi-monthly settlement report).
### `pub struct ShortVolume`
A daily short-volume data point.
### `pub struct SummaryDetail<F: Format = Both>`
Summary detail trading and valuation metrics
Contains detailed information about price, volume, market cap, and other trading data.
The type parameter `F` controls how numeric fields are represented:
- `SummaryDetail` / `SummaryDetail<Both>` — **default**; fields hold `FormattedValue<T>`
- `SummaryDetail<Raw>` — fields hold `T` directly (e.g. `Option<f64>`)
- `SummaryDetail<Pretty>` — fields hold `Option<String>` (human-readable)
Obtain converted views via [`Quote::as_raw`](crate::Quote::as_raw) or call
`.as_raw()` / `.into_raw()` on a `SummaryDetail<Both>` directly.
### `pub struct FinancialRatiosTtm`
Margin, turnover, liquidity, coverage, valuation, and per-share ratios over
the trailing twelve months.
### `pub struct KeyMetricsTtm`
Valuation, capital-efficiency, and working-capital metrics over the
trailing twelve months.
### `pub struct FuturesQuote`
A futures contract quote.
Obtain via [`Providers::futures`](crate::Providers::futures)`(symbol).quote()`.
### `pub struct CommitmentsOfTraders`
Weekly Commitments of Traders positioning for one futures market.
Obtain via [`FuturesContract::commitments_of_traders`](crate::FuturesContract::commitments_of_traders).
### `pub struct CotObservation`
One weekly report row, broken down by trader category.
### `pub struct IndexConstituent`
A constituent (member) of a major stock market index.
### `pub struct IndexConstituentChange`
A historical change in a major index's constituency.
### `pub struct IndexQuote`
A stock market index quote (e.g., S&P 500, NASDAQ, Dow Jones).
Obtain via [`Providers::index`](crate::Providers::index)`(symbol).quote()`.
### `pub enum MajorIndex`
A major stock market index whose constituent lists providers can serve.
Passed to [`Index::constituents`](crate::Index::constituents) (derived from
the handle's symbol) and the INDICES provider route.
### `pub struct Currency`
A single currency with its properties
### `pub struct Exchange`
Information about a supported exchange.
### `pub struct MarketHours`
Flattened response for market hours
### `pub struct MarketTime`
Market time information for a specific market
### `pub struct IndexTrend`
Index trend data (growth estimates for the index)
### `pub struct IndustryTrend`
Industry trend data
### `pub struct SectorTrend`
Sector trend data
### `pub struct TrendEstimate`
Growth estimate for a specific period
### `pub struct BenchmarkPerformance`
Benchmark performance for comparison
### `pub struct GrowthCompany`
Top growth company by growth estimate
### `pub struct IndustryCompany`
Company within an industry
### `pub struct IndustryData`
Industry data from Yahoo Finance
### `pub struct IndustryOverview`
Industry overview statistics
### `pub struct IndustryPerformance`
Industry performance metrics
### `pub struct PerformingCompany`
Top performing company by YTD return
### `pub struct ResearchReport`
Research report
### `pub struct MarketSummaryQuote`
A single market summary quote (index, currency, commodity, etc.)
### `pub struct SparkData`
Spark chart mini-data for market summary
### `pub struct IndustryPe`
An industry's aggregate price/earnings ratio.
### `pub enum MoverDirection`
Which set of market movers to fetch.
### `pub struct MoverQuote`
A symbol appearing in a market-movers list.
### `pub struct SectorPe`
A sector's aggregate price/earnings ratio.
### `pub struct SectorPerformance`
A sector's aggregate performance.
### `pub struct SectorPerformanceHistory`
One day of aggregate performance across every sector and exchange.
### `pub struct ResearchReport`
A research report about the sector
### `pub struct SectorCompany`
A company in the sector's top companies list
### `pub struct SectorData`
Complete sector data with all available information
### `pub struct SectorETF`
An ETF tracking the sector
### `pub struct SectorIndustry`
An industry within the sector
### `pub struct SectorMutualFund`
A mutual fund in the sector
### `pub struct SectorOverview`
Sector overview statistics
### `pub struct SectorPerformance`
Sector performance metrics
### `pub struct OptionChain`
Options chain data for a specific expiration
Note: This struct cannot be manually constructed - use `Ticker::options()` to obtain options data.
### `pub struct OptionsQuote`
Quote data included with options response
Note: This struct cannot be manually constructed - obtain via `Ticker::options()`.
### `pub struct Contracts(pub Vec<OptionContract>)`
A collection of option contracts with DataFrame support.
This wrapper allows `options.calls.to_dataframe()` syntax while still
acting like a `Vec<OptionContract>` for iteration, indexing, etc.
### `pub struct OptionContract`
An options contract (call or put)
Note: This struct cannot be manually constructed - obtain via `Ticker::options()`.
### `pub struct Options`
Response wrapper for options endpoint
Note: While this type is public for return values, users should not manually construct it.
Use `Ticker::options()` to obtain options data.
### `pub struct Quote<F: Format = Both>`
Flattened quote data with deduplicated fields
This is the primary data structure for stock quotes. It flattens scalar fields
from multiple Yahoo Finance modules while preserving complex nested objects.
#### Creating Quote Instances
Quote instances can only be obtained through the Ticker API:
```no_run
# use finance_query::Ticker;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let ticker = Ticker::builder("AAPL").logo().build().await?;
let quote: finance_query::Quote = ticker.quote().await?;
println!("Price: {:?}", quote.regular_market_price);
# Ok(())
# }
```
Note: This struct is marked `#[non_exhaustive]` and cannot be constructed manually.
Use `Ticker::quote()` or `AsyncTicker::quote()` instead.
#### Field Precedence
For duplicate fields across Yahoo Finance modules:
- Price → SummaryDetail → DefaultKeyStatistics → FinancialData → AssetProfile
All fields are optional since Yahoo Finance may not return all data for every symbol.
#### DataFrame Conversion
With the `dataframe` feature enabled, call `.to_dataframe()` to convert to a polars DataFrame:
```ignore
let df = quote.to_dataframe()?;
```
### `#[derive(Debug, Clone, Serialize, Deserialize, FormatConvert)]`
Clone and convert into a [`Raw`](crate::format::Raw) view.
### `#[derive(Debug, Clone, Serialize, Deserialize, FormatConvert)]`
Convert into a [`Pretty`](crate::format::Pretty) view, extracting `.fmt` from each `FormattedValue` field.
### `#[derive(Debug, Clone, Serialize, Deserialize, FormatConvert)]`
Convert into a [`Raw`](crate::format::Raw) view, extracting `.raw` from each `FormattedValue` field.
### `pub struct FormattedValue<T>`
A generic type representing Yahoo Finance's formatted value pattern
Contains the raw numeric value along with optional formatted representations.
Note: `raw` is optional because Yahoo sometimes returns empty objects `{}` for unavailable data.
### `pub struct Price<F: Format = Both>`
Detailed pricing data for a stock
Includes current price, pre/post market data, volume, market cap, and exchange information.
The type parameter `F` controls how numeric fields are represented:
- `Price` / `Price<Both>` — **default**; fields hold `FormattedValue<T>`
- `Price<Raw>` — fields hold `T` directly (e.g. `Option<f64>`)
- `Price<Pretty>` — fields hold `Option<String>` (human-readable)
### `pub struct QuoteTypeData`
Quote type metadata for a symbol (used in quoteSummary module)
Contains exchange information, company names, timezone data, and other metadata.
### `pub struct QuoteSummaryResponse`
Response from the quoteSummary endpoint
Deserializes all requested modules once on construction to avoid repeated
JSON parsing on every accessor call. Uses `Option<T>` for each module since
Yahoo Finance may not return all modules for all symbols.
The return type of [`QuoteProvider::fetch_quote`](crate::QuoteProvider),
so an implementor populates the modules it can serve and leaves the rest
`None`. Each field mirrors one Yahoo `quoteSummary` module.
### `pub enum AssetClass`
Which market a snapshot row belongs to.
### `pub struct MarketSnapshot`
One symbol's current market state, flattened across asset classes.
Providers return a row per requested symbol even when the lookup failed, so
a batch is never silently short: check [`error`](Self::error) before reading
the price fields.
### `pub struct SymbolSentiment`
Per-symbol sentiment from provider news analysis (Polygon, etc.).
Scores range from -1.0 (very negative) to 1.0 (very positive).
Unlike [`FearAndGreed`] (a market-wide 0—100 gauge from Alternative.me),
this reflects news sentiment for a specific stock.
### `pub struct FearAndGreed`
The current CNN Fear & Greed Index reading from Alternative.me.
Scale: 0 (Extreme Fear) → 100 (Extreme Greed).
### `pub enum FearGreedLabel`
Classification label for the Fear & Greed Index value.
### `pub struct Sentiment`
Sentiment score for a news article or transcript segment.
Only present when the `sentiment` feature is enabled.
### `pub fn neutral() -> Self`
A neutral, zero-confidence score (used as the empty aggregate).
### `pub enum SentimentLabel`
Directional sentiment classification for a piece of text.
### `pub fn analyze(text: &str) -> Sentiment`
Score a single piece of text.
Lexicon lookup is O(tokens) — typically well under a millisecond per
headline. Empty/whitespace text scores [`Sentiment::neutral`].
### `pub enum SecurityIdKind`
### `pub struct SecurityMapping`
### `pub async fn resolve(kind: SecurityIdKind, id: &str) -> Result<Vec<SecurityMapping>>`
Resolve an identifier of any supported [`SecurityIdKind`].
### `pub async fn resolve_cusip(cusip: &str) -> Result<Vec<SecurityMapping>>`
Resolve a CUSIP to every instrument carrying it.
Returns an empty list when the identifier is well-formed but matches
nothing; a malformed identifier is an error.
### `pub async fn resolve_isin(isin: &str) -> Result<Vec<SecurityMapping>>`
Resolve an ISIN to every instrument carrying it.
### `pub async fn resolve_many( kind: SecurityIdKind, ids: &[&str], ) -> Result<Vec<Vec<SecurityMapping>>>`
Resolve many identifiers of the same kind in as few requests as
possible (OpenFIGI accepts 10 per request without a key).
The result is positional: element `i` answers `ids[i]`, with an empty
list where nothing matched.
### `pub async fn resolve_sedol(sedol: &str) -> Result<Vec<SecurityMapping>>`
Resolve a SEDOL to every instrument carrying it.
### `pub fn patterns(candles: &[Candle]) -> Vec<Option<CandlePattern>>`
### `pub fn init(api_key: impl Into<String>) -> Result<()>`
### `pub fn init_with_timeout(api_key: impl Into<String>, timeout: Duration) -> Result<()>`
### `pub trait ProviderCore: Send + Sync`
Identity shared by every capability trait: the provider id and the
`NotSupported` error constructor used by default method bodies.
### `pub trait ProviderAdapter: ProviderCore`
A configured provider as seen by [`crate::ProviderSet`] dispatch: lifecycle
plus one `as_*` accessor per capability. Override an accessor to
`Some(self)` for each capability trait the provider implements.
[`capabilities`](Self::capabilities) is derived from which accessors are
overridden, so a provider cannot advertise a capability it does not serve.
### `pub trait ChartProvider: ProviderCore`
[`crate::Capability::CHART`] — historical OHLCV candles and sparklines.
### `pub trait CorporateProvider: ProviderCore`
[`crate::Capability::CORPORATE`] — news, corporate events, similar-symbol
recommendations.
### `pub trait FilingsProvider: ProviderCore`
[`crate::Capability::FILINGS`] — SEC filing data.
### `pub trait FundamentalsProvider: ProviderCore`
[`crate::Capability::FUNDAMENTALS`] — financial statements and share-supply data.
### `pub trait OptionsProvider: ProviderCore`
[`crate::Capability::OPTIONS`] — options chains.
### `pub trait QuoteProvider: ProviderCore`
[`crate::Capability::QUOTE`] — single and batch equity quotes.
### `pub trait CalendarProvider: ProviderCore`
[`crate::Capability::CALENDAR`] — market-wide calendars.
### `pub trait CommoditiesProvider: ProviderCore`
[`crate::Capability::COMMODITIES`] — commodity price quotes.
### `pub trait CryptoProvider: ProviderCore`
[`crate::Capability::CRYPTO`] — cryptocurrency quotes.
### `pub trait DiscoveryProvider: ProviderCore`
[`crate::Capability::DISCOVERY`] — symbol search, reference data, exchanges,
screeners.
### `pub trait EconomicProvider: ProviderCore`
[`crate::Capability::ECONOMIC`] — macro-economic data series.
### `pub trait ForexProvider: ProviderCore`
[`crate::Capability::FOREX`] — currency-pair quotes.
### `pub trait FuturesProvider: ProviderCore`
[`crate::Capability::FUTURES`] — futures contract quotes.
### `pub trait IndicesProvider: ProviderCore`
[`crate::Capability::INDICES`] — stock market index quotes.
### `pub trait MarketProvider: ProviderCore`
[`crate::Capability::MARKET`] — sector/industry performance and movers.
Movers is the required primary (every current implementor serves it);
the sector/industry statistics default to `NotSupported` since coverage
is ragged (FMP serves all of them; Yahoo and Alpha Vantage only movers).
### `pub struct Capability(u32)`
Capability bits that a provider can declare.
Route a capability to specific providers using `.route(Capability::QUOTE, [Provider::Fmp])`.
If no route is configured for a capability, only Yahoo is used, or EDGAR
then Yahoo for [`Capability::FILINGS`].
### `pub fn name(self) -> &'static str`
Returns a short lowercase name for this capability (e.g., `"quote"`, `"chart"`).
Returns `"unknown"` for combined capability flags or unrecognised bits;
[`Display`](std::fmt::Display) spells combined sets out instead (e.g.
`"quote|chart"`).
### `pub struct Providers`
Central provider configuration shared across query handles.
Build once with [`Providers::builder`], then create lightweight
[`Ticker`](crate::Ticker) handles that share the same underlying
provider connections and authentication.
#### Example
```no_run
use finance_query::{Providers, Provider, Fetch, Capability};
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let providers = Providers::builder()
.route(Capability::QUOTE, [Provider::Yahoo])
.fetch(Fetch::Sequential)
.build().await?;
// All Ticker handles share the same Arc<ProviderSet>
let aapl = providers.ticker("AAPL").build().await?;
let nvda = providers.ticker("NVDA").logo().build().await?;
# Ok(())
# }
```
### `pub fn builder() -> ProvidersBuilder`
Create a builder for configuring providers.
### `pub fn calendar(&self) -> crate::domains::MarketCalendar`
Create a [`MarketCalendar`](crate::MarketCalendar) handle backed by this provider set.
Routes market-wide earnings/IPO/dividend/split/economic calendars
through [`Capability::CALENDAR`](crate::Capability::CALENDAR).
### `pub fn commodity(&self, symbol: impl Into<String>) -> crate::domains::Commodity`
Create a [`Commodity`](crate::Commodity) handle backed by this provider set.
### `pub fn crypto(&self, id: impl Into<String>) -> crate::domains::CryptoCoin`
Create a [`CryptoCoin`](crate::CryptoCoin) handle backed by this provider set.
Compiled in unconditionally. With no built-in provider for this
capability, register one with [`ProvidersBuilder::with_adapter`] or
enable its feature, or these calls return `NoProviderAvailable`.
### `pub fn discovery(&self) -> crate::domains::Discovery`
Create a [`Discovery`](crate::Discovery) handle backed by this provider set.
Routes symbol search, reference data, and screening through
[`Capability::DISCOVERY`](crate::Capability::DISCOVERY). Distinct from
[`crate::finance::search`], which is a Yahoo-only shortcut.
### `pub fn economic(&self, series_id: impl Into<String>) -> crate::domains::EconomicIndicator`
Create an [`EconomicIndicator`](crate::EconomicIndicator) handle backed by this provider set.
Compiled in unconditionally. With no built-in provider for this
capability, register one with [`ProvidersBuilder::with_adapter`] or
enable its feature, or these calls return `NoProviderAvailable`.
### `pub fn economic_catalog(&self) -> crate::domains::EconomicCatalog`
Create an [`EconomicCatalog`](crate::EconomicCatalog) handle backed by
this provider set.
Routes series search and category/release browsing through
[`Capability::ECONOMIC`](crate::Capability::ECONOMIC). Unlike
[`economic`](Self::economic) it takes no series id — it is how you find
one.
Compiled in unconditionally. With no built-in provider for this
capability, register one with [`ProvidersBuilder::with_adapter`] or
enable its feature, or these calls return `NoProviderAvailable`.
### `pub fn filings(&self, symbol: impl Into<String>) -> crate::domains::Filings`
Create a [`Filings`](crate::Filings) handle backed by this provider set.
Always available — EDGAR is auto-injected when no other FILINGS provider
is configured.
### `pub fn forex( &self, from: impl Into<String>, to: impl Into<String>, ) -> crate::domains::ForexPair`
Create a [`ForexPair`](crate::ForexPair) handle backed by this provider set.
Compiled in unconditionally. With no built-in provider for this
capability, register one with [`ProvidersBuilder::with_adapter`] or
enable its feature, or these calls return `NoProviderAvailable`.
### `pub fn from_set(set: Arc<ProviderSet>) -> Self`
Wrap a [`ProviderSet`] assembled by hand.
The lower-level counterpart to [`builder`](Self::builder), for a caller
that has already built its own adapters and route table. Nothing is
initialised: [`ProviderAdapter::initialize`](crate::ProviderAdapter::initialize)
is the builder's job, so a hand-built set must be ready to use.
### `pub fn futures(&self, symbol: impl Into<String>) -> crate::domains::FuturesContract`
Create a [`FuturesContract`](crate::FuturesContract) handle backed by this provider set.
### `pub fn health(&self) -> Vec<ProviderHealth>`
Snapshot recent health for every configured provider.
Each [`ProviderHealth`] entry reflects up to the last 20 dispatch
outcomes recorded in-process for that provider (recency window is
internal and unspecified beyond "recent"), plus a best-effort
rate-limit budget estimate where the provider exposes one. Purely
observational — it does not affect routing or retries.
#### Example
```no_run
use finance_query::Providers;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let providers = Providers::builder().build().await?;
for health in providers.health() {
println!("{:?}: healthy={}", health.provider, health.is_healthy);
}
# Ok(())
# }
```
### `pub fn index(&self, symbol: impl Into<String>) -> crate::domains::Index`
Create an [`Index`](crate::Index) handle backed by this provider set.
### `pub fn market(&self) -> crate::domains::Market`
Create a [`Market`](crate::Market) handle backed by this provider set.
Routes sector/industry performance and movers through
[`Capability::MARKET`](crate::Capability::MARKET). Movers work on the
default keyless route (Yahoo screeners); the sector/industry
statistics need a keyed provider (FMP).
### `pub fn snapshot(&self) -> crate::domains::Snapshot`
Create a [`Snapshot`](crate::Snapshot) handle backed by this provider set.
Routes cross-market snapshots through
[`Capability::QUOTE`](crate::Capability::QUOTE). Needs a provider whose
snapshot endpoint spans asset classes, currently Polygon alone.
Compiled in unconditionally. With no built-in provider for this
capability, register one with [`ProvidersBuilder::with_adapter`] or
enable its feature, or these calls return `NoProviderAvailable`.
### `pub fn ticker(&self, symbol: impl Into<String>) -> crate::TickerBuilder`
Create a [`TickerBuilder`](crate::TickerBuilder) pre-wired to this provider set.
The returned builder accepts the same optional configuration as
[`Ticker::builder`](crate::Ticker::builder) (`.cache()`, `.logo()`,
`.format()`) before calling `.build()`.
The language configured via [`ProvidersBuilder::lang`] or
[`ProvidersBuilder::region`] is inherited (override with `.lang()` on
the returned builder). With the `translation` feature, a non-English
language translates text fields automatically.
### `pub fn tickers<S, I>(&self, symbols: I) -> crate::TickersBuilder where S: Into<String>, I: IntoIterator<Item = S>,`
Create a [`TickersBuilder`](crate::TickersBuilder) pre-wired to this provider set.
The returned builder accepts the same optional configuration as
[`Tickers::builder`](crate::Tickers::builder) (`.cache()`,
`.max_concurrency()`, `.logo()`, `.format()`) before calling `.build()`.
The language configured via [`ProvidersBuilder::lang`] or
[`ProvidersBuilder::region`] is inherited (override with `.lang()` on
the returned builder). With the `translation` feature, a non-English
language translates text fields automatically.
### `pub struct ProvidersBuilder`
Builder for [`Providers`].
### `pub fn fetch(mut self, mode: Fetch) -> Self`
Configure how providers are queried. Default: `Sequential`.
Use [`Fetch::Sequential`] or [`Fetch::Parallel`].
### `pub fn lang(mut self, lang: impl Into<String>) -> Self`
Set the language code (e.g., "en-US", "ja-JP").
Inherited by every `Ticker`/`Tickers` handle created from the built
[`Providers`]. With the `translation` feature, a non-English language
translates text fields on those handles automatically.
### `pub fn region(mut self, region: crate::constants::Region) -> Self`
Set the region (automatically sets lang and region code).
### `pub fn retry(mut self, policy: RetryPolicy) -> Self`
Opt into retrying `FinanceError::RateLimited` errors during dispatch
See [`RetryPolicy`] for the exact semantics.
**Default is no retry** — omitting this call preserves the exact
prior behavior: a `RateLimited` error is treated like any other
failure and dispatch moves straight to the next routed provider.
### `pub fn with_adapter(mut self, adapter: Arc<dyn crate::ProviderAdapter>) -> Self`
Register an adapter this crate does not build itself.
Route to it by the id its [`ProviderCore::id`](crate::ProviderCore::id)
returns, usually [`Provider::Custom`]. Registering alone does not route
anything: a capability with no explicit route still falls back to its
default provider.
```no_run
# use std::sync::Arc;
# use finance_query::{Capability, Provider, Providers, ProviderAdapter};
# async fn f(my_adapter: Arc<dyn ProviderAdapter>) -> finance_query::Result<()> {
let providers = Providers::builder()
.with_adapter(my_adapter)
.route(Capability::ECONOMIC, [Provider::custom("my-source")])
.build()
.await?;
# let _ = providers;
# Ok(())
# }
```
### `pub struct ProviderHealth`
Snapshot of one provider's recent health and (where derivable) remaining
rate-limit budget.
Purely observational — computed from the last `WINDOW` dispatch
outcomes recorded in-process by [`super::ProviderSet`]; it is not a
circuit breaker and does not itself change dispatch behavior (routing and
[`RetryPolicy`](super::retry::RetryPolicy) are unaffected by it).
### `pub enum Operation`
A single provider-adapter operation — finer-grained than [`Capability`]
(e.g. `Chart`, `ChartRange`, and `Spark` all fall under `Capability::CHART`).
Used in [`crate::FinanceError::NotSupported`] to say exactly which method a
provider doesn't implement; [`Operation::capability`] recovers the coarser
bit for computing which other providers could satisfy it.
### `pub fn capability(self) -> Capability`
The coarser [`Capability`] bit this operation falls under.
### `pub struct CustomId(u16)`
Index of a custom provider id, obtained from [`Provider::custom`].
Opaque so that only an interned id can be named: the index is meaningless
outside the process that registered it.
### `pub enum Provider`
Typed identifier for a financial data provider.
Variants are feature-gated: unavailable providers are excluded at compile time.
### `pub fn capabilities(self) -> Capability`
Capability bitflags for this provider variant, derived from each
adapter's `as_*` accessor overrides — implementing a capability trait
and declaring it can no longer drift apart. Yahoo is the one exception:
constructing `YahooProvider` needs a live auth handshake, so its set is
a const declared beside its accessor overrides (`yahoo::CAPS`).
[`Provider::Custom`] returns [`Capability::NONE`]. An id carries no
adapter, so a custom provider's real set is
[`ProviderAdapter::capabilities`](crate::ProviderAdapter::capabilities)
on the registered instance.
### `pub fn custom(id: &'static str) -> Self`
A provider this crate does not build, identified by `id`.
Interning is process-wide and append-only, so the same id always maps
to the same value and `Provider::custom("x") == Provider::custom("x")`.
### `pub struct RetryPolicy`
Retry policy for [`super::ProviderSet`] dispatch, opt-in via
[`crate::Providers::builder`]`().`[`retry`](super::config::ProvidersBuilder::retry)`(..)`.
When configured, a candidate provider that returns
[`FinanceError::RateLimited`](crate::error::FinanceError::RateLimited) is
retried in place — honoring the error's `retry_after` hint when present
(capped by `max_retry_after`), or this policy's own
exponential-backoff-plus-jitter delay otherwise — up to `max_attempts`
times before dispatch falls through to the next routed provider (or
fails, if it was the last).
Other error kinds are never retried by this policy: a `RateLimited` is the
one error a policy-level retry can reliably fix by waiting; anything else
(auth failures, 5xx, not-found, ...) is left to the existing
sequential/parallel provider fallback.
**Default is no retry** — a [`Providers`](crate::Providers) built without
calling `.retry(..)` behaves exactly as before this policy existed.
#### Example
```no_run
use finance_query::{Providers, RetryPolicy};
use std::time::Duration;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let providers = Providers::builder()
.retry(RetryPolicy::new(3).base_delay(Duration::from_millis(500)))
.build()
.await?;
# Ok(())
# }
```
### `pub fn base_delay(mut self, delay: Duration) -> Self`
Override the base delay (see [`RetryPolicy::base_delay`] field docs).
### `pub fn jitter(mut self, jitter: f64) -> Self`
Override the jitter fraction (see [`RetryPolicy::jitter`] field docs).
### `pub fn max_delay(mut self, max_delay: Duration) -> Self`
Override the max delay cap (see [`RetryPolicy::max_delay`] field docs).
### `pub fn max_retry_after(mut self, max_retry_after: Duration) -> Self`
Override the cap on an explicit `retry_after` hint
(see [`RetryPolicy::max_retry_after`] field docs).
### `pub fn multiplier(mut self, multiplier: f64) -> Self`
Override the backoff multiplier (see [`RetryPolicy::multiplier`] field docs).
### `pub enum Fetch`
How providers are queried.
### `pub struct Routes`
Per-capability provider routing table.
Maps each [`Capability`] to an ordered list of [`Provider`]s to try. A
capability with no entry falls back to Yahoo, or to EDGAR then Yahoo for
[`Capability::FILINGS`].
Each route may carry its own [`Fetch`] mode, so a quota-limited capability
can stay sequential while another races its providers. Routes without one
use the table default.
### `pub struct AssetProfile`
### `pub struct CalendarEvents`
### `pub struct CompanyOfficer`
### `pub struct DefaultKeyStatistics<F: Format = Both>`
### `pub struct Earnings`
### `pub struct EarningsHistory`
### `pub struct EarningsTrend`
### `pub struct EquityPerformance`
### `pub struct FinancialData<F: Format = Both>`
### `pub struct FundOwnership`
### `pub struct FundPerformance`
### `pub struct FundProfile`
### `pub struct IndexTrend`
### `pub struct IndustryTrend`
### `pub struct InsiderHolders`
### `pub struct InsiderTransactions`
### `pub struct InstitutionOwnership`
### `pub struct MajorHoldersBreakdown`
### `pub struct NetSharePurchaseActivity`
### `pub struct Price<F: Format = Both>`
### `pub struct QuoteTypeData`
### `pub struct RecommendationTrend`
### `pub struct SecFilings`
### `pub struct SectorTrend`
### `pub struct SummaryDetail<F: Format = Both>`
### `pub struct SummaryProfile`
### `pub struct TopHoldings`
### `pub struct UpgradeDowngradeHistory`
### `pub struct RiskSummary`
Comprehensive risk summary for a symbol.
Obtain via [`Ticker::risk`](crate::Ticker::risk).
### `pub fn beta(asset_returns: &[f64], benchmark_returns: &[f64]) -> Option<f64>`
**Measured:** 262224 instructions/iter, 61131ns median, 0 allocs/iter
### `pub fn beta(asset_returns: &[f64], benchmark_returns: &[f64]) -> Option<f64>`
Compute the beta of an asset relative to a benchmark.
`β = Cov(asset, benchmark) / Var(benchmark)`
Both slices must have the same length and at least 2 observations.
Returns `None` on insufficient data or zero benchmark variance.
### `pub fn calmar_ratio(total_return: f64, years: f64, max_drawdown: f64) -> Option<f64>`
**Measured:** 156 instructions/iter, 17ns median, 0 allocs/iter
### `pub fn historical_cvar(returns: &[f64], confidence: f64) -> Option<f64>`
Compute historical CVaR (Expected Shortfall) at the given confidence level.
#### Arguments
* `returns` - Daily log-returns or simple returns (as fractions, e.g. 0.02 = 2%)
* `confidence` - Confidence level, e.g. 0.95 for 95% CVaR
Returns `None` when `returns` is empty.
### `pub fn parametric_cvar(returns: &[f64], confidence: f64) -> Option<f64>`
Compute parametric CVaR assuming normally distributed returns.
Uses the closed-form Expected Shortfall for a normal distribution:
`ES = -(mean - std_dev * phi(z) / (1 - confidence))`, where `phi` is the
standard normal density and `z` is the confidence level's quantile.
#### Arguments
* `returns` - Daily returns as fractions
* `confidence` - Confidence level (0.95 or 0.99 are common)
Returns `None` when fewer than 2 observations are provided.
### `pub struct DrawdownResult`
Maximum drawdown result.
### `pub fn max_drawdown(returns: &[f64]) -> DrawdownResult`
Compute the maximum drawdown from a return series.
#### Arguments
* `returns` - Per-period returns as fractions (e.g., daily returns)
Returns `DrawdownResult` with `max_drawdown = 0.0` when `returns` is empty.
### `pub fn historical_cvar(returns: &[f64], confidence: f64) -> Option<f64>`
**Measured:** 4332813 instructions/iter, 338015ns median, 2 allocs/iter
### `pub fn historical_var(returns: &[f64], confidence: f64) -> Option<f64>`
**Measured:** 31167375 instructions/iter, 2566797ns median, 2 allocs/iter
### `pub fn information_ratio( asset_returns: &[f64], benchmark_returns: &[f64], periods_per_year: f64, ) -> Option<f64>`
**Measured:** 145879 instructions/iter, 35908ns median, 1 allocs/iter
### `pub fn kelly_criterion(win_rate: f64, avg_win_pct: f64, avg_loss_pct: f64) -> f64`
**Measured:** 30925 instructions/iter, 4067ns median, 16 allocs/iter
### `pub fn max_drawdown(returns: &[f64]) -> DrawdownResult`
**Measured:** 35226 instructions/iter, 8025ns median, 1 allocs/iter
### `pub fn omega_ratio(returns: &[f64]) -> f64`
**Measured:** 139305 instructions/iter, 30551ns median, 0 allocs/iter
### `pub fn parametric_cvar(returns: &[f64], confidence: f64) -> Option<f64>`
**Measured:** 100416 instructions/iter, 30595ns median, 0 allocs/iter
### `pub fn parametric_var(returns: &[f64], confidence: f64) -> Option<f64>`
**Measured:** 100412 instructions/iter, 30593ns median, 0 allocs/iter
### `pub fn calmar_ratio(total_return: f64, years: f64, max_drawdown: f64) -> Option<f64>`
Compute the Calmar Ratio: annualised return divided by maximum drawdown.
#### Arguments
* `total_return` - Cumulative return over the entire period (fraction)
* `years` - Length of the period in years
* `max_drawdown` - Maximum drawdown as a positive fraction (e.g., 0.30 = 30%)
Returns `None` when `max_drawdown` is zero.
### `pub fn information_ratio( asset_returns: &[f64], benchmark_returns: &[f64], periods_per_year: f64, ) -> Option<f64>`
Compute the Information Ratio vs a benchmark: annualised mean excess
return divided by tracking error.
Returns `None` when the series differ in length, fewer than 2 aligned
observations are available, or tracking error is zero.
### `pub fn kelly_criterion(win_rate: f64, avg_win_pct: f64, avg_loss_pct: f64) -> f64`
Compute the Kelly Criterion: optimal fraction of capital to risk, given a
win rate and average win/loss magnitudes (in percent).
`W - (1 - W) / R` where `R = avg_win_pct / abs(avg_loss_pct)`. Returns
`f64::MAX` when there are no losses and wins are positive (unbounded
edge), `0.0` for other degenerate inputs.
Use [`win_loss_stats`] to derive `win_rate`/`avg_win_pct`/`avg_loss_pct`
from a plain return series (treating each positive-return period as a
"win" and each negative-return period as a "loss").
### `pub fn omega_ratio(returns: &[f64]) -> f64`
Compute the Omega Ratio at a `0.0` threshold: probability-weighted ratio
of gains to losses over the full return distribution.
`Σ max(r, 0) / Σ max(-r, 0)`. More general than Sharpe — considers the
full return distribution rather than only mean and standard deviation.
Returns `f64::MAX` when there are no negative returns, `0.0` when there
are also no positive returns.
### `pub fn sharpe_ratio(returns: &[f64], risk_free_rate: f64, periods_per_year: f64) -> Option<f64>`
Compute the annualised Sharpe Ratio.
`Sharpe = (mean_return - risk_free_rate) / std_dev`, annualised by `sqrt(periods_per_year)`.
#### Arguments
* `returns` - Per-period returns as fractions (e.g., daily returns)
* `risk_free_rate` - Risk-free rate **per period** (e.g., 0.0001 for daily ≈ 2.5% annual)
* `periods_per_year` - Trading periods in a year (252 for daily, 52 for weekly)
Returns `None` when fewer than 2 observations or standard deviation is zero.
### `pub fn sortino_ratio(returns: &[f64], risk_free_rate: f64, periods_per_year: f64) -> Option<f64>`
Compute the annualised Sortino Ratio (penalises only downside volatility).
`Sortino = (mean_return - risk_free_rate) / downside_std`, annualised.
Returns `None` when fewer than 2 observations or downside deviation is zero.
### `pub fn tracking_error( asset_returns: &[f64], benchmark_returns: &[f64], periods_per_year: f64, ) -> Option<f64>`
Compute the tracking error vs a benchmark: annualised standard deviation
of (asset − benchmark) periodic returns.
Returns `None` when the series differ in length or fewer than 2 aligned
observations are available.
### `pub fn ulcer_index(returns: &[f64]) -> f64`
Compute the Ulcer Index: root-mean-square of drawdown depth across a
return series, expressed as a percentage (0–100).
Unlike [`max_drawdown`](super::max_drawdown), penalises both depth and
duration of drawdowns — a long shallow drawdown scores higher than a
brief deep one.
### `pub fn win_loss_stats(returns: &[f64]) -> (f64, f64, f64)`
Derive win-rate and average win/loss percentages from a return series,
treating each period as if it were a discrete "trade" (a positive-return
period is a win, a negative-return period is a loss) — the natural
analogue of backtesting trade statistics for a plain returns series with
no explicit trade log. Feeds [`kelly_criterion`].
Returns `(win_rate, avg_win_pct, avg_loss_pct)`, all `0.0` for an empty
series.
### `pub fn sharpe_ratio(returns: &[f64], risk_free_rate: f64, periods_per_year: f64) -> Option<f64>`
**Measured:** 100406 instructions/iter, 30643ns median, 0 allocs/iter
### `pub fn sortino_ratio(returns: &[f64], risk_free_rate: f64, periods_per_year: f64) -> Option<f64>`
**Measured:** 161843 instructions/iter, 30576ns median, 0 allocs/iter
### `pub fn tracking_error( asset_returns: &[f64], benchmark_returns: &[f64], periods_per_year: f64, ) -> Option<f64>`
**Measured:** 145876 instructions/iter, 35991ns median, 1 allocs/iter
### `pub fn ulcer_index(returns: &[f64]) -> f64`
**Measured:** 619414 instructions/iter, 175247ns median, 2 allocs/iter
### `pub fn historical_var(returns: &[f64], confidence: f64) -> Option<f64>`
Compute historical VaR at the given confidence level.
Returns the loss that is exceeded only `(1 - confidence)` fraction of the time,
expressed as a positive number (a loss).
#### Arguments
* `returns` - Daily log-returns or simple returns (as fractions, e.g. 0.02 = 2%)
* `confidence` - Confidence level, e.g. 0.95 for 95% VaR
Returns `None` when `returns` is empty.
### `pub fn parametric_var(returns: &[f64], confidence: f64) -> Option<f64>`
Compute parametric (variance-covariance) VaR assuming normally distributed returns.
Uses the normal distribution's z-score for the confidence level.
#### Arguments
* `returns` - Daily returns as fractions
* `confidence` - Confidence level (0.95 or 0.99 are common)
Returns `None` when fewer than 2 observations are provided.
### `pub fn win_loss_stats(returns: &[f64]) -> (f64, f64, f64)`
**Measured:** 389633 instructions/iter, 170830ns median, 25 allocs/iter
### `pub enum AlertCondition`
### `pub enum AlertConditionKind`
### `pub struct AlertEvaluator`
### `pub struct AlertEvent`
### `pub trait AlertExt: Stream<Item = PriceUpdate> + Sized + Unpin`
### `pub struct AlertRule`
### `pub struct AlertStream<S>`
### `pub enum AssetClass`
### `pub struct Batched<S> where S: Stream,`
### `pub struct BookLevel`
### `stream_handle!`
### `pub struct DepthStreamBuilder`
### `stream_handle!`
### `pub struct EconomicStreamBuilder`
### `pub struct Greeks`
### `pub enum MarketHoursType`
### `pub struct NewsStream`
### `pub struct NewsStreamBuilder`
### `pub struct OptionContractUpdate`
### `pub enum OptionType`
### `stream_handle!`
### `pub struct OptionsChainStreamBuilder`
### `pub struct OrderBookUpdate`
### `pub enum PriceSource`
### `pub struct PriceStream`
### `pub struct PriceStreamBuilder`
### `pub struct PriceUpdate`
**Measured:** 11065 instructions/iter, 1032ns median, 4 allocs/iter
### `pub enum QuoteType`
### `pub struct SeriesUpdate`
### `pub trait StreamBatchExt: Stream + Sized + Unpin`
### `pub enum StreamError`
### `pub type StreamResult<T> = std::result::Result<T, StreamError>`
### `stream_handle!`
### `pub struct TradeStreamBuilder`
### `pub struct TradeTick`
### `pub enum AlertCondition`
A predicate over incoming price ticks.
### `pub enum AlertConditionKind`
Which predicate an [`AlertCondition`] applies, without its threshold.
Deliberately **exhaustive** (no `#[non_exhaustive]`): transports that
project a condition onto a flat `kind` + `value` pair must fail to compile
when a predicate is added, rather than silently degrading it.
### `pub struct AlertEvaluator`
Evaluates [`AlertRule`]s against a price feed, tracking the per-symbol
history that crossing conditions need.
Exposed so consumers that already own a price stream (the server's shared
hub, for instance) can apply alerts without re-wrapping the stream.
### `pub struct AlertEvent`
A fired alert, carrying the tick that triggered it.
### `pub trait AlertExt: Stream<Item = PriceUpdate> + Sized + Unpin`
Adds [`alerts`](AlertExt::alerts) to every price stream.
#### Example
```no_run
use finance_query::streaming::{AlertCondition, AlertExt, AlertRule, PriceStream};
use futures::StreamExt;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut alerts = PriceStream::subscribe(["AAPL"])
.await?
.alerts([AlertRule::new("AAPL", AlertCondition::CrossesAbove(200.0))]);
while let Some(alert) = alerts.next().await {
println!("{} crossed at {}", alert.symbol, alert.price);
}
# Ok(())
# }
```
### `pub struct AlertRule`
A symbol paired with the condition that should trigger an alert.
### `pub struct AlertStream<S>`
A `Stream<Item = AlertEvent>` over any price stream.
### `pub struct Batched<S> where S: Stream,`
A stream that yields `Vec<T>` batches collected over a time window.
A batch is emitted when the window since the batch's first item elapses, or
as soon as `max_items` is reached — whichever comes first. Empty batches are
never emitted, and any partial batch is flushed when the source ends.
Boxed rather than a plain newtype so the handle stays `Unpin` — callers
`.next()` it directly, without pinning it first.
### `pub trait StreamBatchExt: Stream + Sized + Unpin`
Adds [`batched`](StreamBatchExt::batched) to every `Stream`.
#### Example
```no_run
use finance_query::streaming::{PriceStream, StreamBatchExt};
use futures::StreamExt;
use std::time::Duration;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut batches = PriceStream::subscribe(["AAPL", "NVDA", "TSLA"])
.await?
.batched(Duration::from_millis(250));
while let Some(batch) = batches.next().await {
println!("{} updates in this window", batch.len());
}
# Ok(())
# }
```
### `pub struct BookLevel`
One price level of an order book.
### `stream_handle!`
A subscription to level-2 order-book depth.
Backed by Polygon's crypto level-2 feed (`XL2`) — the one cluster that
publishes depth — so pairs are crypto pairs (`"BTC-USD"`). Requires the
`polygon` feature and the `POLYGON_API_KEY` environment variable set.
#### Example
```no_run
use finance_query::streaming::DepthStream;
use futures::StreamExt;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut books = DepthStream::subscribe(["BTC-USD"]).await?;
while let Some(book) = books.next().await {
println!("{} spread {:?}", book.symbol, book.spread());
}
# Ok(())
# }
```
### `pub struct DepthStreamBuilder`
Builder for a [`DepthStream`].
### `stream_builder!( DepthStreamBuilder, pairs = "Add crypto pairs to subscribe to." )`
Cap the number of consecutive reconnect attempts before the
stream gives up and ends (default: unlimited, i.e. retry
forever).
### `pub struct OrderBookUpdate`
A depth-of-book update: both sides, best level first.
### `pub enum PriceSource`
Which upstream backend a [`PriceStream`] connects to.
Yahoo multiplexes every asset class onto one connection; Polygon runs a
separate cluster per asset class, so its variant carries the class to use.
### `pub struct PriceStream`
A streaming price subscription that yields real-time price updates.
This provides a Flow-like API for receiving real-time price data.
Backed by a pluggable source (Yahoo by default).
#### Example
```no_run
use finance_query::streaming::PriceStream;
use futures::StreamExt;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Subscribe to multiple symbols
let mut stream = PriceStream::subscribe(["AAPL", "NVDA", "TSLA"]).await?;
// Receive price updates
while let Some(price) = stream.next().await {
println!("{}: ${:.2} ({:+.2}%)",
price.id,
price.price,
price.change_percent
);
}
# Ok(())
# }
```
### `pub struct PriceStreamBuilder`
Builder for creating price streams with custom configuration
### `pub fn max_reconnect_attempts(mut self, max: u32) -> Self`
Cap the number of consecutive reconnect attempts before the stream
gives up and ends (default: unlimited, i.e. retry forever).
### `pub enum StreamError`
Errors that can occur during streaming
### `pub type StreamResult<T> = std::result::Result<T, StreamError>`
Result type for streaming operations
### `stream_handle!`
A continuous subscription to economic-series releases.
Polls each subscribed series on an interval (15 minutes by default) and
yields a [`SeriesUpdate`] only when the latest observation is new or
revised. Requires the `fred` feature and
[`fred::init`](crate::fred::init).
#### Example
```no_run
use finance_query::streaming::EconomicStream;
use futures::StreamExt;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut stream = EconomicStream::subscribe(["FEDFUNDS", "CPIAUCSL"]).await;
while let Some(release) = stream.next().await {
println!("{} = {:?} ({})", release.series_id, release.value, release.date);
}
# Ok(())
# }
```
### `pub struct EconomicStreamBuilder`
Builder for an [`EconomicStream`] with a custom poll interval.
### `pub struct SeriesUpdate`
A newly published (or revised) observation for an economic series.
### `pub struct NewsStream`
A continuous subscription to one or more RSS/Atom sources.
Polls the configured sources on an interval (5 minutes by default,
configurable via [`NewsStreamBuilder::poll_interval`]) and yields entries
as they're first seen: an initial batch on subscribe, then only new items
on each subsequent poll. Backed by a broadcast channel, so
[`resubscribe`](Self::resubscribe) supports multiple independent
consumers of the same subscription.
#### Example
```no_run
use finance_query::streaming::NewsStream;
use finance_query::feeds::FeedSource;
use futures::StreamExt;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut stream =
NewsStream::subscribe([FeedSource::Bloomberg, FeedSource::MarketWatch]).await;
while let Some(entry) = stream.next().await {
println!("[{}] {}", entry.source, entry.title);
}
# Ok(())
# }
```
### `pub fn resubscribe(&self) -> Self`
Create a new receiver for this stream.
Useful when you need multiple consumers of the same news subscription.
### `pub struct NewsStreamBuilder`
Builder for creating a [`NewsStream`] with custom configuration.
### `pub fn poll_interval(mut self, interval: Duration) -> Self`
Set the interval between polls of all subscribed sources (default: 5 minutes).
### `pub struct Greeks`
Option greeks for a contract.
### `pub struct OptionContractUpdate`
A live update for one options contract.
Quote and trade fields arrive from the real-time WebSocket; `greeks`,
`implied_volatility` and `open_interest` come from the periodic chain
snapshot (see [`OptionsChainStreamBuilder::greeks_refresh`]) because the
real-time feed does not carry them.
### `stream_handle!`
A live subscription to one or more options chains.
Subscribe by underlying (`"AAPL"`) to follow the whole chain, or by full
OCC symbol (`"O:AAPL250117C00150000"`) to follow single contracts.
Requires the `polygon` feature and the `POLYGON_API_KEY` environment
variable set.
#### Example
```no_run
use finance_query::streaming::OptionsChainStream;
use futures::StreamExt;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut stream = OptionsChainStream::subscribe(["AAPL"]).await?;
while let Some(contract) = stream.next().await {
println!("{} {:?}/{:?}", contract.contract_symbol, contract.bid, contract.ask);
}
# Ok(())
# }
```
### `pub struct OptionsChainStreamBuilder`
Builder for an [`OptionsChainStream`].
### `pub fn greeks_refresh(mut self, interval: Option<Duration>) -> Self`
Interval between greeks/open-interest snapshot refreshes.
`None` disables them, leaving only WebSocket bid/ask/last (one REST
call per underlying per interval otherwise). Default: 60s.
### `stream_builder!( OptionsChainStreamBuilder, underlyings = "Add underlyings (or full OCC contract symbols) to follow." )`
Cap the number of consecutive reconnect attempts before the
stream gives up and ends (default: unlimited, i.e. retry
forever).
### `pub enum AssetClass`
Asset class of a Polygon real-time cluster.
Each variant is a separate upstream connection with its own channel
vocabulary and symbol format.
### `pub enum MarketHoursType`
Market hours type enumeration
### `pub enum MarketHoursTypeProto`
Protobuf enum for market hours type
### `pub enum OptionType`
Option type enumeration
### `pub struct PriceUpdate`
Real-time price update from Yahoo Finance WebSocket.
This is the user-facing struct with properly typed enum fields
that serialize to readable strings like `"EQUITY"` or `"CRYPTOCURRENCY"`.
### `pub enum QuoteType`
Quote type enumeration
### `pub enum QuoteTypeProto`
Protobuf enum for quote type
### `stream_handle!`
A subscription to every trade print for the given symbols.
Requires the `polygon` feature and the `POLYGON_API_KEY` environment
variable set.
This is a companion to [`PriceStream`](super::PriceStream), not a
replacement — most consumers want the coalesced tick.
#### Example
```no_run
use finance_query::streaming::TradeStream;
use futures::StreamExt;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut trades = TradeStream::subscribe(["AAPL"]).await?;
while let Some(trade) = trades.next().await {
println!("{} {} @ {}", trade.symbol, trade.size, trade.price);
}
# Ok(())
# }
```
### `pub struct TradeStreamBuilder`
Builder for a [`TradeStream`].
### `pub async fn build(self) -> StreamResult<TradeStream>`
Build and start the stream.
#### Errors
Returns [`StreamError::ConnectionFailed`](super::StreamError::ConnectionFailed)
when the chosen asset class has no trade feed.
### `stream_builder!(TradeStreamBuilder, symbols = "Add symbols to subscribe to.")`
Cap the number of consecutive reconnect attempts before the
stream gives up and ends (default: unlimited, i.e. retry
forever).
### `pub struct TradeTick`
A single executed trade.
### `pub async fn symbol_sentiment(symbol: &str) -> Result<crate::models::sentiment::SymbolSentiment>`
### `pub struct ClientHandle(pub(crate) Arc<YahooClient>)`
Opaque handle to a shared Yahoo Finance client session.
Allows multiple [`Ticker`] and [`Tickers`](crate::Tickers) instances to share
one authenticated session, avoiding redundant auth handshakes.
Obtain via [`Ticker::client_handle`] or [`Tickers::client_handle`](crate::Tickers::client_handle), then
pass to other builders via `.client(handle)`.
#### Example
```no_run
use finance_query::Ticker;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let aapl = Ticker::new("AAPL").await?;
let handle = aapl.client_handle();
let msft = Ticker::builder("MSFT").client(handle.clone()).build().await?;
let googl = Ticker::builder("GOOGL").client(handle).build().await?;
# Ok(())
# }
```
### `pub struct Ticker`
The primary entry point for querying financial data for a single symbol.
Data is fetched on first access and cached for 60 seconds by default.
Use the builder via [`Ticker::builder`] for custom configuration, including
[`cache`](TickerBuilder::cache) and [`no_cache`](TickerBuilder::no_cache).
### `super::macros::define_quote_accessors!`
### `pub fn builder(symbol: impl Into<String>) -> TickerBuilder`
Creates a new builder for Ticker.
### `pub async fn calendar( &self, range: TimeRange, ) -> Result<Vec<crate::models::calendar::CalendarEvent>>`
Aggregate upcoming financial events for this ticker into a single
time-sorted list.
Combines earnings, ex-dividend and dividend-payment dates with standard
monthly options expirations, plus — when the `fred` feature is enabled —
a curated set of major economic releases (CPI, NFP, GDP, …). Limited to
the forward window `[now, now + range]` and sorted ascending by
timestamp.
Options are best-effort: a symbol with no listed options contributes no
expiration events rather than failing the call.
### `pub fn client_handle(&self) -> ClientHandle`
Returns a handle to the underlying Yahoo Finance session.
Pass to other builders via `.client(handle)` to share the authenticated
session without a new auth handshake.
#### Panics
Panics if this ticker was created via [`Providers`](crate::Providers) with
no Yahoo provider configured. For session sharing across multiple tickers,
prefer [`Providers::ticker`](crate::Providers::ticker) instead.
### `pub async fn dividend_analytics(&self, range: TimeRange) -> Result<DividendAnalytics>`
Compute dividend analytics for the requested time range.
### `pub async fn edgar_company_facts(&self) -> Result<CompanyFacts>`
Get SEC EDGAR company facts (structured XBRL financial data).
Always uses EDGAR directly — XBRL `us-gaap`/`ifrs`/`dei` fact data is unique
to the SEC's EDGAR API. For routable filing data use [`filings`](Self::filings).
### `pub async fn edgar_submissions(&self) -> Result<EdgarSubmissions>`
Get SEC EDGAR filing history for this symbol.
Always uses EDGAR directly — this is an EDGAR-specific API (CIK-based submission
history and XBRL company facts) that no other provider replicates. For routable
provider-agnostic filing data use [`filings`](Self::filings) instead.
### `pub async fn filings(&self) -> Result<ProviderFilings>`
Fetch SEC filings via the configured [`Capability::FILINGS`] provider.
Routes through the provider system; EDGAR is always available as a fallback
(auto-injected when no explicit FILINGS route is set). To prefer Polygon:
`.route(Capability::FILINGS, [Provider::Polygon, Provider::Edgar])`.
For the full EDGAR submissions response or structured XBRL data, use
[`edgar_submissions`](Self::edgar_submissions) / [`edgar_company_facts`](Self::edgar_company_facts).
### `pub async fn financials( &self, stmt_type: StatementType, frequency: Frequency, ) -> Result<FinancialStatement>`
Get financial statements.
### `pub async fn news(&self) -> Result<Vec<News>>`
Get news articles for this symbol.
### `super::macros::define_quote_accessors!`
Regular, pre- and post-market price, plus the day's range and volume.
### `pub async fn quote<F>(&self) -> Result<Quote<F>> where F: Format, Quote<Both>: Into<Quote<F>>,`
Get full quote data, optionally including logo URLs.
### `pub async fn rating_consensus(&self) -> Result<crate::models::fundamentals::RatingConsensus>`
Fetch the aggregated analyst rating consensus (grade distribution plus a
headline label) via the configured [`Capability::FUNDAMENTALS`] provider
(currently FMP only). Distinct from
[`recommendations`](Self::recommendations), which returns similar symbols.
### `pub async fn recommendations(&self, limit: u32) -> Result<Recommendation>`
Get analyst recommendations and similar symbols.
### `pub async fn risk( &self, interval: Interval, range: TimeRange, benchmark: Option<&str>, ) -> Result<risk::RiskSummary>`
Compute a risk summary for this symbol.
### `pub struct TickerBuilder`
Builder for constructing a [`Ticker`] with optional configuration.
Construct via [`Ticker::builder`]. All builder methods are optional;
call [`build`](TickerBuilder::build) to finalize.
### `pub async fn build(self) -> Result<Ticker>`
Build the Ticker instance.
### `pub fn cache(mut self, ttl: Duration) -> Self`
Cache responses for `ttl` instead of the default 60 seconds.
### `pub fn no_cache(mut self) -> Self`
Disable caching — every call fetches fresh data.
By default a `Ticker` caches each response for 60 seconds, so
repeated accessor calls within that window reuse one fetch.
### `define_batch_response!`
Response containing capital gains for multiple symbols.
### `define_batch_response!`
Response containing charts for multiple symbols.
### `define_batch_response!`
Response containing dividends for multiple symbols.
### `define_batch_response!`
Response containing financial statements for multiple symbols.
### `define_batch_response!`
Response containing technical indicators for multiple symbols.
### `define_batch_response!`
Response containing news articles for multiple symbols.
### `define_batch_response!`
Response containing options chains for multiple symbols.
### `define_batch_response!`
Response containing quotes for multiple symbols.
### `define_batch_response!`
Response containing recommendations for multiple symbols.
### `define_batch_response!`
Response containing spark data for multiple symbols.
Spark data is optimized for sparkline rendering with only close prices.
Unlike charts, spark data is fetched in a single batch request.
### `define_batch_response!`
Response containing splits for multiple symbols.
### `pub struct Tickers`
Multi-symbol ticker for efficient batch operations.
`Tickers` optimizes data fetching for multiple symbols by:
- Using batch endpoints where available (e.g., /v7/finance/quote)
- Fetching concurrently when batch endpoints don't exist
- Sharing a single authenticated client across all symbols
- Caching results per symbol
#### Example
```no_run
use finance_query::Tickers;
# async fn example() -> Result<(), Box<dyn std::error::Error>> {
// Create tickers for multiple symbols
let tickers = Tickers::new(["AAPL", "MSFT", "GOOGL"]).await?;
// Batch fetch all quotes (single API call)
let quotes = tickers.quotes().await?;
for (symbol, quote) in "es.quotes {
let price = quote.regular_market_price.as_ref().and_then(|v| v.raw).unwrap_or(0.0);
println!("{}: ${:.2}", symbol, price);
}
// Fetch charts concurrently
use finance_query::{Interval, TimeRange};
let charts = tickers.charts(Interval::OneDay, TimeRange::OneMonth).await?;
# Ok(())
# }
```
### `pub fn builder<S, I>(symbols: I) -> TickersBuilder where S: Into<String>, I: IntoIterator<Item = S>,`
Creates a new builder for Tickers
### `pub async fn charts( &self, interval: Interval, range: TimeRange, ) -> Result<BatchChartsResponse>`
Batch fetch charts for all symbols concurrently
Chart data cannot be batched in a single request, so this fetches
all charts concurrently using tokio for maximum performance.
### `pub fn client_handle(&self) -> ClientHandle`
Returns a handle to the underlying Yahoo Finance session.
Pass to [`Ticker::builder`](crate::Ticker::builder) or other
[`Tickers::builder`] calls via `.client(handle)` to share the
authenticated session without a new auth handshake.
#### Panics
Panics if these tickers were created via [`Providers`](crate::Providers) with
no Yahoo provider configured. For session sharing across multiple tickers,
prefer [`Providers::tickers`](crate::Providers::tickers) instead.
### `pub struct TickersBuilder`
Builder for Tickers
### `pub fn logo(mut self) -> Self`
Include company logo URLs in quote responses.
When enabled, `quotes()` will fetch logo URLs in parallel with the
quote batch request, adding a small extra request.
### `pub struct Lang`
### `pub trait Translatable`
### `pub trait TranslationBackend: Send + Sync`
### `pub trait TranslationBackend: Send + Sync`
A machine-translation backend for free-form text.
Implement this to plug a custom engine (e.g. a hosted translation API)
into the translation pipeline via [`set_backend`](super::set_backend).
The built-in offline backend (feature `translation-offline`) is used by
default when no custom backend is registered.
Inputs are English; implementations must return one translated string per
input, preserving order. Inputs may contain multiple sentences.
### `pub fn set_backend(backend: Arc<dyn TranslationBackend>)`
Register a custom translation backend for the whole process.
Takes precedence over the built-in offline backend. Free-form text fields
are left untranslated when no backend is available (built-in dictionary
terms are still translated).
### `pub struct Lang`
A parsed, normalized target language for translation.
Accepts BCP 47 language tags (e.g. `"ja"`, `"de-DE"`, `"zh-Hans"`, `"pt_BR"`).
Underscores are accepted as subtag separators for convenience.
### `pub fn set_backend(backend: Arc<dyn TranslationBackend>)`
**Measured:** 244 instructions/iter, 18ns median, 1 allocs/iter
### `pub trait Translatable`
A response type whose human-readable text fields can be translated.
The default implementation visits nothing, so types without
natural-language content implement this trait as a no-op marker.
`visit_translatable` must visit the same fields in the same order on
every call for an unmodified value: the translation pipeline performs one
pass to collect texts and a second pass to write translations back.
### `pub async fn translate<T: Translatable + ?Sized>(value: &mut T, lang: &str) -> Result<()>`
Translate the human-readable text fields of a value in place.
`lang` is a BCP 47 language tag (e.g. `"ja"`, `"de-DE"`, `"zh-Hant"`).
English targets are a no-op. Returns an error for structurally invalid
tags or when the machine-translation backend fails; fields not covered
by the dictionary are left in English when no backend is available.
**Measured:** 53176 instructions/iter, 3488ns median, 79 allocs/iter
### `pub async fn translate_texts<S, I>(texts: I, lang: &Lang) -> Result<Vec<String>> where S: Into<String>, I: IntoIterator<Item = S>,`
Translate a batch of raw English texts, preserving order.
Applies the dictionary, the process-wide memo cache, and the active
machine-translation backend in that order. Texts without a dictionary
hit are returned unchanged when no backend is available.
**Measured:** 19222 instructions/iter, 1877ns median, 49 allocs/iter
### `pub async fn translate_with<T: Translatable + ?Sized>(value: &mut T, lang: &Lang) -> Result<()>`
Like [`translate`], with an already-parsed [`Lang`].
**Measured:** 52349 instructions/iter, 3340ns median, 77 allocs/iter