Package 'secfile'

Title: SEC 'EDGAR' APIs
Description: Simple and efficient access to the SEC's 'EDGAR' APIs <https://www.sec.gov/search-filings> for querying and retrieving filings. The 'secfile' package abstracts the complexities of interacting with SEC EDGAR APIs, such as session management, user agent declaration, rate limiting, index parsing, pagination of filing metadata, URL construction, document caching, and inline XBRL parsing. This abstraction allows users to focus on retrieving data rather than managing API details. Use cases include retrieving data across a range of workflows such as indexes, tenures, submissions, and facts. The package supports flexible query capabilities, including customizable form types, date ranges, and dimensions, and validates the retrieved data automatically. It handles the SEC's fair access requirements, such as user agent declaration and rate limiting between requests, and caches downloaded documents for efficient retrieval of large datasets. The implementation uses standard HTTP libraries to handle API interactions efficiently and supports both R and 'Python' to make it accessible for a broad audience.
Authors: Jason Foster [aut, cre]
Maintainer: Jason Foster <[email protected]>
License: GPL (>= 2)
Version: 0.1.2
Built: 2026-10-06 08:04:28 UTC
Source: https://github.com/jasonjfoster/file

Help Index

SEC 'EDGAR' APIs

Description

Simple and efficient access to the SEC's 'EDGAR' APIs <https://www.sec.gov/search-filings> for querying and retrieving filings. The 'secfile' package abstracts the complexities of interacting with SEC EDGAR APIs, such as session management, user agent declaration, rate limiting, index parsing, pagination of filing metadata, URL construction, document caching, and inline XBRL parsing. This abstraction allows users to focus on retrieving data rather than managing API details. Use cases include retrieving data across a range of workflows such as indexes, tenures, submissions, and facts. The package supports flexible query capabilities, including customizable form types, date ranges, and dimensions, and validates the retrieved data automatically. It handles the SEC's fair access requirements, such as user agent declaration and rate limiting between requests, and caches downloaded documents for efficient retrieval of large datasets. The implementation uses standard HTTP libraries to handle API interactions efficiently and supports both R and 'Python' to make it accessible for a broad audience.

Details

secfile is a package that provides simple and efficient access to the SEC's EDGAR APIs for querying and retrieving filings.

The core functionality of the secfile package abstracts the complexities of interacting with SEC EDGAR APIs, such as session management, user agent declaration, rate limiting, index parsing, pagination of filing metadata, URL construction, document caching, and inline XBRL parsing. This abstraction allows users to focus on retrieving data rather than managing API details. Use cases include retrieving data across a range of workflows:

  • Indexes: master index of all filings by form type and date for universe construction

  • Tenures: status windows built by pairing entry and exit form filings

  • Submissions: filing metadata for any filer with form type and date range filters

  • Facts: investment-level or company-level facts extracted from inline XBRL filings

The implementation uses standard HTTP libraries to handle API interactions efficiently and supports both R and Python to make it accessible for a broad audience.

Author(s)

Jason Foster [aut, cre]

Create Tenures for the SEC EDGAR APIs

Description

A function to create status windows ("tenures") by pairing entry and exit form filings for each filer (e.g., exchange listing registration and removal).

Usage

create_tenures(data, entry_form, exit_form)

Arguments

data

data frame. Data that contains the company, CIK, form, date, and link for each filing created using the get_index function.
entry_form

string or character vector. Form type or vector of form types that start a tenure (e.g., "8-A12B").
exit_form

string or character vector. Form type or vector of form types that end a tenure (e.g., "25" and "25-NSE").

Value

A data frame that contains the company, CIK, start date, end date, start link, and end link for each tenure. The end date is missing for active tenures.

Examples

## Not run: 
index <- get_index(forms = c("8-A12B", "25", "25-NSE"),
                   user_agent = "[email protected]")

tenures <- create_tenures(index, "8-A12B", c("25", "25-NSE"))

## End(Not run)

Forms Data for the SEC EDGAR APIs

Description

A data frame with the available forms data for the SEC EDGAR APIs sourced from https://www.sec.gov/Archives/edgar/lookup-data.js. Amendments are filed with an "/A" suffix (e.g., "10-K/A").

Usage

data_forms

Format

A data frame.

Items Data for the SEC EDGAR APIs

Description

A data frame with the available items data for the SEC EDGAR APIs sourced from https://www.sec.gov/Archives/edgar/lookup-data.js and supplemented with items adopted after the source was last updated (e.g., "1.05"). Dotted item numbers (e.g., "2.02") apply to current report ("8-K") filings after August 2004 and un-dotted item numbers (e.g., "12") apply to earlier filings.

Usage

data_items

Format

A data frame.

Get CIKs from the SEC EDGAR APIs

Description

A function to get the Central Index Key ("CIK") for one or more tickers from the SEC EDGAR APIs sourced from https://www.sec.gov/files/company_tickers.json. The result can be passed to the get_submissions function. Filers with multiple share classes have one row for each ticker.

Usage

get_ciks(tickers = NULL, user_agent = NULL, session = NULL)

Arguments

tickers

string or character vector. Ticker or vector of tickers to filter, or NULL for all tickers.
user_agent

string. User agent with contact information.
session

list. Session created using the get_session function. When a session is provided, the user_agent argument is ignored.

Value

A data frame that contains the company, CIK, and ticker for each filer.

Examples

## Not run: 
ciks <- get_ciks(c("AAPL", "MSFT"), user_agent = "[email protected]")

## End(Not run)

Get Data from the SEC EDGAR APIs

Description

A function to get facts from inline XBRL filings from the SEC EDGAR APIs using the specified filing metadata.

Usage

get_data(data, dimension = NULL, date = NULL, cache_dir = NULL,
  user_agent = NULL, session = NULL)

Arguments

data

data frame. Filing metadata that contains the CIK, accession number, primary document, and report date for each filing created using the get_submissions function.
dimension

string. Dimension of contexts to match (i.e., "typed", "explicit", or an axis name such as "InvestmentIdentifierAxis"), or NULL for all contexts.
date

string. Date in "YYYY-MM-DD" format to match context periods, or NULL for the report date of each filing. Instant contexts match when the instant equals the date and duration contexts match when the end date equals the date.
cache_dir

string. Directory to cache downloaded XBRL instance documents, or NULL to disable caching.
user_agent

string. User agent with contact information.
session

list. Session created using the get_session function. When a session is provided, the user_agent argument is ignored.

Value

A data frame that contains facts from the SEC EDGAR APIs for the specified filing metadata with the period type, start and end dates, and dimension axes and members for each context.

Examples

## Not run: 
ciks <- get_ciks("AAPL", user_agent = "[email protected]")

submissions <- get_submissions(ciks, user_agent = "[email protected]")

data <- get_data(submissions, user_agent = "[email protected]")

## End(Not run)

Get Index from the SEC EDGAR APIs

Description

A function to get the master index of filings from the SEC EDGAR APIs for a range of years with optional form types.

Usage

get_index(from_year = 1993, to_year = NULL, forms = c("10-K", "10-Q"),
  user_agent = NULL, session = NULL)

Arguments

from_year

integer. Start year (e.g., 1993).
to_year

integer. End year.
forms

string or character vector. Form type or vector of form types to filter (see "data_forms"), or NULL for all form types.
user_agent

string. User agent with contact information.
session

list. Session created using the get_session function. When a session is provided, the user_agent argument is ignored.

Value

A data frame that contains the company, CIK, form, date, and link for each filing.

Examples

## Not run: 
index <- get_index(user_agent = "[email protected]")

## End(Not run)

Get the Handle for the SEC EDGAR APIs

Description

A function to get the handle required to interact with the SEC EDGAR APIs. The SEC requires a user agent that declares contact information (e.g., "[email protected]") for fair access. Sessions are cached by user agent and reused across subsequent calls.

Usage

get_session(user_agent = NULL)

Arguments

user_agent

string. User agent with contact information.

Value

A list containing the following elements:

handle

A curl handle object for subsequent requests.

Examples

session <- get_session("[email protected]")

Get Submissions from the SEC EDGAR APIs

Description

A function to get the filing metadata ("submissions") from the SEC EDGAR APIs for one or more filers with optional form type and date range filters.

Usage

get_submissions(ciks, forms = c("10-K", "10-Q"), from_date = NULL,
  to_date = NULL, user_agent = NULL, session = NULL)

Arguments

ciks

string, numeric, vector, or data frame. CIK or vector of CIKs, or a data frame created using the get_ciks or create_tenures functions that contains a cik column with optional start_date and end_date columns.
forms

string or character vector. Form type or vector of form types to filter (see "data_forms"), or NULL for all form types.
from_date

string. Start date in "YYYY-MM-DD" format.
to_date

string. End date in "YYYY-MM-DD" format.
user_agent

string. User agent with contact information.
session

list. Session created using the get_session function. When a session is provided, the user_agent argument is ignored.

Value

A data frame that contains the filing metadata for the specified filer(s) with the archives URL for each filing.

Examples

## Not run: 
ciks <- get_ciks("AAPL", user_agent = "[email protected]")

submissions <- get_submissions(ciks, user_agent = "[email protected]")

## End(Not run)