sec-data-fetcher

v1.0.2

Published

2 months ago

An npm library to fetch SEC data from all supported endpoints with rate limiting.

Downloads

0High
0Medium
0Low

sebastianboehler

SEC EDGAR API Wrapper finance parsing formatting api data rate-limiting

SEC Data Fetcher

An npm library to fetch SEC data from all supported endpoints with rate limiting, written in TypeScript.

Features

CIK Lookup: Lookup Central Index Key (CIK) using a company's ticker symbol.
Company Data: Retrieve company submission data.
Reports: Fetch recent filings (e.g., 10-Q, 10-K, 8-K) after a specified date.
Company Facts: Get standardized fundamental data.
Parse Filings: Parse SEC filings from URLs or strings into structured objects.
Rate Limiting: Configurable rate limiting to comply with SEC guidelines.
TypeScript Support: Includes types for better TypeScript integration.
Customizable User-Agent: Set your own User-Agent string as required by the SEC.

Installation

npm install sec-data-fetcher

Usage

import { SECClient } from 'sec-data-fetcher';

// Initialize the SECClient with your User-Agent
const secClient = new SECClient({
  userAgent: 'Your Company Name [email protected]',
});

(async () => {
  // Lookup CIK
  const cik = await secClient.cikLookup('AAPL');
  console.log('CIK:', cik);

  if (cik) {
    // Get Company Data
    const companyData = await secClient.getCompanyData(cik);
    console.log('Company Data:', companyData);

    // Get Reports
    const reports = await secClient.getReports(cik);
    console.log('Reports:', reports);

    // Parse a filing from URL
    if (reports.length > 0) {
      const filingUrl = `https://www.sec.gov/Archives/edgar/data/${parseInt(
        cik,
        10,
      )}/${reports[0].accessionNumber.replace(/-/g, '')}/${
        reports[0].primaryDocument
      }`;
      const filingObject = await secClient.getObjectFromUrl(filingUrl);
      console.log('Filing Object:', filingObject);
    }
  }
})();

API Reference

SECClient

Constructor

new SECClient(options: SECClientOptions)

Methods

cikLookup(ticker: string): Promise<string | null>
getCompanyData(cik: string): Promise
getReports(cik: string, after?: Date, forms?: string[]): Promise<Filing[]>
getCompanyFacts(cik: string): Promise
getObjectFromString(content: string): FilingObject
getObjectFromUrl(url: string): Promise
fetchFiling(url: string): Promise
Fetches the raw HTML content of an SEC filing from the provided URL.
extractTablesFromFilingUrl(url: string): Promise<Array<Array<Array>>>
Fetches the filing content from a URL and extracts tables from the filing.
extractTablesFromContent(filingContent: string): Array<Array<Array>>
Extracts tables from the provided raw HTML content of an SEC filing.

Extract Tables from SEC Filings

The package provides two ways to extract tables from SEC filings:

Extract from a URL: Fetch and extract tables directly from an SEC filing URL.
Extract from provided HTML content: Extract tables from the provided HTML content when you already have the filing data.

import { SECClient } from 'sec-data-fetcher';

const secClient = new SECClient({
  userAgent: 'Your Company <[email protected]>',
});

// Extract tables from an SEC filing URL
const tablesFromUrl = await secClient.extractTablesFromFilingUrl(
  'https://www.sec.gov/...',
);

// Extract tables from provided HTML content
const filingContent = '<html>...</html>';
const tablesFromContent = secClient.extractTablesFromContent(filingContent);

Notes

Ensure that you comply with the SEC’s Terms of Use.
All requests include the required headers (User-Agent, Accept-Encoding, and Host).
The library includes rate limiting to prevent exceeding the SEC’s request limits.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT License. See the LICENSE file for details.

Disclaimer

This library is provided as-is and is not affiliated with or endorsed by the U.S. Securities and Exchange Commission. Use this library responsibly and in compliance with the SEC’s Terms of Use.