The Complete Guide to Using XBRL Data for Financial Analysis

What XBRL Actually Is

XBRL stands for eXtensible Business Reporting Language. It's a tagging standard that turns the numbers in SEC filings into structured data. Every figure in a modern 10-K or 10-Q carries a machine-readable label that says what the number represents (revenue, total assets, diluted EPS), which period it covers, what unit it's in, and which company reported it. A PDF gives you revenue as ink on a page. The tagged version gives you a fact you can query, join, and chart without copying anything by hand.

The SEC started phasing in mandatory XBRL tagging in 2009, beginning with the largest filers, and within a few years it covered the financial statements in essentially every 10-K and 10-Q. The format has since moved to inline XBRL, meaning the tags now live inside the same HTML document a human reads rather than in a separate data file. Open a recent filing on EDGAR, launch the inline viewer, and you can click any number to see exactly how the company tagged it. Spending ten minutes doing that with a filing you know well will teach you the mechanics faster than any documentation.

Why XBRL Matters for Investors

Before XBRL, getting financials out of filings meant either paying a data vendor or copying numbers into a spreadsheet by hand. Vendors are still useful, mostly because they clean and standardize what companies report, but the raw material they sell is now free at the source. The SEC publishes structured financial data for every US filer through a public API with no key, no account, and no contract.

That changes what an individual analyst or a two-person team can realistically do. Screening the whole universe of US filers on a fundamental metric used to require a terminal subscription. Now it takes an afternoon and some scripting. You also get something vendors rarely give you, which is a direct line to the reported figure. When a number looks strange, you can trace it to the exact filing and the exact tag instead of guessing what a vendor's normalization did to it.

Where the Data Lives

Everything runs through data.sec.gov, the SEC's structured data service. Three endpoints cover most of what you'll ever need.

• companyconcept returns one tag for one company across time. The pattern looks like /api/xbrl/companyconcept/CIK0000320193/us-gaap/NetIncomeLoss.json, which returns every net income fact Apple has ever tagged. The ten-digit number is the CIK, the SEC's company identifier, zero padded.
• companyfacts returns every tagged fact for one company in a single JSON payload. This is the workhorse when you're building a picture of one business.
• frames flips the axis and returns one tag across all companies for one period. For example, /api/xbrl/frames/us-gaap/Assets/USD/CY2024Q1I.json gives you total assets for every filer as of the first quarter of 2024. The trailing I marks an instantaneous, point-in-time value; duration concepts like revenue drop it.

To map tickers to CIK numbers, the SEC publishes a file called company_tickers.json. Two practical rules apply to all of this. Declare a User-Agent header with your name or company and an email address, because the SEC blocks anonymous scripted traffic. And stay under the published limit of ten requests per second, which is generous for research work. If you want everything at once, skip the crawling entirely. The SEC offers bulk downloads, including quarterly Financial Statement Data Sets and an archive of the full companyfacts dataset.

The Taxonomy, and the Revenue Problem

Tags come from a shared dictionary called the US GAAP taxonomy. Concepts like Revenues, NetIncomeLoss, Assets, Liabilities, and StockholdersEquity are defined once and used by every filer, which is what makes cross-company work possible at all. Each concept is either a duration (revenue over a quarter) or an instant (assets on a balance sheet date), and each fact carries a unit, usually USD, sometimes shares or USD per share.

Now the catch that trips up nearly every first-time user: companies don't all use the same tag for the same idea. Revenue is the classic case. Some filers tag it as Revenues, older filings often use SalesRevenueNet, and after the ASC 606 revenue standard most companies moved to RevenueFromContractWithCustomerExcludingAssessedTax. Query only Revenues and you'll see gaps and assume the data is broken. The fix is a fallback chain. Try the contract-with-customer tag first, then Revenues, then the older variants, and take the first one that has values for your period. Net income behaves much better, since NetIncomeLoss is close to universal.

Companies can also invent custom extension tags for items the standard taxonomy doesn't cover. The flexibility is necessary, and it's harmless when you're deep in a single company, but custom tags don't map across companies. For peer comparison, stick to standard concepts. And if you're ever unsure which tags a company actually uses, pull its companyfacts payload and scan the keys under the us-gaap section. That takes seconds and beats guessing at concept names.

A Worked Example: Five Years of Operating Margin

Say you want a clean five-year operating margin series for one company. The steps look like this.

1. Look up the CIK in company_tickers.json, then pull the companyfacts JSON for it.
2. From the us-gaap section, extract OperatingIncomeLoss plus your revenue fallback chain.
3. Filter to annual facts. Each fact records which form it came from, the fiscal year and period, the start and end dates, and the filing date. Keep the ones where the form is 10-K and the start and end dates span a full year.
4. Deduplicate. The same annual number appears in several filings because every 10-K repeats prior years as comparatives. Decide whether you want figures as first reported (keep the earliest filing) or as restated (keep the latest), and apply that consistently. For most ratio work you want the latest.
5. Compute the ratio. If the company reports, say, operating income of $630 million on revenue of $4.2 billion, that year's operating margin is 15 percent. Repeat per year and you have your series.

One wrinkle if you want quarterly numbers: there is no Q4 filing. Companies file three 10-Qs and then a 10-K covering the full year, so Q4 has to be derived by subtracting the three reported quarters from the annual figure. Forgetting this is probably the most common bug in homemade XBRL pipelines, and I say that as someone who has personally written the bug.

Comparing Across Companies

The frames endpoint does the heavy lifting for cross-sectional work because it aligns everyone to calendar periods. A few things still need care. Fiscal calendars differ, so a retailer with a January year end lands in frames differently than a calendar-year filer, and you should check actual period end dates rather than trusting labels. A filer with a June year end, for instance, reports an annual period that straddles two calendar years and gets slotted into whichever frame best matches its period end. Tagging depth varies too. Every filer tags the totals, but the detail underneath (segment revenue, individual expense lines) gets inconsistent quickly, partly because of the custom extension problem above.

My rule of thumb is that top-level concepts such as revenue, net income, assets, equity, and operating cash flow compare well across companies with minimal cleaning. Anything below the top level deserves validation against a handful of real filings before you trust it at scale.

What You Can Build With It

Once the pipeline exists, a few applications repay the setup effort quickly.

• Universe screening. Pull one metric across every filer with a frames call, rank the results, and flag outliers. Any tagged concept can become a screen, which goes well beyond what most retail screeners expose.
• Ratio databases. Pull numerators and denominators separately and compute ratios yourself. You control the definitions, which matters more than people expect, since vendors quietly disagree about things like what belongs in operating income. Every input to a Piotroski F-Score, to take a well-known example, is a standard tagged concept, so you can compute the score across the whole market yourself.
• Trend work. Track a metric across a sector over several years. Inventory building up across a retail peer group, or capex trends across an industry, amounts to a few dozen API calls and a chart.
• Red-flag scans. Compare growth rates within a company's own statements. Receivables growing much faster than revenue for several quarters running is the classic warning sign, and XBRL makes checking it across an entire watchlist trivial.

For what it's worth, this is the same public data that most company-intelligence tools, including the ones we build at FirmAdapt, sit on top of. Understanding the raw layer makes you a sharper user of everything downstream.

Limitations Worth Respecting

XBRL data is only as good as the tagging, and tagging has errors. Companies occasionally pick the wrong tag, flip a sign, or file a value at the wrong scale, and the same line item sometimes moves between tags from one year to the next. When a value looks off by a factor of a thousand, it usually is, and the original filing settles the question. Validate anything surprising before it drives a decision.

Coverage is uneven. The primary statements are tagged well, while footnotes and supplementary schedules are tagged more loosely, so don't expect to reconstruct a debt maturity schedule or a lease table from tags alone. History is bounded too. The mandate only began in 2009 and smaller filers came in later, so long backtests will simply run out of data.

And the tags only ever cover the numbers. Management discussion, risk factors, and footnotes carry the context that explains why the numbers moved, and none of that lives in XBRL. The workflow that has served me best is to let the structured data do a wide quantitative sweep across many companies, then read the actual filings for the short list the sweep surfaces. If you're starting today, pick one company you know well, pull its companyfacts file, and reconcile three numbers against the 10-K. That exercise will teach you more about the format than any guide, this one included.