SEC companyfacts: read XBRL with the right context

Choose the smallest useful endpoint

The SEC documents aggregation for standard-taxonomy facts applying to the entire entity. A custom company extension or segment-specific disclosure may require the filing’s own XBRL and notes. A missing concept in companyfacts does not prove the company omitted the disclosure.

Retain the evidence fields

Store taxonomy, tag, unit, start and end dates, value, form, filed date and accn together. Duration facts need their start date; instant facts typically do not. Preserve any frame or fiscal period labels as additional context rather than using them to erase the underlying dates.

The selection code below intentionally keeps all USD observations for a chosen end date. It does not pick the last list item or silently treat a later filing as the only correct historical value. Review amendments and comparative restatements according to your application’s stated policy.

def observations(payload, end_date):
    concept = payload["facts"]["us-gaap"]["AccountsPayableCurrent"]
    return [
        {key: fact.get(key) for key in
         ("start", "end", "val", "accn", "form", "filed", "fy", "fp", "frame")}
        for fact in concept.get("units", {}).get("USD", [])
        if fact.get("end") == end_date
    ]

# payload must be a companyfacts response.
# Inspect the returned accession/form context before choosing a value.

Illustrative extraction logic for the documented JSON structure. No live companyfacts request or accounting-validation test was performed for this page.

Do not compare unlike periods

Revenue for a quarter and revenue for a year-to-date duration can share a tag. A calendar frame can also combine companies whose periods end on different dates. Before comparing values, check start/end dates, unit, taxonomy and consolidation scope.

When your output cites a figure, link the accession and original financial statement or note. The aggregated endpoint is useful for discovery and repeatable extraction, but the source filing explains accounting definitions and presentation choices.

When to leave the aggregate API

Use the filing itself when you need custom tags, segment tables, non-GAAP reconciliation or a narrative explanation. An event-stream post that a new 10-Q arrived is a trigger for that retrieval; it is not proof that the post includes an XBRL statement.