clj-yfinance.experimental.timeseries — com.github.clojure-finance/clj-yfinance 0.1.10

EXPERIMENTAL: financial statements from Yahoo's fundamentals-timeseries endpoint.

This is the endpoint Yahoo's own financials pages use. Unlike the quoteSummary statement modules (see fetch-financials in clj-yfinance.experimental.fundamentals, which Yahoo has cut down to a few fields), it returns the full income statement, balance sheet and cash flow statement. It needs no cookie or crumb.

• fetch-statements / fetch-statements* - statement line items as tidy rows
• fetch-timeseries / fetch-timeseries* - raw access by Yahoo type string (e.g. "quarterlyTotalRevenue")
• statement-fields, field->keyword - the field catalog

Data notes (Yahoo's behaviour, not this library's):

• Typical depth is 4 annual, 5 quarterly and a few trailing (TTM) points.
• Period ends are normalised to month ends: a fiscal quarter ending Saturday 2025-09-27 is reported as "2025-09-30".
• Annual and quarterly per-share values are restated to the current share basis (NVDA's FY2024 diluted EPS comes back as 1.19, not the 11.93 reported before its 2024 10:1 split). Trailing points are not always restated.
• :currency is the reporting currency, which can differ from the trading currency (0005.HK reports in USD).
• There is no trailing balance sheet.

WARNING: Yahoo does not document this endpoint and can change it at any time.

balance-sheet-fields clj

Balance sheet fields (Yahoo field names, 149), in python-yfinance's fundamentals_keys order.

cash-flow-fields clj

Cash flow statement fields (Yahoo field names, 123), in python-yfinance's fundamentals_keys order.

fetch-statements clj

(fetch-statements ticker & {:keys [frequencies statements fields start end]})

Fetch financial statement rows for a ticker (simple API). Options as for fetch-statements*. Returns the rows, or [] on failure.

fetch-statements* clj

(fetch-statements* ticker
                   &
                   {:keys [frequencies statements fields start end] :as opts})

Fetch financial statement line items for a ticker (verbose API).

Options: :frequencies - collection of :annual :quarterly :trailing (default all) :statements - collection of :income-statement :balance-sheet :cash-flow (default all) :fields - Yahoo field names, e.g. ["TotalRevenue" "DilutedEPS"]; overrides :statements. Must be in the catalog (statement-fields). :start/:end - epoch seconds (integer) or Instant, as for fetch-timeseries*

Returns {:ok? true :data [rows] :request {...}} or {:ok? false :error {...}}. Each row: {:ticker "AAPL" :statement :income-statement :field :total-revenue :yahoo-field "TotalRevenue" :frequency :quarterly :period-end "2025-06-30" :period-type "3M" :currency "USD" :value 9.4036E10} sorted by statement, field, frequency and period end. Only data Yahoo returns becomes a row; nothing is filled in. Balance-sheet fields have no trailing frequency. Unknown option keys or values give :invalid-opts.

All statements at all frequencies are about 1000 Yahoo types, i.e. 10 requests; narrow :statements, :frequencies or :fields to send fewer. If any request fails, the whole call fails (see fetch-timeseries*).

fetch-timeseries clj

(fetch-timeseries ticker types & {:keys [start end]})

Fetch raw fundamentals-timeseries rows by Yahoo type string (simple API). Returns the rows of fetch-timeseries*, or [] on failure.

fetch-timeseries* clj

(fetch-timeseries* ticker types & {:keys [start end] :as opts})

Fetch raw fundamentals-timeseries data by Yahoo type string (verbose API).

types is a collection of Yahoo types: a frequency prefix (annual, quarterly, trailing) plus a field name, e.g. ["annualTotalRevenue" "quarterlyDilutedEPS"]. They are sent in chunks of at most 100 types per request (query2, failing over to query1, with the chart endpoint's retry and backoff).

Options: :start - epoch seconds (integer) or Instant (default 1985-08-23) :end - epoch seconds (integer) or Instant (default now)

Returns {:ok? true :data [rows] :request {...}}, rows sorted by :type then :period-end: {:ticker "MSFT" :type "quarterlyDilutedEPS" :period-end "2025-06-30" :period-type "3M" :currency "USD" :value 3.65} Null entries and entries without a value are skipped; types Yahoo has no data for produce no rows (so does an unknown ticker). If every chunk is made only of types Yahoo does not know, the call fails with :api-error and :reason :no-known-types.

If any chunk fails, the whole call fails: {:ok? false :error {...}} with the failing chunk's error (:rate-limited, :http-error, :api-error, :parse-error, :connection-error) and no partial data. Bad arguments give :invalid-opts before any request.

field->keyword clj

(field->keyword field)

Kebab-case keyword for a Yahoo PascalCase field name. Runs of capitals are kept together as one word: "TotalRevenue" -> :total-revenue, "DilutedEPS" -> :diluted-eps, "NetPPE" -> :net-ppe, "DilutedNIAvailtoComStockholders" -> :diluted-ni-availto-com-stockholders. Injective over the field catalog.

income-statement-fields clj

Income statement fields (Yahoo field names, 103), in python-yfinance's fundamentals_keys order.

parse-timeseries-body clj

(parse-timeseries-body ticker json-string)

Parse a 200 timeseries response body into {:ok? true :data [rows]} or {:ok? false :error {...}}. Rows are {:ticker :type :period-end :period-type :currency :value}, in response order. Types Yahoo has no data for are simply absent. Pure function for testing.

parse-timeseries-response clj

(parse-timeseries-response ticker status body)

Interpret a timeseries HTTP status and body. Yahoo answers a request whose types it knows none of with 404 "No timeseries type(s) specified"; that becomes {:ok? true :data [] :no-known-types? true}. Any other non-200 is an :http-error. Pure function for testing.

statement-fields clj

Yahoo field names by statement.

statements-rows clj

(statements-rows ticker type-info rows)

Turn fetch-timeseries* rows into statement rows using type-info ({yahoo-type {:statement :field :yahoo-field :frequency}}), sorted by statement (income statement, balance sheet, cash flow), field name, frequency (annual, quarterly, trailing) and period end. Pure function for testing.