What is an analyst estimate, as data?

The three calendars before this one schedule events and carry provisional terms — a date, an EPS estimate, a split ratio, an offer price. /calendar/trends carries no event at all, only what a panel of analysts currently expects a company to earn. That makes it the most easily misread endpoint in the family, and the most interesting once you read it correctly.

The endpoint

/calendar/trends takes symbols — required, comma-separated — and fmt, which supports json only. There is no date range, because the data is not a series over calendar time; it is a snapshot of expectations for a set of fiscal periods.

The response nests one level deeper than you expect: trends is an array of arrays, one inner array per requested symbol.

Reading one record

From the documented AAPL.US example, trimmed:

period: "+1y"    date: "2025-09-30"
earningsEstimateAvg:  "7.4700"   earningsEstimateLow:  "6.8800"
earningsEstimateHigh: "7.9300"   earningsEstimateNumberOfAnalysts: "42"
earningsEstimateYearAgoEps: "6.6700"   growth: "0.1200"
revenueEstimateAvg: "420689000000.00"
revenueEstimateLow: "401691000000.00"
revenueEstimateHigh: "441882000000.00"
epsTrendCurrent:  "7.4700"   epsTrend7daysAgo:  "7.4800"
epsTrend30daysAgo: "7.4800"  epsTrend60daysAgo: "7.4800"
epsTrend90daysAgo: "7.3400"
epsRevisionsUpLast7days: "1"   epsRevisionsUpLast30days: "4"
epsRevisionsDownLast30days: "3"

period takes values like 0q, +1q, 0y, +1y — the current and next quarter, the current and next fiscal year. It is a relative label, so what 0y means depends on when you fetched it. Store the fetch date beside it or the record becomes uninterpretable in a month.

Every populated numeric value is a string. "7.4700", "42", "420689000000.00" — and some fields arrive empty or null instead, as the next section shows. Cast before you compute, and never sort these fields as text — a string sort compares character by character, so a two-digit estimate such as "10.6700" lands before "7.9300", the reverse of what you want.

The number that matters is the spread, not the average

"Consensus 7.47" sounds like a fact. Look at the range: low 6.88, high 7.93, from 42 analysts. The spread is 7.93 − 6.88 = 1.05, which is 14.1% of the average. Forty-two professionals with access to the same filings disagree by fourteen percent about the same fiscal year.

The revenue line tells the same story: 441,882 − 401,691 = $40.2 billion of disagreement, 9.6% of the $420.7 billion average.

A single average conceals that entirely. Whenever this endpoint gives you a Low and a High next to an Avg, the width is the honest content of the field.

The trend fields, and what they measure

epsTrendCurrent through epsTrend90daysAgo are the same estimate as it stood at five points in the past. In the example: 7.34 ninety days ago, 7.48 sixty and thirty and seven days ago, 7.47 now. So the estimate rose +0.13 over ninety days, or +1.77%, and slipped 0.01 in the last week — −0.13%.

epsRevisionsUpLast7days and its siblings count how many analysts moved, rather than by how much: 1 up in seven days, 4 up and 3 down in thirty.

Note carefully what these fields are: a measure of how expectations changed, not of whether they were right. The revision series records analyst behaviour. It contains no information about the outcome, and this course draws no inference from it about future prices. Describing what a field measures is the job here; using it to decide anything is not something this material recommends.

Two honest defects

revenueEstimateYearAgoEps is a misnamed field — it holds a revenue comparison, not an EPS one — and it carries no number: an empty string in the documented example, null on the live endpoint. Handle both; a check for one will not catch the other. And epsRevisionsDownLast7days is absent from the record entirely, while its Up counterpart is present. Absent keys and empty strings are both real; write your parser to tolerate them rather than to assume a fixed key set.

Try it now

1. Here is /calendar/trends?symbols=AAPL.US,MSFT.US, the first record of each inner list. Confirm the double-nesting from the paths: trends is a list of lists, one per symbol. The second table is Apple's call on its own, a few fields of its first record.

2. Here are the first records for Apple and for Upstart, a far smaller and more volatile company, both +1y. Compute (High − Low) ÷ Avg for each. The two numbers are a measure of how much is actually known.

3. Cast every field you use, then re-run your code with a record where revenueEstimateYearAgoEps is "". If it crashes, you have found the bug this lesson exists to prevent.