fmp-node-api
Version:
A comprehensive Node.js wrapper for Financial Modeling Prep API
1,064 lines (1,058 loc) • 133 kB
text/typescript
import { F as FMPConfig, A as APIResponse } from './common-COsxpVBY.mjs';
export { P as PeriodParams, S as SymbolParams } from './common-COsxpVBY.mjs';
import { M as MarketCap, S as StockSplitResponse, a as StockDividendResponse, b as StockRealTimePrice, c as StockRealTimePriceFull, I as IncomeStatement, B as BalanceSheet, C as CashFlowStatement, K as KeyMetrics, F as FinancialRatios, E as EnterpriseValue, d as CashflowGrowth, e as IncomeGrowth, f as BalanceSheetGrowth, g as FinancialGrowth, h as EarningsHistorical, i as EarningsSurprises, j as ETFHoldingDates, k as ETFHolding, l as ETFHolder, m as ETFProfile, n as ETFWeighting, o as ETFCountryWeighting, p as ETFStockExposure, T as TreasuryRate, q as EconomicIndicator, r as MarketHours, s as MarketPerformance, t as MarketSectorPerformance, u as MarketIndex, v as StockList, w as ETFList, x as CryptoList, y as ForexList, A as AvailableIndexesList, z as EarningsCalendar, D as EarningsConfirmed, G as DividendsCalendar, H as EconomicsCalendar, J as IPOCalendar, L as SplitsCalendar, N as CompanyProfile, O as ExecutiveCompensation, P as CompanyNotes, Q as HistoricalEmployeeCount, R as SharesFloat, U as HistoricalSharesFloat, V as EarningsCallTranscript, W as CompanyTranscriptData, X as Quote, Y as HistoricalPriceResponse, Z as HistoricalPriceData, _ as SenateTradingResponse, $ as SenateHouseTradingByNameResponse, a0 as HouseTradingResponse, a1 as Form13FResponse, a2 as InstitutionalHolderResponse, a3 as InsiderTradingRSSResponse, a4 as InsiderTradingSearchResponse, a5 as TransactionTypesResponse, a6 as InsidersBySymbolResponse, a7 as InsiderTradeStatisticsResponse, a8 as CikMapperResponse, a9 as CikMapperBySymbolResponse, aa as BeneficialOwnershipResponse, ab as FailToDeliverResponse, ac as TransactionType, ad as RSSFeedItem, ae as RSSFeedAllItem, af as RSSFeedV3Item, ag as RSSFeed8KItem, ah as SECFiling, ai as IndustryClassification, aj as IndustryClassificationCode, ak as MutualFundHolding } from './types-only-BhmQjuTn.mjs';
export { ao as EconomicIndicatorName, an as MarketHoliday, am as StockDividend, al as StockSplit } from './types-only-BhmQjuTn.mjs';
export { FMPValidation } from './utils/validation.mjs';
declare class FMPClient {
private v3Client;
private v4Client;
private stableClient;
private apiKey;
constructor(config: FMPConfig);
/**
* Standard get method - returns raw API response
*
* For endpoints that return arrays, this will always return an array (possibly empty) for `data` when success is true.
* For endpoints that return objects, data is returned as-is.
*/
get<T>(endpoint: string, version?: 'v3' | 'v4' | 'stable', params?: Record<string, any>): Promise<APIResponse<T>>;
/**
* Get method for single-object endpoints - unwraps single-item arrays
*
* For endpoints that return single objects, this will always return an object (possibly empty) for `data` when success is true.
*/
getSingle<T>(endpoint: string, version?: 'v3' | 'v4' | 'stable', params?: Record<string, any>): Promise<APIResponse<T>>;
private getClientForVersion;
}
declare class StockEndpoints {
private client;
constructor(client: FMPClient);
/**
* Get current market capitalization for a stock
*
* Market capitalization represents the total value of a company's outstanding shares.
* Calculated by multiplying the current share price by the number of outstanding shares.
* This metric is crucial for understanding a company's size and market position.
*
* @param symbol - The stock symbol to get market cap for (e.g., 'AAPL', 'MSFT', 'GOOGL')
*
* @returns Promise resolving to market cap data including symbol, date, and market cap value
*
* @example
* ```typescript
* // Get market cap for Apple
* const marketCap = await fmp.stock.getMarketCap('AAPL');
* console.log(`Apple's market cap: $${marketCap.data.marketCap.toLocaleString()}`);
*
* // Get market cap for Microsoft
* const msftCap = await fmp.stock.getMarketCap('MSFT');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#market-cap-company-information|FMP Market Cap Documentation}
*/
getMarketCap(symbol: string): Promise<APIResponse<MarketCap>>;
/**
* Get historical stock splits for a company
*
* Stock splits occur when a company increases the number of shares by dividing existing shares.
* This endpoint provides the complete history of stock splits including dates, ratios, and split types.
* Useful for adjusting historical price data and understanding corporate actions.
*
* @param symbol - The stock symbol to get split history for (e.g., 'AAPL', 'TSLA', 'NVDA')
*
* @returns Promise resolving to historical stock splits with dates, labels, and split ratios
*
* @example
* ```typescript
* // Get Apple's split history
* const splits = await fmp.stock.getStockSplits('AAPL');
* splits.data.historical.forEach(split => {
* console.log(`${split.date}: ${split.numerator}:${split.denominator} split`);
* });
*
* // Get Tesla's split history
* const teslaSplits = await fmp.stock.getStockSplits('TSLA');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#splits-historical-splits|FMP Stock Splits Documentation}
*/
getStockSplits(symbol: string): Promise<APIResponse<StockSplitResponse>>;
/**
* Get historical dividend payments for a stock
*
* Dividends are periodic payments made by companies to shareholders from profits.
* This endpoint provides the complete dividend history including payment dates, amounts,
* and important dates like ex-dividend, record, and declaration dates.
*
* @param symbol - The stock symbol to get dividend history for (e.g., 'KO', 'JNJ', 'PG')
*
* @returns Promise resolving to dividend history with payment details and important dates
*
* @example
* ```typescript
* // Get Coca-Cola's dividend history
* const dividends = await fmp.stock.getDividendHistory('KO');
* dividends.data.historical.forEach(dividend => {
* console.log(`${dividend.date}: $${dividend.dividend} per share`);
* });
*
* // Get Johnson & Johnson's dividend history
* const jnjDividends = await fmp.stock.getDividendHistory('JNJ');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#dividends-historical-dividends|FMP Dividends Documentation}
*/
getDividendHistory(symbol: string): Promise<APIResponse<StockDividendResponse>>;
/**
* Get real-time stock prices for multiple symbols
*
* Provides current market prices for stocks with minimal data overhead.
* Returns basic price information including symbol and current price.
* Ideal for quick price checks and portfolio monitoring.
*
* @param symbols - Array of stock symbols to get real-time prices for
*
* @returns Promise resolving to array of real-time price data with symbol and price
*
* @example
* ```typescript
* // Get prices for multiple tech stocks
* const prices = await fmp.stock.getRealTimePrice([
* 'AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA'
* ]);
*
* prices.data.forEach(stock => {
* console.log(`${stock.symbol}: $${stock.price}`);
* });
*
* // Get price for single stock
* const aaplPrice = await fmp.stock.getRealTimePrice(['AAPL']);
* ```
*/
getRealTimePrice(symbols: string[]): Promise<APIResponse<StockRealTimePrice[]>>;
/**
* Get comprehensive real-time stock data for multiple symbols
*
* Provides detailed real-time market data including bid/ask prices, volume, trade sizes,
* and timestamps. This endpoint offers much more information than the basic real-time price.
* Perfect for trading applications, market analysis, and detailed price monitoring.
*
* @param symbols - Array of stock symbols to get detailed real-time data for
*
* @returns Promise resolving to array of detailed real-time data including bid/ask, volume, and timestamps
*
* @example
* ```typescript
* // Get detailed data for multiple stocks
* const detailedData = await fmp.stock.getRealTimePriceForMultipleStocks([
* 'AAPL', 'MSFT', 'GOOGL'
* ]);
*
* detailedData.data.forEach(stock => {
* console.log(`${stock.symbol}:`);
* console.log(` Bid: $${stock.bidPrice} (${stock.bidSize} shares)`);
* console.log(` Ask: $${stock.askPrice} (${stock.askSize} shares)`);
* console.log(` Last: $${stock.lastSalePrice} (${stock.lastSaleSize} shares)`);
* console.log(` Volume: ${stock.volume.toLocaleString()}`);
* });
*
* // Get detailed data for single stock
* const aaplDetailed = await fmp.stock.getRealTimePriceForMultipleStocks(['AAPL']);
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#real-time-full-price-quote|FMP Real-Time Full Price Documentation}
*/
getRealTimePriceForMultipleStocks(symbols: string[]): Promise<APIResponse<StockRealTimePriceFull[]>>;
}
declare class FinancialEndpoints {
private client;
constructor(client: FMPClient);
/**
* Get income statement data
*
* Provides comprehensive income statement data including revenue, expenses,
* net income, and earnings per share. Essential for analyzing company
* profitability, revenue trends, and financial performance over time.
*
* @param params - Income statement request parameters
* @param params.symbol - The stock symbol to get income statement for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of income statement data with financial metrics
*
* @example
* ```typescript
* // Get annual income statements for Apple
* const incomeStatements = await fmp.financial.getIncomeStatement({ symbol: 'AAPL' });
* incomeStatements.data.forEach(statement => {
* console.log(`${statement.date}: Revenue $${statement.revenue.toLocaleString()}, Net Income $${statement.netIncome.toLocaleString()}`);
* });
*
* // Get quarterly income statements for Microsoft
* const quarterlyIncome = await fmp.financial.getIncomeStatement({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#income-statements-financial-statements|FMP Income Statement Documentation}
*/
getIncomeStatement(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<IncomeStatement[]>>;
/**
* Get balance sheet data
*
* Provides comprehensive balance sheet data including assets, liabilities,
* and shareholder equity. Essential for analyzing company financial position,
* liquidity, and capital structure.
*
* @param params - Balance sheet request parameters
* @param params.symbol - The stock symbol to get balance sheet for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of balance sheet data with financial position metrics
*
* @example
* ```typescript
* // Get annual balance sheets for Apple
* const balanceSheets = await fmp.financial.getBalanceSheet({ symbol: 'AAPL' });
* balanceSheets.data.forEach(sheet => {
* console.log(`${sheet.date}: Assets $${sheet.totalAssets.toLocaleString()}, Equity $${sheet.totalStockholdersEquity.toLocaleString()}`);
* });
*
* // Get quarterly balance sheets for Microsoft
* const quarterlyBalance = await fmp.financial.getBalanceSheet({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#balance-sheet-statements-financial-statements|FMP Balance Sheet Documentation}
*/
getBalanceSheet(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<BalanceSheet[]>>;
/**
* Get cash flow statement data
*
* Provides comprehensive cash flow data including operating, investing,
* and financing cash flows. Essential for analyzing company cash generation,
* capital allocation, and financial sustainability.
*
* @param params - Cash flow statement request parameters
* @param params.symbol - The stock symbol to get cash flow statement for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of cash flow statement data with cash flow metrics
*
* @example
* ```typescript
* // Get annual cash flow statements for Apple
* const cashFlows = await fmp.financial.getCashFlowStatement({ symbol: 'AAPL' });
* cashFlows.data.forEach(flow => {
* console.log(`${flow.date}: Operating CF $${flow.operatingCashFlow.toLocaleString()}, Free CF $${flow.freeCashFlow.toLocaleString()}`);
* });
*
* // Get quarterly cash flow statements for Microsoft
* const quarterlyCashFlow = await fmp.financial.getCashFlowStatement({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#cashflow-statements-financial-statements|FMP Cash Flow Statement Documentation}
*/
getCashFlowStatement(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<CashFlowStatement[]>>;
/**
* Get key financial metrics
*
* Provides essential financial metrics including revenue, net income,
* P/E ratio, and other key performance indicators. Essential for
* fundamental analysis and company valuation.
*
* @param params - Key metrics request parameters
* @param params.symbol - The stock symbol to get key metrics for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of key metrics data with financial indicators
*
* @example
* ```typescript
* // Get key metrics for Apple
* const keyMetrics = await fmp.financial.getKeyMetrics({ symbol: 'AAPL' });
* keyMetrics.data.forEach(metric => {
* console.log(`${metric.date}: P/E ${metric.peRatio}, ROE ${metric.roe}%`);
* });
*
* // Get quarterly key metrics for Microsoft
* const quarterlyMetrics = await fmp.financial.getKeyMetrics({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#key-metrics-statement-analysis|FMP Key Metrics Documentation}
*/
getKeyMetrics(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<KeyMetrics[]>>;
/**
* Get financial ratios
*
* Provides comprehensive financial ratios including P/B ratio, ROE,
* debt-to-equity, and other important ratios. Essential for analyzing
* company financial health and comparing with peers.
*
* @param params - Financial ratios request parameters
* @param params.symbol - The stock symbol to get financial ratios for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of financial ratios data with ratio metrics
*
* @example
* ```typescript
* // Get financial ratios for Apple
* const ratios = await fmp.financial.getFinancialRatios({ symbol: 'AAPL' });
* ratios.data.forEach(ratio => {
* console.log(`${ratio.date}: P/B ${ratio.priceToBookRatio}, Debt/Equity ${ratio.debtToEquity}`);
* });
*
* // Get quarterly ratios for Microsoft
* const quarterlyRatios = await fmp.financial.getFinancialRatios({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#ratios-statement-analysis|FMP Financial Ratios Documentation}
*/
getFinancialRatios(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<FinancialRatios[]>>;
/**
* Get enterprise value data
*
* Provides enterprise value metrics including total enterprise value,
* market cap, and debt information. Essential for company valuation
* and comparing companies with different capital structures.
*
* @param params - Enterprise value request parameters
* @param params.symbol - The stock symbol to get enterprise value for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of enterprise value data with valuation metrics
*
* @example
* ```typescript
* // Get enterprise value for Apple
* const enterpriseValue = await fmp.financial.getEnterpriseValue({ symbol: 'AAPL' });
* enterpriseValue.data.forEach(ev => {
* console.log(`${ev.date}: EV $${ev.enterpriseValue.toLocaleString()}, Market Cap $${ev.marketCapitalization.toLocaleString()}`);
* });
*
* // Get quarterly enterprise value for Microsoft
* const quarterlyEV = await fmp.financial.getEnterpriseValue({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#enterprise-values-statement-analysis|FMP Enterprise Value Documentation}
*/
getEnterpriseValue(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<EnterpriseValue[]>>;
/**
* Get cash flow growth data
*
* Provides cash flow growth rates showing how quickly a company's
* cash flows are growing over time. Essential for analyzing cash
* generation trends and financial sustainability.
*
* @param params - Cash flow growth request parameters
* @param params.symbol - The stock symbol to get cash flow growth for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of cash flow growth data with growth metrics
*
* @example
* ```typescript
* // Get cash flow growth for Apple
* const cashFlowGrowth = await fmp.financial.getCashflowGrowth({ symbol: 'AAPL' });
* cashFlowGrowth.data.forEach(growth => {
* console.log(`${growth.date}: Operating CF Growth ${growth.operatingCashFlowGrowth}%`);
* });
*
* // Get quarterly cash flow growth for Microsoft
* const quarterlyGrowth = await fmp.financial.getCashflowGrowth({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#cashflow-growth-statement-analysis|FMP Cash Flow Growth Documentation}
*/
getCashflowGrowth(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<CashflowGrowth[]>>;
/**
* Get income growth data
*
* Provides income growth rates showing how quickly a company's
* revenue and net income are growing over time. Essential for
* analyzing profitability trends and business momentum.
*
* @param params - Income growth request parameters
* @param params.symbol - The stock symbol to get income growth for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of income growth data with growth metrics
*
* @example
* ```typescript
* // Get income growth for Apple
* const incomeGrowth = await fmp.financial.getIncomeGrowth({ symbol: 'AAPL' });
* incomeGrowth.data.forEach(growth => {
* console.log(`${growth.date}: Revenue Growth ${growth.revenueGrowth}%, Net Income Growth ${growth.netIncomeGrowth}%`);
* });
*
* // Get quarterly income growth for Microsoft
* const quarterlyGrowth = await fmp.financial.getIncomeGrowth({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#income-growth-statement-analysis|FMP Income Growth Documentation}
*/
getIncomeGrowth(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<IncomeGrowth[]>>;
/**
* Get balance sheet growth data
*
* Provides balance sheet growth rates showing how quickly a company's
* assets, liabilities, and equity are growing over time. Essential for
* analyzing capital structure trends and financial position changes.
*
* @param params - Balance sheet growth request parameters
* @param params.symbol - The stock symbol to get balance sheet growth for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of balance sheet growth data with growth metrics
*
* @example
* ```typescript
* // Get balance sheet growth for Apple
* const balanceSheetGrowth = await fmp.financial.getBalanceSheetGrowth({ symbol: 'AAPL' });
* balanceSheetGrowth.data.forEach(growth => {
* console.log(`${growth.date}: Assets Growth ${growth.totalAssetsGrowth}%, Equity Growth ${growth.totalStockholdersEquityGrowth}%`);
* });
*
* // Get quarterly balance sheet growth for Microsoft
* const quarterlyGrowth = await fmp.financial.getBalanceSheetGrowth({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#balance-sheet-growth-statement-analysis|FMP Balance Sheet Growth Documentation}
*/
getBalanceSheetGrowth(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<BalanceSheetGrowth[]>>;
/**
* Get financial growth data
*
* Provides comprehensive financial growth rates across all key
* financial metrics. Essential for analyzing overall financial
* performance trends and business momentum.
*
* @param params - Financial growth request parameters
* @param params.symbol - The stock symbol to get financial growth for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.period - The reporting period: 'annual' or 'quarter' (default: 'annual')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of financial growth data with comprehensive growth metrics
*
* @example
* ```typescript
* // Get financial growth for Apple
* const financialGrowth = await fmp.financial.getFinancialGrowth({ symbol: 'AAPL' });
* financialGrowth.data.forEach(growth => {
* console.log(`${growth.date}: Revenue Growth ${growth.revenueGrowth}%, EPS Growth ${growth.epsGrowth}%`);
* });
*
* // Get quarterly financial growth for Microsoft
* const quarterlyGrowth = await fmp.financial.getFinancialGrowth({ symbol: 'MSFT', period: 'quarter', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#financial-growth-statement-analysis|FMP Financial Growth Documentation}
*/
getFinancialGrowth(params: {
symbol: string;
period?: 'annual' | 'quarter';
limit?: number;
}): Promise<APIResponse<FinancialGrowth[]>>;
/**
* Get historical earnings data
*
* Provides historical and upcoming earnings announcements including
* dates, estimated EPS, and actual EPS. Essential for analyzing
* earnings trends and tracking company performance.
*
* @param params - Earnings historical request parameters
* @param params.symbol - The stock symbol to get earnings history for (e.g., 'AAPL', 'MSFT', 'GOOGL')
* @param params.limit - Number of periods to retrieve (default: 5)
*
* @returns Promise resolving to array of historical earnings data with announcement details
*
* @example
* ```typescript
* // Get earnings history for Apple
* const earningsHistory = await fmp.financial.getEarningsHistorical({ symbol: 'AAPL', limit: 10 });
* earningsHistory.data.forEach(earning => {
* console.log(`${earning.date}: Est. ${earning.estimatedEps}, Actual ${earning.actualEps}`);
* });
*
* // Get earnings history for Microsoft
* const msftEarnings = await fmp.financial.getEarningsHistorical({ symbol: 'MSFT', limit: 8 });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#earnings-historical-earnings|FMP Earnings Historical Documentation}
*/
getEarningsHistorical(params: {
symbol: string;
limit?: number;
}): Promise<APIResponse<EarningsHistorical[]>>;
/**
* Get earnings surprises data
*
* Provides earnings announcements that exceeded or fell short of
* analyst estimates. Essential for analyzing earnings quality and
* market reactions to earnings releases.
*
* @param symbol - The stock symbol to get earnings surprises for (e.g., 'AAPL', 'MSFT', 'GOOGL')
*
* @returns Promise resolving to array of earnings surprises data with surprise details
*
* @example
* ```typescript
* // Get earnings surprises for Apple
* const earningsSurprises = await fmp.financial.getEarningsSurprises('AAPL');
* earningsSurprises.data.forEach(surprise => {
* console.log(`${surprise.date}: Est. ${surprise.estimatedEps}, Actual ${surprise.actualEps}, Surprise ${surprise.surprisePercentage}%`);
* });
*
* // Get earnings surprises for Microsoft
* const msftSurprises = await fmp.financial.getEarningsSurprises('MSFT');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#earnings-surprises-earnings|FMP Earnings Surprises Documentation}
*/
getEarningsSurprises(symbol: string): Promise<APIResponse<EarningsSurprises[]>>;
}
declare class ETFEndpoints {
private client;
constructor(client: FMPClient);
/**
* Get available ETF holding dates
*
* Provides a list of dates when ETF holdings are updated and available.
* Useful for determining when the most recent holdings data is available
* and ensuring you're working with current portfolio information.
*
* @param symbol - ETF symbol to get holding dates for (e.g., 'SPY', 'VOO', 'QQQ')
*
* @returns Promise resolving to array of available holding dates
*
* @example
* ```typescript
* // Get holding dates for specific ETF
* const spyDates = await fmp.etf.getHoldingDates('SPY');
* spyDates.data.forEach(date => {
* console.log(`Holdings available: ${date.date}`);
* });
*
* // Get VOO holding dates
* const vooDates = await fmp.etf.getHoldingDates('VOO');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#etf-holding-dates-etf-holdings|FMP ETF Holding Dates Documentation}
*/
getHoldingDates(symbol: string): Promise<APIResponse<ETFHoldingDates[]>>;
/**
* Get ETF holdings for specific date
*
* Provides detailed holdings information for an ETF on a specific date.
* Includes individual stocks, their weights, shares held, and market values.
* Essential for understanding ETF composition and portfolio analysis.
*
* @param params - ETF holdings request parameters
* @param params.symbol - The ETF symbol to get holdings for (e.g., 'SPY', 'VOO', 'QQQ')
* @param params.date - The date to get holdings for in YYYY-MM-DD format
*
* @returns Promise resolving to array of ETF holdings with detailed stock information
*
* @example
* ```typescript
* // Get SPY holdings for specific date
* const holdings = await fmp.etf.getHoldings({ symbol: 'SPY', date: '2024-01-15' });
* holdings.data.forEach(holding => {
* console.log(`${holding.asset}: ${holding.weight}% (${holding.sharesNumber} shares)`);
* });
*
* // Get VOO holdings
* const vooHoldings = await fmp.etf.getHoldings({ symbol: 'VOO', date: '2024-01-15' });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#etf-holdings-etf-holdings|FMP ETF Holdings Documentation}
*/
getHoldings(params: {
symbol: string;
date: string;
}): Promise<APIResponse<ETFHolding[]>>;
/**
* Get ETF holdings and components
*
* Provides all stocks held by a specific ETF including assets, share numbers,
* and weight percentages. Essential for understanding ETF composition and
* finding which ETFs hold specific stocks.
*
* @param symbol - The ETF symbol to get holdings for (e.g., 'SPY', 'VOO', 'QQQ')
*
* @returns Promise resolving to array of ETF holdings with stock details
*
* @example
* ```typescript
* // Get SPY holdings
* const spyHoldings = await fmp.etf.getHolder('SPY');
* spyHoldings.data.forEach(holding => {
* console.log(`${holding.asset}: ${holding.weight}% (${holding.sharesNumber} shares)`);
* });
*
* // Get VOO holdings
* const vooHoldings = await fmp.etf.getHolder('VOO');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#etf-holder-etf-holdings|FMP ETF Holder Documentation}
*/
getHolder(symbol: string): Promise<APIResponse<ETFHolder[]>>;
/**
* Get ETF profile and information
*
* Provides comprehensive information about an ETF including ticker symbol,
* name, expense ratio, assets under management, and other key metrics.
* Essential for ETF comparison and due diligence.
*
* @param symbol - ETF symbol to get profile for (e.g., 'SPY', 'VOO', 'QQQ')
*
* @returns Promise resolving to ETF profile with detailed information
*
* @example
* ```typescript
* // Get SPY profile
* const spyProfile = await fmp.etf.getProfile('SPY');
* console.log(`SPY AUM: $${spyProfile.data.aum.toLocaleString()}`);
* console.log(`Expense Ratio: ${spyProfile.data.expenseRatio}%`);
*
* // Get VOO profile
* const vooProfile = await fmp.etf.getProfile('VOO');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#etf-information-etf-holdings|FMP ETF Information Documentation}
*/
getProfile(symbol: string): Promise<APIResponse<ETFProfile>>;
/**
* Get ETF sector weighting and exposure
*
* Provides a breakdown of an ETF's sector allocation showing the percentage
* of assets invested in each sector. Essential for understanding sector
* exposure and diversification analysis.
*
* @param symbol - The ETF symbol to get sector weighting for (e.g., 'SPY', 'VOO', 'QQQ')
*
* @returns Promise resolving to array of sector weightings with percentage allocations
*
* @example
* ```typescript
* // Get SPY sector weightings
* const sectorWeightings = await fmp.etf.getSectorWeighting('SPY');
* sectorWeightings.data.forEach(sector => {
* console.log(`${sector.sector}: ${sector.weight}%`);
* });
*
* // Get QQQ sector exposure (tech-heavy)
* const qqqSectors = await fmp.etf.getSectorWeighting('QQQ');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#etf-sector-weighting-etf-holdings|FMP ETF Sector Weighting Documentation}
*/
getSectorWeighting(symbol: string): Promise<APIResponse<ETFWeighting[]>>;
/**
* Get ETF country weighting and exposure
*
* Provides a breakdown of an ETF's geographic allocation showing the percentage
* of assets invested in each country. Essential for understanding international
* exposure and geographic diversification.
*
* @param symbol - The ETF symbol to get country weighting for (e.g., 'SPY', 'VOO', 'EFA')
*
* @returns Promise resolving to array of country weightings with percentage allocations
*
* @example
* ```typescript
* // Get SPY country weightings
* const countryWeightings = await fmp.etf.getCountryWeighting('SPY');
* countryWeightings.data.forEach(country => {
* console.log(`${country.country}: ${country.weight}%`);
* });
*
* // Get international ETF exposure
* const efaCountries = await fmp.etf.getCountryWeighting('EFA');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#etf-country-weighting-etf-holdings|FMP ETF Country Weighting Documentation}
*/
getCountryWeighting(symbol: string): Promise<APIResponse<ETFCountryWeighting[]>>;
/**
* Get ETF stock exposure and holdings
*
* Provides detailed exposure information for a specific stock across all ETFs
* that hold it. Includes market value, share numbers, and weight percentages.
* Useful for finding which ETFs have exposure to specific stocks.
*
* @param symbol - The stock symbol to get ETF exposure for (e.g., 'AAPL', 'MSFT', 'GOOGL')
*
* @returns Promise resolving to array of ETF exposures with detailed holding information
*
* @example
* ```typescript
* // Find ETFs that hold Apple
* const appleExposure = await fmp.etf.getStockExposure('AAPL');
* appleExposure.data.forEach(etf => {
* console.log(`${etf.etfSymbol}: ${etf.weight}% (${etf.sharesNumber} shares)`);
* });
*
* // Find ETFs that hold Microsoft
* const msftExposure = await fmp.etf.getStockExposure('MSFT');
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#etf-sector-exposure-etf-holdings|FMP ETF Stock Exposure Documentation}
*/
getStockExposure(symbol: string): Promise<APIResponse<ETFStockExposure[]>>;
}
declare class EconomicEndpoints {
private client;
constructor(client: FMPClient);
/**
* Get treasury rates data
*
* Provides historical treasury rates for various maturities including
* 1-month, 3-month, 6-month, 1-year, 2-year, 3-year, 5-year, 7-year,
* 10-year, 20-year, and 30-year treasury bonds. Essential for analyzing
* interest rate trends, yield curves, and fixed income investments.
*
* @param params - Treasury rates request parameters
* @param params.from - Start date in YYYY-MM-DD format (optional, defaults to 1 year ago)
* @param params.to - End date in YYYY-MM-DD format (optional, defaults to today)
*
* @returns Promise resolving to array of treasury rates data with yield information
*
* @example
* ```typescript
* // Get treasury rates for the last year
* const treasuryRates = await fmp.economic.getTreasuryRates({
* from: '2023-01-01',
* to: '2023-12-31'
* });
* treasuryRates.data.forEach(rate => {
* console.log(`${rate.date}: 10Y ${rate.tenY}%, 2Y ${rate.twoY}%`);
* });
*
* // Get recent treasury rates
* const recentRates = await fmp.economic.getTreasuryRates({
* from: '2024-01-01'
* });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#treasury-rates-economics-data|FMP Treasury Rates Documentation}
*/
getTreasuryRates(params: {
from?: string;
to?: string;
}): Promise<APIResponse<TreasuryRate[]>>;
/**
* Get economic indicators data
*
* Provides real-time and historical economic data for a wide variety of
* economic indicators including GDP, unemployment, inflation, retail sales,
* and many others. Essential for macroeconomic analysis and understanding
* economic trends and cycles.
*
* @param params - Economic indicators request parameters
* @param params.name - The economic indicator to retrieve
* @param params.from - Start date in YYYY-MM-DD format (optional, defaults to 1 year ago)
* @param params.to - End date in YYYY-MM-DD format (optional, defaults to today)
*
* @returns Promise resolving to array of economic indicator data with historical values
*
* @example
* ```typescript
* // Get GDP data for the last year
* const gdpData = await fmp.economic.getEconomicIndicators({
* name: 'GDP',
* from: '2023-01-01',
* to: '2023-12-31'
* });
* gdpData.data.forEach(gdp => {
* console.log(`${gdp.date}: GDP $${gdp.value.toLocaleString()} billion`);
* });
*
* // Get unemployment rate data
* const unemploymentData = await fmp.economic.getEconomicIndicators({
* name: 'unemploymentRate',
* from: '2024-01-01'
* });
*
* // Get inflation rate data
* const inflationData = await fmp.economic.getEconomicIndicators({
* name: 'inflationRate',
* from: '2023-01-01',
* to: '2023-12-31'
* });
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#economic-indicators-economics-data|FMP Economic Indicators Documentation}
*/
getEconomicIndicators(params: {
name: 'GDP' | 'realGDP' | 'nominalPotentialGDP' | 'realGDPPerCapita' | 'federalFunds' | 'CPI' | 'inflationRate' | 'inflation' | 'retailSales' | 'consumerSentiment' | 'durableGoods' | 'unemploymentRate' | 'totalNonfarmPayroll' | 'initialClaims' | 'industrialProductionTotalIndex' | 'newPrivatelyOwnedHousingUnitsStartedTotalUnits' | 'totalVehicleSales' | 'retailMoneyFunds' | 'smoothedUSRecessionProbabilities' | '3MonthOr90DayRatesAndYieldsCertificatesOfDeposit' | 'commercialBankInterestRateOnCreditCardPlansAllAccounts' | '30YearFixedRateMortgageAverage' | '15YearFixedRateMortgageAverage';
from?: string;
to?: string;
}): Promise<APIResponse<EconomicIndicator[]>>;
}
declare class MarketEndpoints {
private client;
constructor(client: FMPClient);
/**
* Get current market hours and trading status
*
* Provides real-time information about market trading hours, including
* whether markets are currently open or closed, trading session times,
* and upcoming market holidays. Essential for determining trading
* availability and market status.
*
* @returns Promise resolving to market hours data with trading status and session information
*
* @example
* ```typescript
* // Get current market status
* const marketHours = await fmp.market.getMarketHours();
* console.log(`Market is ${marketHours.data.isTheStockMarketOpen ? 'OPEN' : 'CLOSED'}`);
* console.log(`Current time: ${marketHours.data.currentTime}`);
* console.log(`Next trading day: ${marketHours.data.nextTradingDay}`);
*
* // Check if it's a trading day
* if (marketHours.data.isTheStockMarketOpen) {
* console.log('Markets are currently open for trading');
* } else {
* console.log('Markets are closed');
* }
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#market-hours|FMP Market Hours Documentation}
*/
getMarketHours(): Promise<APIResponse<MarketHours>>;
/**
* Get overall market performance data
*
* Provides comprehensive market performance data including major indices,
* market breadth, and key performance metrics. Essential for understanding
* overall market sentiment, trends, and daily market activity.
*
* @returns Promise resolving to array of market performance data with indices and metrics
*
* @example
* ```typescript
* // Get overall market performance
* const marketPerformance = await fmp.market.getMarketPerformance();
* marketPerformance.data.forEach(market => {
* console.log(`${market.index}: ${market.change} (${market.changesPercentage}%)`);
* console.log(` Open: $${market.open}, High: $${market.dayHigh}, Low: $${market.dayLow}`);
* });
*
* // Find specific indices
* const sp500 = marketPerformance.data.find(market => market.index === 'S&P 500');
* console.log(`S&P 500 performance: ${sp500?.changesPercentage}%`);
*
* // Check market sentiment
* const gainers = marketPerformance.data.filter(market => market.changesPercentage > 0);
* const losers = marketPerformance.data.filter(market => market.changesPercentage < 0);
* console.log(`Gaining indices: ${gainers.length}, Losing indices: ${losers.length}`);
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#market-performance|FMP Market Performance Documentation}
*/
getMarketPerformance(): Promise<APIResponse<MarketPerformance[]>>;
/**
* Get top gaining stocks for the current trading day
*
* Provides a list of stocks that have gained the most value during the
* current trading session. Essential for identifying momentum stocks,
* tracking market movers, and discovering potential investment opportunities.
* Useful for day trading, momentum strategies, and market analysis.
*
* @returns Promise resolving to array of top gaining stocks with price and percentage change data
*
* @example
* ```typescript
* // Get top gainers for the day
* const gainers = await fmp.market.getGainers();
* console.log(`Top ${gainers.data.length} gaining stocks today:`);
*
* gainers.data.forEach((stock, index) => {
* console.log(`${index + 1}. ${stock.symbol} (${stock.name})`);
* console.log(` Price: $${stock.price} | Change: +${stock.change} (${stock.changesPercentage}%)`);
* console.log(` Volume: ${stock.volume.toLocaleString()}`);
* });
*
* // Find stocks with >10% gains
* const bigGainers = gainers.data.filter(stock => stock.changesPercentage > 10);
* console.log(`Stocks with >10% gains: ${bigGainers.length}`);
*
* // Check volume leaders among gainers
* const highVolumeGainers = gainers.data.filter(stock => stock.volume > 1000000);
* console.log(`High volume gainers (>1M shares): ${highVolumeGainers.length}`);
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#market-biggest-gainers-market-overview|FMP Market Biggest Gainers Documentation}
*/
getGainers(): Promise<APIResponse<MarketPerformance[]>>;
/**
* Get top losing stocks for the current trading day
*
* Provides a list of stocks that have lost the most value during the
* current trading session. Essential for identifying underperforming stocks,
* tracking market decliners, and discovering potential contrarian opportunities.
* Useful for risk management, short selling strategies, and market analysis.
*
* @returns Promise resolving to array of top losing stocks with price and percentage change data
*
* @example
* ```typescript
* // Get top losers for the day
* const losers = await fmp.market.getLosers();
* console.log(`Top ${losers.data.length} losing stocks today:`);
*
* losers.data.forEach((stock, index) => {
* console.log(`${index + 1}. ${stock.symbol} (${stock.name})`);
* console.log(` Price: $${stock.price} | Change: ${stock.change} (${stock.changesPercentage}%)`);
* console.log(` Volume: ${stock.volume.toLocaleString()}`);
* });
*
* // Find stocks with >10% losses
* const bigLosers = losers.data.filter(stock => stock.changesPercentage < -10);
* console.log(`Stocks with >10% losses: ${bigLosers.length}`);
*
* // Check for potential oversold conditions
* const highVolumeLosers = losers.data.filter(stock => stock.volume > 1000000);
* console.log(`High volume losers (>1M shares): ${highVolumeLosers.length}`);
*
* // Look for potential bounce candidates
* const oversoldStocks = losers.data.filter(stock =>
* stock.changesPercentage < -5 && stock.volume > 500000
* );
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#market-biggest-losers-market-overview|FMP Market Biggest Losers Documentation}
*/
getLosers(): Promise<APIResponse<MarketPerformance[]>>;
/**
* Get most actively traded stocks for the current trading day
*
* Provides a list of stocks with the highest trading volume during the
* current trading session. Essential for identifying stocks with high
* liquidity, tracking market interest, and discovering stocks with
* significant trading activity. Useful for day trading and liquidity analysis.
*
* @returns Promise resolving to array of most active stocks with volume and price data
*
* @example
* ```typescript
* // Get most active stocks for the day
* const mostActive = await fmp.market.getMostActive();
* console.log(`Top ${mostActive.data.length} most active stocks today:`);
*
* mostActive.data.forEach((stock, index) => {
* console.log(`${index + 1}. ${stock.symbol} (${stock.name})`);
* console.log(` Volume: ${stock.volume.toLocaleString()} shares`);
* console.log(` Price: $${stock.price} | Change: ${stock.change} (${stock.changesPercentage}%)`);
* console.log(` Avg Volume: ${stock.avgVolume?.toLocaleString() || 'N/A'}`);
* });
*
* // Find stocks with unusual volume (>2x average)
* const unusualVolume = mostActive.data.filter(stock =>
* stock.avgVolume && stock.volume > stock.avgVolume * 2
* );
* console.log(`Stocks with unusual volume: ${unusualVolume.length}`);
*
* // Check for high volume gainers
* const highVolumeGainers = mostActive.data.filter(stock =>
* stock.changesPercentage > 0 && stock.volume > 1000000
* );
* console.log(`High volume gainers: ${highVolumeGainers.length}`);
*
* // Find penny stocks with high volume
* const pennyStocks = mostActive.data.filter(stock =>
* stock.price < 5 && stock.volume > 500000
* );
* ```
*
* @see {@link https://site.financialmodelingprep.com/developer/docs#market-most-actives|FMP Market Most Actives Documentation}
*/
getMostActive(): Promise<APIResponse<MarketPerformance[]>>;
/**
* Get sector performance data for the current trading day
*
* Provides performance data for all major market sectors including
* technology, healthcare, financials, energy, and others. Essential for
* sector rotation analysis, identifying leading/lagging sectors, and
* understanding market breadth and sector-specific trends.
*
* @returns Promise resolving to array of sector performance data with percentage changes
*
* @example
* ```typescript
* // Get sector performance for the day
* const sectorPerformance = await fmp.market.getSectorPerformance();
* console.log(`Sector performance for ${sectorPerformance.data.length} sectors:`);
*
* sectorPerformance.data.forEach(sector => {
* const changeColor = sector.changesPercentage >= 0 ? 'green' : 'red';
* console.log(`${sector.sector}: ${sector.changesPercentage}%`);
* console.log(` Change: ${sector.changesPercentage >= 0 ? '+' : ''}${sector.changesPercentage}%`);
* });
*
* // Find best performing sectors
* const topSectors = sectorPerformance.data
* .sort((a, b) => b.changesPercentage - a.changesPercentage)
* .slice(0, 3);
* console.log('Top 3 performing sectors:');
* topSectors.forEach((sector, index) => {
* console.log(`${index + 1}. ${sector.sector}: ${sector.changesPercentage}%`);
* });
*
* // Find worst performing sectors
* const bottomSectors = sectorPerformance.data
* .sort((a, b) => a.changesPercentage - b.changesPercentage)
* .slice(0, 3);
* console.log('Bottom 3 performing sectors:');
* bottomSectors.forEach((sector, index) => {
* console.log(`${index + 1}. ${sector.sector}: ${sector.changesPercentage}%`);
* });
*
* // Check for sector rotation
* const gainingSectors = sectorPerformance.