| Title: | Retrieve Fundamental Financial Data from SEC 'EDGAR' |
|---|---|
| Description: | Provides a simple, ticker-based interface for retrieving fundamental financial data from the United States Securities and Exchange Commission's 'EDGAR' 'XBRL' API <https://www.sec.gov/edgar/sec-api-documentation>. Functions return key financial ratios including earnings per share, return on equity, return on assets, debt-to-equity, current ratio, gross margin, operating margin, net margin, price-to-earnings, price-to-book, and dividend yield for any publicly traded U.S. company. Data is sourced directly from company 10-K annual filings, requiring no API key or paid subscription. Designed for use in quantitative finance courses and research workflows. |
| Authors: | Robert P Schumaker [aut, cre] (ORCID: <https://orcid.org/0000-0003-2977-1856>) |
| Maintainer: | Robert P Schumaker <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.2 |
| Built: | 2026-05-26 06:34:03 UTC |
| Source: | https://github.com/robschumaker/edgarfundamentals |
Translates a stock ticker symbol into the corresponding SEC EDGAR Central Index Key (CIK). The CIK is a unique numerical identifier assigned by the SEC to every company that files with EDGAR. It is required for all subsequent EDGAR API calls.
get_cik(symbol)get_cik(symbol)
symbol |
A character string containing the stock ticker symbol
(e.g. |
Data is retrieved from https://www.sec.gov/files/company_tickers.json, a publicly maintained mapping file updated by the SEC. No API key is required.
The SEC requests that automated tools identify themselves via a User-Agent
header. Set your identifier once per session with:
options(edgarfundamentals.user_agent = "Your Name [email protected]")
A character string containing the CIK number (without zero-padding).
## Not run: options(edgarfundamentals.user_agent = "Jane Smith [email protected]") get_cik("AAPL") get_cik("LLY") ## End(Not run)## Not run: options(edgarfundamentals.user_agent = "Jane Smith [email protected]") get_cik("AAPL") get_cik("LLY") ## End(Not run)
Returns a data frame listing the most recent EDGAR filings of a specified form type for a given company. Useful for verifying that a company has filed the expected number of 10-K or 10-Q reports, or for retrieving accession numbers needed to access specific filings.
get_filing_history(symbol, form_type = "10-K", n = 5)get_filing_history(symbol, form_type = "10-K", n = 5)
symbol |
A character string containing the stock ticker symbol
(e.g. |
form_type |
A character string specifying the SEC form type to
retrieve. Common values are |
n |
An integer specifying the maximum number of filings to return.
Defaults to |
Data is retrieved from the SEC EDGAR submissions API (https://data.sec.gov/submissions/). The API returns up to the 1,000 most recent filings across all form types; older filings may not appear.
Set your User-Agent once per session:
options(edgarfundamentals.user_agent = "Your Name [email protected]")
A data frame with one row per filing and the following columns:
The ticker symbol passed to the function.
The SEC accession number uniquely identifying
the filing (e.g. "0000320193-24-000123").
The date the filing was submitted to EDGAR.
The period-end date covered by the filing.
The form type as recorded in EDGAR.
The filename of the primary HTML document within the filing.
## Not run: options(edgarfundamentals.user_agent = "Jane Smith [email protected]") # Five most recent annual reports for Lockheed Martin get_filing_history("LMT", form_type = "10-K", n = 5) # Most recent quarterly reports for Eli Lilly get_filing_history("LLY", form_type = "10-Q", n = 4) ## End(Not run)## Not run: options(edgarfundamentals.user_agent = "Jane Smith [email protected]") # Five most recent annual reports for Lockheed Martin get_filing_history("LMT", form_type = "10-K", n = 5) # Most recent quarterly reports for Eli Lilly get_filing_history("LLY", form_type = "10-Q", n = 4) ## End(Not run)
Pulls fundamental financial data directly from a company's most recent annual 10-K filing in SEC EDGAR and computes key financial ratios. No API key or paid subscription is required.
get_fundamentals(symbol, to_date = as.character(Sys.Date()))get_fundamentals(symbol, to_date = as.character(Sys.Date()))
symbol |
A character string containing the stock ticker symbol
(e.g. |
to_date |
A character string in |
Financial statement values are extracted from XBRL-tagged 10-K filings via
the SEC EDGAR companyfacts API
(https://data.sec.gov/api/xbrl/companyfacts/). Because data comes
from annual filings, ratios reflect the most recently completed fiscal year
ending on or before to_date, not real-time values.
Fallback XBRL tags are attempted automatically when a company uses a non-standard tag name for a concept. A courtesy pause of 0.5 seconds is inserted after the companyfacts API call to respect the SEC's rate limit of 10 requests per second.
Set your User-Agent once per session:
options(edgarfundamentals.user_agent = "Your Name [email protected]")
A named numeric vector with the following elements:
SEC Central Index Key – the company's unique EDGAR identifier.
Diluted Earnings Per Share (USD per share) from the most recent qualifying 10-K. Falls back to basic EPS if diluted is unavailable.
Net income attributable to the company (USD).
Total revenue (USD).
Return on Equity as a percentage (NetIncome / StockholdersEquity * 100). A measure of how efficiently the company generates profit from shareholder capital.
Return on Assets as a percentage (NetIncome / TotalAssets * 100). A measure of how efficiently the company uses its assets.
Debt-to-Equity ratio (LongTermDebt / StockholdersEquity). A measure of financial leverage.
Current Assets divided by Current Liabilities. A measure of short-term liquidity; values above 1 indicate the company can cover near-term obligations.
Gross Profit as a percentage of Revenue. Measures pricing power and production efficiency.
Operating Income as a percentage of Revenue. Measures operational efficiency before interest and taxes.
Net Income as a percentage of Revenue. Bottom-line profitability after all expenses.
Price-to-Earnings ratio, computed by dividing the most recent
adjusted closing price (from Yahoo Finance via tidyquant) by EPS.
Returns NA if EPS is zero or negative.
Price-to-Book ratio, computed by dividing the most recent
adjusted closing price by Book Value per Share (StockholdersEquity /
SharesOutstanding). Returns NA if shares outstanding is zero
or unavailable.
Dividend Yield as a percentage (DividendsPerShareDeclared /
Price * 100). Returns NA if no dividend data is available.
## Not run: options(edgarfundamentals.user_agent = "Jane Smith [email protected]") # Fundamentals for Eli Lilly as of end of 2024 get_fundamentals("LLY", "2024-12-31") # Fundamentals as of today get_fundamentals("JNJ") ## End(Not run)## Not run: options(edgarfundamentals.user_agent = "Jane Smith [email protected]") # Fundamentals for Eli Lilly as of end of 2024 get_fundamentals("LLY", "2024-12-31") # Fundamentals as of today get_fundamentals("JNJ") ## End(Not run)
A vectorized wrapper around get_fundamentals that accepts a
vector of ticker symbols and returns a tidy data frame with one row per
stock. Failed lookups are recorded as NA rather than stopping
execution, so a single problematic ticker does not interrupt the batch.
get_fundamentals_batch(symbols, to_date = as.character(Sys.Date()))get_fundamentals_batch(symbols, to_date = as.character(Sys.Date()))
symbols |
A character vector of stock ticker symbols
(e.g. |
to_date |
A character string in |
Each symbol requires two SEC EDGAR API calls (one for the CIK lookup and one for the companyfacts data) plus one Yahoo Finance call for the current price. A 0.5-second pause is inserted after each companyfacts call to respect the SEC rate limit of 10 requests per second. For a portfolio of 14 stocks, expect a total retrieval time of approximately 20–30 seconds.
Set your User-Agent once per session:
options(edgarfundamentals.user_agent = "Your Name [email protected]")
A data frame with one row per symbol and the following columns:
symbol, CIK, EPS, NetIncome, Revenue,
ROE, ROA, DE, CurrentRatio,
GrossMargin, OperatingMargin, NetMargin,
PE, PB, DIV. See get_fundamentals
for definitions. Rows where data retrieval failed contain NA
for all ratio columns.
get_fundamentals for single-stock retrieval.
## Not run: options(edgarfundamentals.user_agent = "Jane Smith [email protected]") healthcare <- c("UNH", "PFE", "MRK", "ABT", "LLY", "CVS", "AMGN") get_fundamentals_batch(healthcare, "2024-12-31") defense <- c("LMT", "RTX", "NOC", "GD", "HII", "LHX", "LDOS") get_fundamentals_batch(defense, "2024-12-31") ## End(Not run)## Not run: options(edgarfundamentals.user_agent = "Jane Smith [email protected]") healthcare <- c("UNH", "PFE", "MRK", "ABT", "LLY", "CVS", "AMGN") get_fundamentals_batch(healthcare, "2024-12-31") defense <- c("LMT", "RTX", "NOC", "GD", "HII", "LHX", "LDOS") get_fundamentals_batch(defense, "2024-12-31") ## End(Not run)