A quarterly revenue chart can look consistent while mixing reporting periods that ended weeks apart. SEC EDGAR's XBRL frames endpoint groups facts by the calendar period they most closely match. Companies with different fiscal calendars can therefore appear in the same frame even when their actual start and end dates differ.
The SEC's API documentation describes quarterly duration frames as roughly 91 days, plus or minus 30 days. It also says the endpoint selects one fact per reporting entity that was last filed and most closely fits the requested calendar period. That makes frames useful for a broad screen, but the frame name alone is too coarse for an exact quarter-over-quarter calculation.
A small example
Imagine a screen with two synthetic revenue facts:
facts = [
{"cik": "0000000001", "start": "2024-01-01", "end": "2024-03-31", "value": 120},
{"cik": "0000000002", "start": "2023-12-03", "end": "2024-03-02", "value": 120},
]
Both rows cover about three months, and both values are in the same illustrative units. They do not describe the same dates. A market event in late March could affect the first company's reporting period while falling outside the second's. Equal frame membership does not align the underlying windows.
A second trap appears when a dashboard is rebuilt later. The endpoint's last-filed selection can pick a fact from a later filing. A historical screen built today can consequently differ from one built before that filing. The difference may be a revision, a comparative disclosure, or a different candidate selection; the frame alone does not establish which. This is especially important when testing a strategy: a backtest needs the information available at the simulated decision date.
Retain the dates and filing identity
This example labels the periods and computes the inclusive duration. It takes normalized rows, not the raw API response. The sample values are fictional.
from datetime import date
def describe_period(row):
start = date.fromisoformat(row["start"])
end = date.fromisoformat(row["end"])
if end < start:
raise ValueError("end precedes start")
return {
**row,
"inclusive_days": (end - start).days + 1,
}
facts = [
{"cik": "0000000001", "start": "2024-01-01", "end": "2024-03-31", "value": 120},
{"cik": "0000000002", "start": "2023-12-03", "end": "2024-03-02", "value": 120},
]
for row in facts:
result = describe_period(row)
print(result["cik"], result["start"], result["end"], result["inclusive_days"])
The output is 91 days for both rows. Duration checks catch annual facts mixed into a quarterly calculation, but they do not establish that two fiscal quarters ended on the same date. Store the start and end dates along with the entity, taxonomy, concept, unit, value and accession. For a point-in-time dataset, retain filing date and, when the application needs intraday precision, use filing acceptance timestamps from the filing metadata.
A frame is a useful discovery layer. For exact company history, inspect the candidates in companyfacts or companyconcept, and follow the accession back to its filing. Companyfacts aggregates standard-taxonomy facts applying to the whole entity; it is not a complete substitute for the filing when the answer depends on custom tags or dimensional detail.
Choose a time policy before calculating growth
For a fiscal-quarter chart, group observations by the company's actual fiscal periods. For a calendar-aligned comparison across companies, display the actual reporting dates and decide how much mismatch your analysis accepts. A company changing its fiscal calendar or using a 53-week year deserves a separate review; a fixed 90-day rule will discard legitimate periods.
For a point-in-time screen, select only filings available by the cutoff, then apply a documented rule for choosing among eligible candidates with the same concept, unit and period. Preserve all candidates and their accessions. If a later filing changes a comparative value, you can recompute the current view without rewriting the earlier snapshot. Filing date alone provides day-level ordering, not proof that a filing was available at a particular intraday trading time.
Instant facts need a different check. A balance-sheet value is measured at a date, so treating it as a 91-day duration makes no sense. Frames use the I suffix for instantaneous periods; compare the actual end dates and the same unit before calculating changes.
The SEC notes that API data updates as filings are disseminated and that processing delays can grow during peak periods. Record when you fetched a response as well as the filing identity. That gives you a practical way to distinguish an old cached snapshot from a later view when investigating a changed chart.
For a related period problem, see normalizing discrete quarters and year-to-date facts.
Top comments (0)