Background Question

[eweisbrod]

Hi,

Not sure if this is the right place to ask this, but giving this a shot: What is the difference between the datasets used in these examples and the companyfacts data zip files here https://www.sec.gov/search-filings/edgar-application-programming-interfaces ?

It seems like it might be easier to work with these zipped json files unless i am missing something by doing so?

Thanks for any advice you might have,
~Eric

[sec-gov]

Eric,
They are quite different.
As stated on this page https://www.sec.gov/search-filings/edgar-application-programming-interfaces :

The following XBRL APIs aggregate facts from across submissions that

• Use a non-custom taxonomy (e.g. us-gaap, ifrs-full, dei, or srt)
• Apply to the entire filing entity

---

This API returns all the company concepts data for a company into a single API call:
https://data.sec.gov/api/xbrl/companyfacts/CIK0000789019.json

So a single call goes as far back as the underlying XBRL data is available and trims it further to fit the quarterly 'data frames" for each quarter and fiscal year (although this is not always done consistently), as well as removing duplicates that arise from the same numbers reported in subsequent filings. Furthermore, the API leaves out the vast majority of the content of the monthly CSV files, which contain, for each separate filing of the month in question:

• Dimensioned facts
• Non-numeric (text, date, etc.) facts
• Facts in namespaces from other EDGAR standard taxonomies such as cef, ecd, and cef (see https://www.sec.gov/data-research/structured-data/taxonomies-schemas).)
• Facts in namespaces defined by the filer.

Each monthly data set zip file (https://www.sec.gov/data-research/sec-markets-data/financial-statement-data-sets ) contains a copy of a readme.htm file to detail the data structure and meaning of each table and column.

Aggregation across time is up to the data user, although the data model has not changed since 2013.

The API warrants some caution; for most companies, even the primary financial statement data points (balance sheet, income statement, changes in equity) may be incomplete as a result of the API's selection criteria.

Thanks for your interest!

[eweisbrod]

Thank you so much for getting back to me! This is really helpful. I have been thinking through it, and it seems like there are pros and cons to each approach. However, now I better understand the different datasets. I had been mentally comparing the smaller financial statements dataset against the API, but now I realize there is a larger AND NOTES dataset as well.

[sophymarine]

The zipped companyfacts files are usually the faster path if your goal is point-in-time extraction from EDGAR, especially for repeat analysis. The main tradeoff is that the example datasets often wrap extra curation or normalization around the raw source, so you may miss a bit of reproducibility or encounter edge cases the notebooks already handled. If you only need standardized facts for a small pipeline, the zip files are likely enough; if you want to compare outputs against the example code exactly, follow the notebook’s data path first and then simplify once the mapping is clear.