axion-edgartools

edgartools (JavaScript)

JavaScript port of edgartools for working with SEC EDGAR filings.

Setup

cd JS
npm install

Configuration

Before making requests, you must set your SEC EDGAR identity (User-Agent):

import { setIdentity } from 'edgartools';

// Required: Your name and email per SEC guidelines
// See https://www.sec.gov/os/accessing-edgar-data
setIdentity('YourName [e-mail]');

// Or via environment variable:
// EDGAR_IDENTITY="YourName [e-mail]"

Usage

import {
  setIdentity,
  getFilings,
  getByAccessionNumber,
  Company,
  Filing,
} from 'edgartools';

setIdentity('MyApp [e-mail]');

// Get 10-K filings for Q1 2024
const filings = await getFilings(2024, 1, { form: '10-K' });
console.log(`Found ${filings.length} 10-K filings`);

// Filter by company CIK
const appleFilings = filings.filterByCik(320193);

// Get a specific filing by accession number
const filing = await getByAccessionNumber('0000320193-24-000123');

// Get company info
const company = await new Company('AAPL');
await company.load();
console.log(company.name, company.cik);

// Get company filings
const companyFilings = await company.getFilings(20);

// Get financials (revenue, net income, assets, etc. from SEC Company Facts)
const financials = await company.getFinancials();
console.log('Revenue:', financials.getRevenue());
console.log('Net income:', financials.getNetIncome());
const metrics = financials.getFinancialMetrics();

API Overview

Financials

• Financials.fromCik(cik) - Create Financials from CIK (fetches Company Facts)
• company.getFinancials() - Get Financials for a Company/Entity
• getRevenue(periodOffset), getNetIncome(periodOffset), getTotalAssets(periodOffset), etc.
• getOperatingCashFlow(), getCapitalExpenditures(), getFreeCashFlow()
• getSharesOutstandingBasic(), getSharesOutstandingDiluted()
• getFinancialMetrics() - Object with all common metrics and ratios (current_ratio, debt_to_assets)
• NoCompanyFactsFound - Thrown when CIK has no company facts

Filings

• getFilings(year, quarter, options) - Fetch filings index for a quarter
• getByAccessionNumber(accessionNumber) - Get single filing by accession number
• Filing - Represents a single SEC filing
• Filings - Collection of filings with .filterByForm(), .filterByCik(), .filterByDate()

Entity / Company

• Company(ticker) / Entity(identifier) - SEC filer (by ticker or CIK)
• getCompanyTickers() - Ticker to CIK mapping
• findCik(ticker) - Get CIK for a ticker
• findTicker(cik) - Get ticker for a CIK

Forms

• describeForm(form, prependForm) - Human-readable description for SEC form code (e.g. "10-K", "8-K")
• FUND_FORMS - Array of fund form codes (NPORT-P, NPORT-EX)

Earnings (8-K EX-99.1)

• EarningsRelease.fromFiling(filing) - Parse earnings exhibit from an 8-K filing
• getEarningsTables(filing) - Get all financial tables from filing's EX-99.1
• FinancialTable - Parsed table with .dataframe, .scale, .statement_type, .toJSON(), .toMarkdown()
• Scale - UNITS, THOUSANDS, MILLIONS, BILLIONS; detectScale(text)
• StatementType - INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW, etc.
• findEarningsExhibitDocument(indexHtml) - Get EX-99.1 document name from index HTML

Configuration

• setIdentity(str) - Set User-Agent for SEC requests
• configureHttp({ verifySsl, proxy, timeout }) - HTTP client settings
• Environment: EDGAR_BASE_URL, EDGAR_DATA_URL, EDGAR_IDENTITY, EDGAR_VERIFY_SSL, EDGAR_RATE_LIMIT_PER_SEC

Differences from Python edgartools

This is a port of the core functionality. Financials use the SEC Company Facts API (same underlying data as XBRL). The Python library has additional features: full XBRL statement rendering, 13F/proxy/Form D parsing, Rich terminal output, local storage/caching.