Fetch and parse SEC earnings reports and other filings. Useful for financial analysis.
npm install sec-edgar-apiFetch and parse earnings reports and other documents filed with the SEC using the EDGAR API.
This package is focused on the earnings reports for stock analysis.
Some main data points available include:
- Earnings Reports
- Insider Transactions
- Institutional Holders
- Filing History
- Directors & Executives
- Executive Compensation
``SH`
npm install sec-edgar-api
Reports are all returned as a uniform interface:
`TS
interface ReportTranslated {
cik: number
url: string | null
dateReport: string
dateFiled: string
fiscalPeriod: FiscalPeriod
fiscalYear: number
splitDate: string | null
splitRatio: number | null
assetTotal: number | null
assetCurrent: number | null
assetCurrentCashEquivalents: number | null
assetCurrentInvestments: number | null
assetCurrentAccountsReceivable: number | null
assetCurrentInventory: number | null
assetNonCurrent: number | null
assetNonCurrentPPENet: number | null
assetNonCurrentPPEGross: number | null
assetNonCurrentInvestments: number | null
assetNonCurrentGoodwill: number | null
assetNonCurrentIntangibleLessGoodwill: number | null
liabilityTotal: number | null
liabilityCurrent: number | null
liabilityCurrentAccountsPayable: number | null
liabilityCurrentDebt: number | null
liabilityNonCurrent: number | null
liabilityNonCurrentDebt: number | null
equityTotal: number | null
equityRetainedEarnings: number | null
sharesOutstanding: number | null
sharesOutstandingDiluted: number | null
eps: number | null
epsDiluted: number | null
ebit: number | null
ebitda: number | null
profitGross: number | null
revenueTotal: number | null
revenueCost: number | null
revenueOperating: number | null
expenseTotal: number | null
expenseOperating: number | null
expenseResearchDevelopment: number | null
expenseInterest: number | null
expenseDepreciation: number | null
expenseTax: number | null
expenseDepreciationAccumulated: number | null
expenseStockCompensation: number | null
expenseNonCashOther: number | null
expenseSellingGeneralAdministrative: number | null
incomeOperating: number | null
incomeNet: number | null
incomePretax: number | null
cashFlowFree: number | null
cashFlowDividendsPaid: number | null
cashFlowDividendsPaidPreferred: number | null
cashFlowOperating: number | null
cashFlowInvesting: number | null
cashFlowFinancing: number | null
cashFlowCapex: number | null
cashFlowDeferredTax: number | null
cashFlowWorkingCapitalNonCash: number | null
}
`
import package contents
`TS`
import { secEdgarApi } from 'sec-edgar-api'
You can fetch reports individually directly from the SEC website, (throttled to 10 requests per second)
`TS`
// returns array of ReportWrapper (which implements ReportTranslated)
const reports = await secEdgarApi.getReports({ symbol: 'AAPL' })
The main problem with the edgar API is that the property names and data provided are not uniform. You have to deal with companies omitting important data
in some filings, or using different property keys for the same data point.
Resolvers attempt to get information from each report and output a uniform interface. The resolvers will calculate missing data if there is other data that can be used to derive from.
| Resolver | Formula used to derive values |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| resolveAssetCurrent | assetTotal - assetNonCurrent = assetCurrent |
| resolveAssetNonCurrentPpeGross | assetNonCurrentPPENet + expenseDepreciationAccumulated = assetNonCurrentPpeGross |
| resolveCashFlowCapex | Q1 + Q2 + Q3 + Q4 = FY (if FY known, divides evenly between missing quarters) |
| resolveCashFlowFree | cashFlowOperating - cashFlowCapex = cashFlowFree |
| resolveCashFlowOperating | incomeNet + expenseDepreciation - changeInWorkingCapitalNonCash = cashFlowOperating |
| resolveCashFlowWorkingCapitalNonCash | (assetCurrent - assetCurrentCashEquivalents) - (liabilityCurrent - liabilityCurrentDebt) = cashFlowWorkingCapitalNonCash |
| resolveEbit | expenseDepreciation + ebitda = ebit |
| resolveExpenseDepreciation | (expenseDepreciationFY / assetNonCurrentPpeGrossFY) x assetNonCurrentPpeGross = expenseDepreciation |
| resolveExpenseOperating | revenueTotal - incomeOperating - revenueCost = expenseOperating |
| resolveExpenseTotal | revenueTotal - incomeNet = expenseTotal |
| resolveFiscalYearCumulativeProperties | Q1 + Q2 + Q3 + Q4 = FY (for quarterly properties that add to annual) |
| resolveQ4FiscalYearMatchingProperties | Q4 = FY (for non-cumulative properties such as sharesOutstanding) |
| resolveRevenueTotal | revenueCost + profitGross = revenueTotal |
Getting all the properties in a uniform interface accurately is proving to be very difficult due to the differences in all the reports.
Please contribute if you know how to improve this.
Files for mapping & resolving properties:
- Mapping properties: src/util/key-translations.ts
- Resolving properties: (add resolvers to the resolvers/ directory, import to /resolver/index.ts`, and add to ReportParser.resolveAll)
- XBRL Taxonomies: https://xbrl.us/xbrl-taxonomy/2024-us-gaap/
- Validate resolved values: https://finance.yahoo.com/
- Financial calculations: https://www.gurufocus.com/
- Calculate change in working capital: https://www.oldschoolvalue.com/stock-valuation/change-in-working-capital/