| Type: | Package |
| Title: | SEC 'EDGAR' APIs |
| Version: | 0.1.1 |
| 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 filings 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 automatic data validation. It handles the SEC's fair access requirements automatically, 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 is available in both R and 'Python' for accessibility to a broad audience. |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| URL: | https://github.com/jasonjfoster/file |
| BugReports: | https://github.com/jasonjfoster/file/issues |
| Depends: | R (≥ 3.5.0) |
| Imports: | curl, jsonlite, xml2 |
| Suggests: | covr, testthat |
| Config/roxygen2/old_usage: | TRUE |
| Config/roxygen2/version: | 8.0.0 |
| Encoding: | UTF-8 |
| LazyData: | true |
| NeedsCompilation: | no |
| Packaged: | 2026-08-03 11:16:20 UTC; jason |
| Author: | Jason Foster [aut, cre] |
| Maintainer: | Jason Foster <jason.j.foster@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-08-08 12:30:02 UTC |
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 filings 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 automatic data validation. It handles the SEC's fair access requirements automatically, 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 is available in both R and 'Python' for accessibility to a broad audience.
Details
secfile is a package that provides simple and efficient access to the SEC's EDGAR functionality 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 filings 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 leverages standard HTTP libraries to handle API interactions efficiently and provides support for both R and Python to ensure accessibility 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 |
entry_form |
string. Form type that starts a tenure (e.g., "8-A12B"). |
exit_form |
string. Form type that ends a tenure (e.g., "25"). |
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"), user_agent = "username@domain.com")
tenures <- create_tenures(index, "8-A12B", "25")
## 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. Ticker or vector of tickers to filter
or |
user_agent |
string. User agent with contact information. |
session |
list. Session created using the |
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 = "username@domain.com")
## 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 |
dimension |
string. Dimension of contexts to match (i.e., "typed",
"explicit", or an axis name such as "InvestmentIdentifierAxis")
or |
date |
string. Date in "YYYY-MM-DD" format to match context periods
or |
cache_dir |
string. Directory to cache downloaded XBRL instance documents
or |
user_agent |
string. User agent with contact information. |
session |
list. Session created using the |
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 = "username@domain.com")
submissions <- get_submissions(ciks, user_agent = "username@domain.com")
data <- get_data(submissions, user_agent = "username@domain.com")
## 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. Form type or vector of form types to filter
(see |
user_agent |
string. User agent with contact information. |
session |
list. Session created using the |
Value
A data frame that contains the company, CIK, form, date, and link for each filing.
Examples
## Not run:
index <- get_index(user_agent = "username@domain.com")
## 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., "username@domain.com") 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("username@domain.com")
Get Submissions from the SEC EDGAR APIs
Description
A function to get the filing metadata ("submissions") from the SEC EDGAR APIs for filers with optional form types and date range.
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, or data frame. CIK or vector of CIKs, or a data
frame that contains a |
forms |
string. Form type or vector of form types to filter
(see |
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 |
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 = "username@domain.com")
submissions <- get_submissions(ciks, user_agent = "username@domain.com")
## End(Not run)