XBRL (eXtensible Business Reporting Language) is the tagging system that turns the numbers in a filing into structured data. When Apple reports "revenue was $102,466,000,000," XBRL is what makes that readable as Revenues: 102466000000 instead of text in a table.
The basic idea
Every tagged number is a fact, and a fact has four parts:
- A concept: what the number means, picked from a taxonomy. The main one is
us-gaap(US accounting standards). There's alsodeifor entity info like company name and ticker. - A value: the number itself, or text for things like entity names.
- A context: the period it covers.
Assetsis an instant ("as of Sept 27, 2025"), whileRevenuesis a duration ("for the 12 months ended Sept 27, 2025"). Same tag, different meaning. - A unit: USD, shares, USD-per-share.
So one fact reads like: "us-gaap:Revenues, USD, 12 months ending 2025-09-27 = 102,466,000,000."
Inline XBRL
Since 2019, most companies file inline XBRL (iXBRL): the tags are embedded directly in the human-readable HTML. One document serves both humans and machines. Nice in theory. In practice it means the structured data is scattered through a giant HTML file instead of sitting in a clean XML blob.
Why it's a pain
- Tags aren't consistent. Companies pick different concepts for the same line item. "Revenue" might be
Revenues,RevenueFromContractWithCustomerExcludingAssessedTax, orSalesRevenueNet. Sometimes all three across different years. - Extensions. If no standard tag fits, a company can invent its own (
aapl:SomethingCustom). Great for accuracy, terrible for querying across companies. - Restatements. Companies re-tag old numbers. The "revenue for FY2023" you pulled last year might not match what the latest filing says for FY2023.
- Contexts multiply. One tag can appear with a dozen contexts: fiscal year, quarter, segment breakdowns, geographic slices. Picking "the" revenue number means filtering all that out.
- Duration vs. instant confusion. Sum four quarters of a duration tag and compare to the annual value and you'll occasionally get a mismatch, because companies report YTD and quarterly values both.
None of this is exotic edge-case stuff. It's the everyday reality of the data.
Skipping the wrangling
The raw layer is still useful when you need it. /v1/companies/:cik/facts gives you a company's full fact history, filterable by tag, unit, form, and period:
GET /v1/companies/0000320193/facts?tag=Assets
GET /v1/facts?tag=Revenues&end=2025-09-30&unit=USD # every company, one quarter
But most of the time you don't want facts, you want a statement. /v1/companies/:cik/financials normalizes the fact soup into income statement, balance sheet, or cash flow line items:
GET /v1/companies/0000320193/financials?statement=income&period=annual&limit=8
GET /v1/companies/0000320193/financials?statement=cashflow&period=quarterly
The cash flow statement includes a computed freeCashFlow line. If you've ever hand-rolled "operating cash flow minus capex" across inconsistent tag names, you know why that's nice to have.
More on the endpoints in the docs.