sec-edgar-api

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 20 Open GitHub ↗

Fetch and parse SEC earnings reports and other filings. Useful for financial analysis.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SEC Edgar API

Fetch 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

## Installation

```SH
npm install sec-edgar-api
```

## Report Interface

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

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

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
}
```

## Usage

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' })
```

## Resolvers

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                                                                                 |

## Contributing

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: `src/services/ReportParser.ts` (add resolvers to the `resolvers/` directory, import to `/resolver/index.ts`, and add to ReportParser.resolveAll)

### Resources

-   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/

sec-edgar-api

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README