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

EXPERIMENTAL: earnings report dates and EPS surprises.

• fetch-earnings-history / * - the last four quarters from the quoteSummary earnings module: fiscal period end paired with the date and time the results were reported, EPS actual vs. estimate.
• fetch-earnings-dates / * - the longer history of earnings announcement events from Yahoo's visualization API (back to the 1990s for large US companies), with EPS estimate, actual and surprise.

Both use the authenticated session of clj-yfinance.experimental.auth.

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

• EPS here is the figure analysts estimate (usually adjusted, non-GAAP), which can differ from the reported diluted EPS of the statements.
• :period-end is normalised to the month end, as in the statements.
• The visualization history currently stops in mid-2025 (Yahoo no longer seems to update it); fetch-earnings-history covers the recent quarters.

WARNING: Yahoo does not document these endpoints and can change them at any time.

earnings-history-rows clj

(earnings-history-rows ticker earnings)

Rows from the quoteSummary earnings module map (the value of :earnings), sorted by period end. Strings are parsed to doubles; absent values are nil. Pure function for testing.

fetch-earnings-dates clj

(fetch-earnings-dates ticker & {:keys [limit] :or {limit 100}})

Fetch earnings announcement events for a ticker (simple API). Options as for fetch-earnings-dates*. Returns the rows, or [] on failure.

fetch-earnings-dates* clj

(fetch-earnings-dates* ticker & {:keys [limit] :or {limit 100} :as opts})

Fetch earnings announcement events for a ticker (verbose API), from Yahoo's visualization API.

Options: :limit - how many of the most recent events to fetch (default 100). Yahoo serves at most 250 per request; larger limits are paged.

Returns {:ok? true :data [rows] :request {...}} or {:ok? false :error {...}} (:auth-failed, :session-failed, :request-failed, :rate-limited, :http-error, :api-error, :missing-data, :parse-error, :invalid-opts). Rows, sorted ascending by time: {:ticker "AAPL" :company-name "Apple Inc." :event-name nil :announced-at "2025-05-01T20:30:00Z" :announced-epoch 1746131400 :timing "TAS" :eps-estimate 1.63 :eps-actual 1.65 :surprise-pct 1.41 :timezone "EDT" :gmt-offset-ms -14400000} :event-name is nil for plain earnings releases and names other events (e.g. "Annual Shareholders Meeting", "Q1 2025 Earnings Call"), whose EPS fields are usually nil. :timezone and :gmt-offset-ms are the exchange's at the event. Values Yahoo leaves out are nil. If any page fails, the whole call fails.

fetch-earnings-history clj

(fetch-earnings-history ticker)

Fetch the last four reported quarters for a ticker (simple API). Returns the rows of fetch-earnings-history*, or [] on failure.

fetch-earnings-history* clj

(fetch-earnings-history* ticker)

Fetch the last four reported quarters for a ticker (verbose API), from the quoteSummary earnings module.

Returns {:ok? true :data [rows] :request {...}} or {:ok? false :error {...}} (error types as for fundamentals/fetch-quotesummary*). Rows, sorted by period end: {:ticker "AAPL" :period-end "2025-09-30" :reported-date "2025-10-30" :reported-at 1761856200 :fiscal-quarter "4Q2025" :calendar-quarter "3Q2025" :eps-actual 1.85 :eps-estimate 1.76993 :eps-difference 0.08 :surprise-pct 4.52 :currency "USD"} :reported-at is epoch seconds of the release (e.g. 16:30 New York time for an after-the-close report); :reported-date is Yahoo's date string for it. :currency is the reporting currency of the EPS figures. Values Yahoo leaves out are nil. A ticker without the module's quarterly data gives [].

parse-visualization-response clj

(parse-visualization-response ticker status body)

Interpret a visualization API status and body. Success is {:ok? true :data {:rows [...] :total n}} with rows in response order, columns mapped by their id (not their position). Pure function for testing.