Stock market data infrastructure
SEC EDGAR XBRL API vs a normalized financials API
When to call SEC EDGAR's free XBRL APIs directly and when a normalized financial statements API saves concept mapping, deduplication and period handling.
Documentation revised
Third-party plans and limits on this page were checked against each provider's public pages on 2026-11-04. Providers change plans; their current pages are authoritative.
What SEC EDGAR provides for free
The SEC publishes JSON APIs on data.sec.gov for filing submissions, single company concepts, all company facts, and cross-company frames. They need no authentication or API key. The SEC states typical processing delays of under a second for submissions and under a minute for the XBRL APIs, and republishes bulk ZIP files of the company facts and submissions data nightly at about 3:00 a.m. ET.
Automated access must follow the SEC's fair access guidance: a maximum of 10 requests per second, and a declared User-Agent that identifies the requester. For US-listed filers, this is the primary source. Any normalized API built on SEC data, including this one, is downstream of it.
What you build when you go direct
Company facts are reported XBRL facts, not finished statements. Your code chooses which concept represents each line item, and filers can use different tags for the same economic item or change tags between years. The same period appears again as a comparative in later filings, so you need a rule for which filing's value wins. Quarterly cash flow in 10-Q filings is year-to-date, so standalone quarters must be derived. Fiscal years that do not end in December need their own period mapping.
None of this is hard for one company and one field. It becomes the main maintenance cost across hundreds of filers and dozens of fields, and silent mistakes, such as picking a tag that covers only part of revenue, look like valid numbers.
import httpx
# SEC asks automated clients to declare who they are in the User-Agent
# header and to stay at or below 10 requests per second.
headers = {"User-Agent": "Example Corp [email protected]"}
facts = httpx.get(
"https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json",
headers=headers, timeout=30,
).json()["facts"]["us-gaap"]
# You choose the concept. Filers can report revenue under different tags,
# and a single company can change tags between years.
for tag in ("RevenueFromContractWithCustomerExcludingAssessedTax", "Revenues", "SalesRevenueNet"):
if tag in facts:
rows = [r for r in facts[tag]["units"]["USD"] if r.get("form") == "10-K" and r.get("fp") == "FY"]
# One fiscal period appears in several later filings (comparatives);
# keep one row per period end, here the latest filed.
latest = {}
for r in sorted(rows, key=lambda r: r["filed"]):
latest[r["end"]] = r
print(tag, [(end, r["val"]) for end, r in sorted(latest.items())][-3:])
break
What a normalized API returns instead
The financials endpoint returns one row per company, period type and period end, with standard field names across filers. Each row carries primary_source, filed_date, currency, cash_flow_basis for quarterly cash flow, and a sources map that names the XBRL tag behind each populated field. That map keeps the normalization auditable: you can check any value against the company facts JSON or the filing itself.
import os
import httpx
response = httpx.get(
"https://stockmarketapi.ai/api/v1/companies/AAPL/financials",
params={"period_type": "FY", "limit": 3, "exchange": "NASDAQ"},
headers={"X-API-Key": os.environ["STOCKMARKET_API_KEY"]},
timeout=30,
)
response.raise_for_status()
for period in response.json()["periods"]:
# sources maps each populated field to the tag it came from,
# e.g. {"revenue": "us-gaap:RevenueFromContractWithCustomer..."}.
print(period["period_end"], period.get("revenue"),
period.get("primary_source"), (period.get("sources") or {}).get("revenue"))
Choose SEC EDGAR directly when
You need a concept this API does not map, every fact as filed including dimensional and custom tags, the lowest possible latency after filing, or zero third-party dependency and cost. Research on the full population of US filers is also usually better served by the SEC's bulk ZIP files than by any per-company API.
Choose a normalized API when
You need comparable statement fields across many companies quickly, want period deduplication and cash-flow de-cumulation handled consistently, or also need non-SEC listings such as ASX companies, prices and report documents in one contract. Check the trade-offs: normalization is an interpretation, coverage is limited to the stored universe, and the stored history for a company can be shorter than its full EDGAR record.