% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_fundamentals.R
\name{get_fundamentals}
\alias{get_fundamentals}
\title{Retrieve key fundamental financial ratios for a single stock}
\usage{
get_fundamentals(symbol, to_date = as.character(Sys.Date()))
}
\arguments{
\item{symbol}{A character string containing the stock ticker symbol
(e.g. \code{"LLY"}). Case-insensitive.}

\item{to_date}{A character string in \code{"YYYY-MM-DD"} format. The
function returns ratios from the most recent 10-K with a period end date
on or before this date. Defaults to today's date.}
}
\value{
A named numeric vector with the following elements:
\describe{
  \item{CIK}{SEC Central Index Key -- the company's unique EDGAR identifier.}
  \item{EPS}{Diluted Earnings Per Share (USD per share) from the most recent
    qualifying 10-K. Falls back to basic EPS if diluted is unavailable.}
  \item{NetIncome}{Net income attributable to the company (USD).}
  \item{Revenue}{Total revenue (USD).}
  \item{ROE}{Return on Equity as a percentage (NetIncome / StockholdersEquity
    * 100). A measure of how efficiently the company generates profit from
    shareholder capital.}
  \item{ROA}{Return on Assets as a percentage (NetIncome / TotalAssets
    * 100). A measure of how efficiently the company uses its assets.}
  \item{DE}{Debt-to-Equity ratio (LongTermDebt / StockholdersEquity). A
    measure of financial leverage.}
  \item{CurrentRatio}{Current Assets divided by Current Liabilities. A
    measure of short-term liquidity; values above 1 indicate the company
    can cover near-term obligations.}
  \item{GrossMargin}{Gross Profit as a percentage of Revenue. Measures
    pricing power and production efficiency.}
  \item{OperatingMargin}{Operating Income as a percentage of Revenue.
    Measures operational efficiency before interest and taxes.}
  \item{NetMargin}{Net Income as a percentage of Revenue. Bottom-line
    profitability after all expenses.}
  \item{PE}{Price-to-Earnings ratio, computed by dividing the most recent
    adjusted closing price (from Yahoo Finance via tidyquant) by EPS.
    Returns \code{NA} if EPS is zero or negative.}
  \item{PB}{Price-to-Book ratio, computed by dividing the most recent
    adjusted closing price by Book Value per Share (StockholdersEquity /
    SharesOutstanding). Returns \code{NA} if shares outstanding is zero
    or unavailable.}
  \item{DIV}{Dividend Yield as a percentage (DividendsPerShareDeclared /
    Price * 100). Returns \code{NA} if no dividend data is available.}
}
}
\description{
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.
}
\details{
Financial statement values are extracted from XBRL-tagged 10-K filings via
the SEC EDGAR companyfacts API
(\url{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 \code{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:
\code{options(edgarfundamentals.user_agent = "Your Name your@email.com")}
}
\examples{
\dontrun{
options(edgarfundamentals.user_agent = "Jane Smith jane@example.com")

# Fundamentals for Eli Lilly as of end of 2024
get_fundamentals("LLY", "2024-12-31")

# Fundamentals as of today
get_fundamentals("JNJ")
}

}
