UFC - Unified Finance Client/com.ulalax.ufc.api/Ufc

Ufc

Main entry point for the UFC (US Free Financial Data Collector) library.

This class provides a unified facade for accessing financial data from multiple sources:

Yahoo Finance: Real-time quotes, historical data, company fundamentals, options chains, stock screener, earnings calendar, and WebSocket streaming
FRED: Federal Reserve Economic Data including GDP, unemployment, inflation, and other economic indicators
Business Insider: ISIN to ticker symbol conversion

The library is inspired by Python's yfinance and fredapi libraries, providing similar functionality for Kotlin/JVM applications.

Quick Start

// Create client without FRED API
val ufc = Ufc.create()
val quote = ufc.quote("AAPL")
println("Price: ${quote.pricing?.price}")

// Or with FRED API key
val config = UfcConfig(fredApiKey = "your-api-key")
val ufcWithFred = Ufc.create(config)

Usage Examples

// Get multiple quotes
val quotes = ufc.quote(listOf("AAPL", "GOOGL", "MSFT"))

// Get historical chart data
val chart = ufc.chart(
    symbol = "AAPL",
    interval = Interval.OneDay,
    period = Period.OneYear
)

// Get company fundamentals
val summary = ufc.quoteSummary(
    "AAPL",
    QuoteSummaryModule.PRICE,
    QuoteSummaryModule.FINANCIAL_DATA
)

// Screen stocks
val gainers = ufc.screener(PredefinedScreener.DAY_GAINERS, count = 10)

// Get FRED economic data (requires API key)
val gdp = ufc.series("GDP")

Resource Management

This class implements AutoCloseable and should be used with try-with-resources or Kotlin's use function to ensure proper cleanup of HTTP clients and WebSocket connections:

Ufc.create().use { ufc ->
    val quote = ufc.quote("AAPL")
    // ...
}

Types

Companion

object Companion

Properties

businessInsider

val businessInsider: BusinessInsiderClient

Business Insider client for ISIN lookups

fred

val fred: FredClient?

FRED client for economic data (null if API key not provided)

streaming

val streaming: StreamingClient

WebSocket streaming client for real-time price updates

yahoo

val yahoo: YahooClient

Yahoo Finance client for market data and company information

Functions

chart

suspend fun chart(symbol: String, interval: Interval = Interval.OneDay, period: Period = Period.OneYear, vararg events: ChartEventType): ChartData

Retrieves historical OHLCV (Open, High, Low, Close, Volume) chart data.

open override fun close()

Closes all underlying HTTP clients and resources.

earningsCalendar

suspend fun earningsCalendar(symbol: String, limit: Int = 12, offset: Int = 0): EarningsCalendar

Retrieves the earnings calendar for a specific company.

fundamentalsTimeseries

suspend fun fundamentalsTimeseries(symbol: String, types: List<FundamentalsType>, startDate: LocalDate? = null, endDate: LocalDate? = null): FundamentalsTimeseriesResult

Retrieves time-series fundamental data for financial statement line items.

lookup

suspend fun lookup(query: String, type: LookupType = LookupType.ALL, count: Int = 25): LookupResult

Looks up securities by query string with optional type filtering.

marketSummary

suspend fun marketSummary(market: MarketCode): MarketSummaryResult

Retrieves market summary data for a specific market.

marketTime

suspend fun marketTime(market: MarketCode): MarketTimeResult

Retrieves market trading hours and status for a specific market.

options

suspend fun options(symbol: String, expirationDate: Long? = null): OptionsData

Retrieves options chain data for a specific symbol and expiration date.

quote

suspend fun quote(symbol: String): QuoteData

Retrieves real-time quote data for a single symbol.

suspend fun quote(symbols: List<String>): List<QuoteData>

Retrieves real-time quote data for multiple symbols in a single request.

quoteSummary

suspend fun quoteSummary(symbol: String, vararg modules: QuoteSummaryModule): QuoteSummaryModuleResult

Retrieves detailed company information using Yahoo's QuoteSummary modules.

screener

suspend fun screener(predefined: PredefinedScreener, count: Int = 25, sortField: ScreenerSortField? = null, sortAsc: Boolean? = null): ScreenerResult

Screens stocks using a predefined screener enum.

suspend fun screener(predefinedId: String, count: Int = 25, sortField: ScreenerSortField? = null, sortAsc: Boolean? = null): ScreenerResult

Screens stocks using a predefined screener ID.

suspend fun screener(query: ScreenerQuery, sortField: ScreenerSortField = ScreenerSortField.TICKER, sortAsc: Boolean = false, size: Int = 100, offset: Int = 0): ScreenerResult

Screens stocks using a custom query with filtering criteria.

suspend fun search(query: String, quotesCount: Int = 8, newsCount: Int = 8, enableFuzzyQuery: Boolean = false): SearchResponse

Searches for symbols, companies, and related news.

searchIsin

suspend fun searchIsin(isin: String): IsinSearchResult

Searches for a ticker symbol using an ISIN (International Securities Identification Number).

series

suspend fun series(seriesId: String, startDate: LocalDate? = null, endDate: LocalDate? = null, frequency: DataFrequency? = null): FredSeries

Retrieves economic data series from the Federal Reserve Economic Data (FRED) API.

visualization

suspend fun visualization(symbol: String, limit: Int = 12): VisualizationEarningsCalendar

Retrieves earnings calendar visualization data for a symbol.

Ufc