Yield Analysis API

Retrieve yield analysis ratios for any publicly traded company. This endpoint returns cash-flow-based yield metrics that measure how much cash a company returns to shareholders relative to its market valuation, including free cash flow yield, shareholder yield, and buyback yield.

Yield ratios provide a cash-flow-centric view of investment returns that goes beyond traditional dividend yield. Free cash flow yield shows the percentage of a company's market cap generated as free cash flow each year, making it a powerful alternative to P/E ratios for valuation. Shareholder yield combines dividends and buybacks into a single metric that captures total capital returned to shareholders. These ratios are particularly favored by value investors and quantitative strategies because cash flows are harder to manipulate than accounting earnings.

Data is available for both annual and quarterly periods, with up to 250 historical periods per request.

GEThttps://api.roic.ai/v2/fundamental/ratios/yield-analysis/{identifier}

Parameters

Path Parameters

identifierstringrequired

Company identifier — supports ticker symbol (e.g., `AAPL`), CIK, CUSIP, or ISIN.

Example: AAPL

Query Parameters

apikeystringrequired

Your API key for authentication.

periodstringoptional

Reporting period for financial data.

Default: annualValues: annual, quarterly

limitnumberoptional

Maximum number of periods to return.

Default: 10Example: 10

fiscal_year_startnumberoptional

Filter results starting from this fiscal year.

Example: 2020

fiscal_year_endnumberoptional

Filter results ending at this fiscal year.

Example: 2024

date_startstringoptional

Filter results starting from this date (YYYY-MM-DD format).

Example: 2020-01-01

date_endstringoptional

Filter results ending at this date (YYYY-MM-DD format).

Example: 2024-12-31

orderstringoptional

Sort order for time-series data.

Default: DESCValues: ASC, DESC

formatstringoptional

Response format. Use `json` for JSON (default) or `excel` for tab-separated values compatible with Google Sheets and Excel.

Default: jsonValues: json, excel

Code Examples

curl "https://api.roic.ai/v2/fundamental/ratios/yield-analysis/AAPL?apikey=YOUR_API_KEY"

Response

Response200 OK

[
  {
    "ticker": "AAPL",
    "date": "2025-09-30",
    "period": "annual",
    "period_label": "2025",
    "fiscal_year": "2025",
    "currency": "USD",
    "ttm_cash_from_oper": 111482000000,
    "ttm_cap_expend": -12715000000,
    "ttm_free_cash_flow": 124197000000,
    "free_cash_flow_yield": 3.250680646517491,
    "cf_dvd_paid": -15421000000,
    "cf_proc_fr_repurch_eqty_detailed": -90711000000,
    "cf_pymt_debt_and_capital_lease": -10932000000,
    "cf_other_financing_act_excl_fx": -8103000000,
    "ttm_cff": -120686000000,
    "shareholder_yield_cff": 3.1706602465687643,
    "returned_capital_ex_debt": 106132000000,
    "shareholder_yield_ex_debt": 2.788297841413553,
    "cf_cash_from_oper": 111482000000,
    "cf_cap_expenditures": -12715000000,
    "cf_free_cash_flow_firm": 98767000000,
    "enterprise_value": 3850296555000,
    "ttm_fcf_to_firm_yield": 3.225647641055534,
    "capital_yield": 3.134459859806825
  }
]

Field Dictionary

Field	Description
`ttm_cash_from_oper`	TTM cash from operations
`ttm_cap_expend`	TTM capital expenditures
`ttm_free_cash_flow`	TTM free cash flow
`free_cash_flow_yield`	Free cash flow yield
`cf_dvd_paid`	Dividends paid
`cf_proc_fr_repurch_eqty_detailed`	Net share repurchases
`cf_pymt_debt_and_capital_lease`	Debt & capital lease payments
`cf_other_financing_act_excl_fx`	Other financing activities
`ttm_cff`	TTM cash from financing
`shareholder_yield_cff`	Shareholder yield (CFF-based)
`returned_capital_ex_debt`	Returned capital excluding debt
`shareholder_yield_ex_debt`	Shareholder yield excluding debt
`cf_cash_from_oper`	Cash from operations
`cf_cap_expenditures`	Capital expenditures
`cf_free_cash_flow_firm`	Free cash flow to firm
`enterprise_value`	Enterprise value
`ttm_fcf_to_firm_yield`	TTM FCF to firm yield
`capital_yield`	Capital yield

Metadata

Field	Description
`ticker`	Company ticker symbol
`date`	Period end date
`period`	Reporting period (e.g. Annual, Quarterly)
`period_label`	Human-readable period label
`fiscal_year`	Fiscal year
`currency`	Reporting currency

Yield Interpretation

FCF Yield	Signal
Above 8%	Potentially undervalued. generating significant cash relative to market price
4% - 8%	Moderate yield. typical for mature, cash-generative businesses
Below 4%	Lower yield. may indicate growth-stage pricing or capital-intensive operations

Use Cases

Screen for high free cash flow yield stocks as value investment candidates
Build shareholder yield strategies that capture both dividends and buybacks
Compare FCF yield across sector peers to identify the most attractively priced cash generators
Track buyback yield trends to identify companies aggressively repurchasing shares
Use cash flow yield as a valuation metric that is more resistant to accounting manipulation than P/E

Profitability Ratios - margins and payout ratio that drive yield metrics
Valuation Multiples - P/E and EV/EBITDA for complementary valuation context
Cash Flow Statement - raw free cash flow and capital allocation data
Per-Share Data - dividends per share and EPS for per-share yield calculations