If you need financial figures from SEC filings in a form your code can use, an edgar json api can return structured data instead of making you copy values from a report. The key is choosing the right JSON: filing metadata identifies a submission, XBRL facts represent tagged values, a converter may organize a selected filing’s facts into statements, and the original SEC submission and its documents remain sources to verify. This guide shows a direct SEC.gov workflow and explains where SEC Filing Data’s third-party API fits.
| Research need | Data source | What it provides |
|---|---|---|
| Find a company’s filing history | SEC submissions JSON | Filing metadata, including forms and filing dates. |
| Retrieve standardized company facts | SEC Company Facts or Company Concept JSON | Tagged facts grouped by taxonomy and concept, with units and reporting periods. |
| Search by ticker or other supported criteria | SEC Filing Data Query API | Matching filing metadata and available filing details in JSON; API token required. |
| Review the disclosure and related materials | Original SEC filing and filing index | A submission may include a primary document and separate exhibits or attachments. |
| Convert a supported filing into organized financial-statement JSON | SEC Filing Data XBRL-to-JSON converter | Organized statement data for supported inputs, subject to documented coverage and request-method limitations. |
What SEC filing data in JSON contains
JSON is a data format, not a promise that every part of a filing has been converted. The SEC’s submissions endpoint returns company filing history and related metadata, such as forms and filing dates. The SEC’s XBRL endpoints return selected facts reported in tagged financial statements. Neither is a full copy of a filing’s narrative, tables, exhibits, or attachments.
XBRL (eXtensible Business Reporting Language) tags financial facts with a concept, value, unit, reporting period, and context. SEC Company Facts places facts into a JSON hierarchy by taxonomy and concept. For example, a concept may have an units object with a separate array for each unit of measure; each observation can carry a value, period end, form, filing date, and accession number. The JSON is machine-readable, but you still need to interpret those fields.
An original EDGAR filing may include a primary document and separate exhibits or attachments. The primary document presents the disclosure as filed; related materials may appear as separate files in the filing index. A converted JSON object is a derived representation and may omit context or material that is not part of its supported conversion. Keep the filing index and links to the primary document and any relevant exhibits or attachments with extracted values.
Choose the JSON source that matches your task
Use the SEC companyfacts endpoint when you want standardized facts for one filer across its filings. Use companyconcept when you already know the taxonomy and tag and want one concept’s reported observations. Use submissions when you need to identify filings and their metadata. The SEC’s frames endpoint is designed to return one fact per entity for a requested calendar-aligned period; fiscal periods that do not match the calendar may not line up exactly. The SEC’s EDGAR API documentation describes the endpoint families and their scope.
The SEC API aggregates facts that use standard taxonomies, such as US GAAP or IFRS, and apply to the filing entity as a whole. Company-specific extension tags and facts with dimensions for a segment or other narrower context are not included in these aggregate endpoints. For large-scale retrieval, the SEC also publishes bulk ZIP files for Company Facts and submissions.
SEC Filing Data is a third-party provider, while SEC.gov remains the source. Its current product pages describe a Query API for searching filing metadata and an XBRL-to-JSON converter for supported filings. This can be useful when you need a provider-managed search or filing-level organization in addition to direct SEC JSON. The SEC Filings API overview describes those services; check each API’s own coverage and documentation before building against it.
Get company facts from SEC.gov step by step
1. Identify the company by CIK
The SEC’s data endpoints use a Central Index Key (CIK), not a ticker in the URL. A CIK in these paths is ten digits, with leading zeros added when needed. For example, Apple Inc.’s CIK is 0000320193. If you start with a company name or ticker in an application, resolve it to a CIK and confirm the company name before requesting the facts. SEC Filing Data’s Mapping API documents lookups from a ticker, CIK, or company name; the SEC also publishes company-ticker mapping files.
2. Request the Company Facts JSON
The direct SEC endpoint uses HTTP GET and does not require an API key:
https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json
For automated requests, identify your application in a descriptive User-Agent with a contact address, download only what you need, and follow the SEC’s fair-access guidance. The SEC limits you to 10 requests per second across all machines. The data.sec.gov API does not support browser CORS, so a browser-based application generally needs a server-side request.
Here is a minimal Python example using only the standard library. It retrieves Apple’s company facts and prints the reported observations for the SEC-documented us-gaap concept AccountsPayableCurrent, keeping each observation’s unit and filing context visible.
import json
from urllib.request import Request, urlopen
cik = "0000320193"
url = f"https://data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json"
request = Request(
url,
headers={
"User-Agent": "Your Name your.email@example.com",
"Accept": "application/json",
},
)
with urlopen(request) as response:
company = json.load(response)
concept = company.get("facts", {}).get("us-gaap", {}).get("AccountsPayableCurrent")
if concept is None:
raise ValueError("The requested concept is not present in this response.")
for unit, observations in concept["units"].items():
for fact in observations:
if fact.get("form") in {"10-K", "10-Q"}:
print(
unit,
fact.get("start"),
fact["end"],
fact["val"],
fact.get("form"),
fact.get("filed"),
fact.get("accn"),
)
This example requests the complete Company Facts object and then selects one concept. It does not assert a particular returned value or that every company uses the same concept. To examine a different metric, first inspect the tags the filer actually reported and select the relevant concept and unit.
3. Select facts by concept, unit, and period
In the JSON, look underfacts, choose a taxonomy such asus-gaap, then find a concept key. Within the concept, units groups observations; choose the unit that matches the measure you intend to analyze. The val field is the reported numeric value in that unit. Do not assume every value is dollars: facts can use shares, per-share units, percentages, or other measures.
Next, inspect the dates. A fact with start and end describes a duration, such as revenue over a quarter or year. A fact with only end is usually an instant balance measured as of a date, such as assets. Compare like with like: income-statement durations need comparable start and end dates, while balance-sheet amounts are point-in-time values.
Keep form, filed, and accn alongside each value. form identifies the filing type; filed records when the report was filed; and accn identifies the submission. The reporting period end (end) is not the filing date. Amendments and later filings can report a value for a period again, so retain the accession and filing date rather than overwriting older observations without a rule.
Find a filing and convert its XBRL to JSON
Company Facts is convenient for standardized company-wide facts over time. If you need to process a specific report, first identify the filing and retain its accession number and source URL. The SEC’s submissions JSON lists recent filing metadata for a CIK, with older filing-history files referenced when needed. SEC Filing Data’s Query API is another option for searching by ticker and other supported criteria. Send a POST request to https://api.secfilingdata.com/v1/filings/query with the API token in the Authorization header. The SEC Query API documentation lists supported searches, pagination fields, and response details.
Example request payload (this is the JSON you send, not EDGAR output or an API response):
{
"query_type": "ticker",
"query_value": "AAPL",
"from": 0,
"size": 10,
"sort_order": "DESC"
}
SEC Filing Data’s XBRL-to-JSON documentation says its converter accepts a filing URL ending in .htm or .html (including an index page URL), or the associated XBRL .xml URL. It describes a JSON response containing financial statements, cover-page information, and custom items, with standardized sections including income statements, balance sheets, cash flows, and shareholders’ equity. The XBRL to JSON Converter API reference documents those input and output claims.
There is a documentation issue to resolve before implementing that converter request: the reference labels the endpoint POST and provides POST request examples, but a separate line says “Supported HTTP methods: GET.” Because those instructions conflict, do not treat the converter method as verified end-to-end until SEC Filing Data clarifies it. The stated URL input, token requirement, and response description are documented, but the request method is not unambiguous.
Limits to keep in mind
- Standard taxonomy coverage: SEC Company Facts aggregates standard taxonomy concepts for the filing entity. Custom extension tags and segment-specific facts may require the filing’s own XBRL data or another supported filing-specific process.
- Period alignment: Fiscal quarters and years do not always match calendar quarters and years. Frames are calendar-aligned and may include facts whose actual start and end dates differ from the requested calendar frame.
- Units and context: Do not compare amounts until units, duration or instant type, dates, and any relevant context match.
- Filing detail: JSON facts and metadata do not automatically include all prose, footnotes, exhibits, or attachments from a filing submission. The primary document and separate materials may need to be reviewed individually through the filing index.
- Availability: Not every filer, period, concept, or filing produces the same coverage. Check for missing concepts, custom tags, amendments, and changes in how a company labels a measure.
Frequently asked questions
Is SEC EDGAR data available as JSON for free?
The SEC’s public submissions and XBRL data APIs return JSON without an API key. Automated use must still follow the SEC’s fair-access policy and site requirements. Third-party providers may have separate authentication, usage, and licensing terms.
Does Company Facts return a complete income statement?
It returns aggregated facts for supported standard-taxonomy concepts, not necessarily a formatted statement with every line item and contextual disclosure. Use a filing-specific source when you need custom tags, segment details, or the report’s presentation.
How is JSON different from the SEC filing document?
JSON is a structured data representation, such as metadata or tagged facts. An original filing is a submission that may contain a primary document and separate exhibits or attachments. A generated PDF or converted JSON can help with a workflow, but neither replaces the filed documents and their context.
Takeaway: Keep the company identifier, concept, unit, reporting dates, filing form, and accession number with every selected value. That makes comparisons easier to audit and helps you trace a number back to the SEC filing that reported it.
