npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

sec-edgar-api

v0.5.1

Published

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

Downloads

486

Readme

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

npm install sec-edgar-api

Report Interface

Reports are all returned as a uniform interface:

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
}

Usage

import package contents

import { secEdgarApi } from 'sec-edgar-api'

You can fetch reports individually directly from the SEC website, (throttled to 10 requests per second)

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