When does this company report, and what does the calendar know beforehand?

Every endpoint so far has described something that already happened. The calendar family is different: it describes scheduled events, which means part of what it returns is a forecast, and knowing which part is the whole skill.

The endpoint

/calendar/earnings takes from and to (YYYY-MM-DD), symbols (comma-separated, e.g. AAPL.US,MSFT.US), and fmt.

Three behaviours to internalise:

• Defaults are narrow. With no from, it starts today. With no to, it ends seven days from today. A bare call gives you the coming week, not everything.
• symbols filters inside the window; it does not replace it. This is the one worth testing rather than assuming. Pass symbols=AAPL.US alone and you will very often get zero rows — not because Apple has no earnings, but because the default window is the coming seven days and a company reports four times a year. Give it a range and the rows appear: symbols=AAPL.US&from=2026-01-01&to=2026-12-31 returns four, the quarters. If a symbol query comes back empty, widen the dates before you doubt the symbol.
• fmt defaults to csv, not json. So do /calendar/ipos and /calendar/splits; most of the rest of this course defaults the other way, and /calendar/dividends in the same family defaults to json. Pass fmt=json explicitly.

The record

A call for AAPL.US across a whole calendar year returns four rows, one per quarter. Here are the first and the last of them:

Two dates, two meanings. date is the fiscal period being reported, normalised to a calendar quarter-end — here 30 June. That last part matters on any join: issuers on 52/53-week calendars close near the date rather than on it, and Apple is one of them, ending its year on the last Saturday of September. Its fiscal Q3 2026 actually closed on Saturday 27 June 2026, and the API still labels the row 30 June. Treat date as a label, not as the issuer's period end. report_date is when the company announces it — 30 July. Confusing them shifts every earnings event by a month. before_after_market says whether the release lands outside trading hours, which is why an earnings reaction so often appears as a gap rather than a move.

The gotcha in an unreported row

On any row whose quarter has not been reported yet, actual is null, and percent is null for the same reason. But difference is 0 — and zero here does not mean "the company met the estimate exactly." It means the field was filled with a placeholder instead of being left null.

If you aggregate difference across a calendar window to measure surprises, every unreported future event contributes a clean zero and drags your average toward "no surprise." Filter on actual IS NOT NULL before you compute anything. This is the null-versus-zero distinction from Unit 1, showing up in the place where it does the most quiet damage.

On a reported quarter the same record is complete: actual and estimate both populated, difference the arithmetic gap between them, and percent that gap as a percentage.

What a calendar is and is not good for

Genuinely useful: knowing when a number lands. That is a scheduling fact, and it is what lets you plan a data refresh, avoid comparing a company that has reported against one that has not, or understand why a series has a discontinuity on a particular morning.

Not what it does: telling you what the number will be, or what the price will do afterwards. estimate is a survey of analysts, not a forecast the data provider stands behind, and future report_date values are frequently the company's expected date rather than a confirmed one — they move.

This course describes mechanics only. Nothing here suggests trading around an event, and the calendar contains no information about direction. Its content is a date and an expectation, and treating an expectation as a prediction is the error the field's own nulls are trying to warn you about.

Try it now

1. Here is /calendar/earnings?symbols=AAPL.US&fmt=json with no dates, called on 28 September 2026, a month before Apple's next report. That empty earnings array is the lesson about symbols. The table near the top of this lesson is the same call with from=2026-01-01&to=2026-12-31: find the first row where actual is empty and note what difference says on it.

{"type": "Earnings", "description": "Historical and upcoming Earnings",
 "symbols": "AAPL.US", "earnings": []}

2. Here is the same endpoint with from=2026-09-21&to=2026-09-25 and no symbols, its first row and its last. The caption gives the row count. That is what "the market's week" looks like as data: work out the average per trading day, then say what the Thursday figure does to that average.

3. For one reported quarter, verify that difference equals actual − estimate, and that percent is that gap over estimate. Confirming an API's own arithmetic is a five-minute habit that catches a lot.