Metric series endpoint

Endpoint

GET https://tgmcharts.com/api/v1/series/{symbol}/{metric} returns one metric's stored history for one symbol. One slug is one series with one basis (daily, monthly, annual, quarterly, or TTM — the catalogue below states each one; a series is never described as denser than it is stored). Keyless and CORS-open; unknown query keys answer 400.

curl -s "https://tgmcharts.com/api/v1/series/KO/pe-ratio?years=10"

curl -s "https://tgmcharts.com/api/v1/series/KO/pe-ratio?years=10&format=csv" -o ko-pe-ratio.csv

curl -s https://tgmcharts.com/api/v1/series/AAPL/revenue

Response shape

A type sketch, not a live response — the docs do not print numbers that were not read from the data store. methodology is the registry's computation note for the slug, served verbatim; source appears only on the EDGAR-lane metrics.

{
  "symbol": "KO",
  "name": string | null,
  "metric": "pe-ratio",
  "label": "P/E Ratio",
  "unit": "usd" | "usdPerShare" | "percent" | "ratio",
  "basis": "daily" | "monthly" | "annual" | "quarterly" | "ttm",
  "methodology": string,               // the registry's computation note, verbatim
  "source": "sec-edgar-companyfacts",  // present on EDGAR-lane metrics only
  "asOf": ISO date-time | null,
  "years": integer | null,             // the ?years= you asked for
  "points": [ { "date": "YYYY-MM-DD", "value": number }, … ] | null,
  "applicability": "applicable" | { "tone": "hard" | "soft", "message": string },
  "note": string,                      // present when points is null or []
  "links": { "chart": string | null, "page": string, "docs": string, "openapi": string }
}

Honest states

• points: null with applicability: { tone: "hard", … } — the metric is intentionally withheld for the company type (EV and FCF families on banks, insurers, REITs and funds). The message says why.
• points: [] with a note — the symbol is covered but no history is stored for this metric yet (or, on the EDGAR lane, no SEC XBRL fact maps to it). An honest gap, not a zero.
• EDGAR-lane metrics on a symbol whose SEC data is still being ingested answer 200, points: [], a preparing note, and a short s-maxage=120 cache so the state is not outlived by the edge.
• 404 for an uncovered symbol (onboarding hint), and 404 for a slug that is not in the series tier — the body lists every valid seriesMetrics slug and links the OpenAPI document.

Metric catalogue

Generated from the same registry the endpoint reads, so a slug listed here resolves. Series-tier slugs (JSON/CSV): pe-ratio, ps-ratio, pb-ratio, pfcf-ratio, pocf-ratio, ev-ebitda, ev-ebit, ev-sales, ev-fcf, ev-assets, earnings-yield, fcf-yield, ebitda-yield, ocf-yield, dividend-yield, total-return, roic, revenue-ttm, net-income-ttm, fcf-ttm, ebitda-ttm, capex-ttm, buybacks-ttm, sbc-ttm, rd-ttm, gross-margin-quarterly, operating-margin-quarterly, net-margin-quarterly, revenue, net-income, capex, buybacks, stock-based-comp, r-and-d, revenue-quarterly, net-income-quarterly. Chart-only slugs (PNG via the charts endpoint, JSON pending EDGAR coverage): eps, free-cash-flow, ebitda, gross-margin, operating-margin, profit-margin, roe, roa, eps-quarterly, fcf-quarterly.

Source: TGMCharts-computed series are derived by TGMCharts from licensed end-of-day market data and reported statements (daily valuation and yield lines, rolling TTM flows, quarterly margins, ROIC, total return). SEC EDGAR entries (revenue, net-income, capex, buybacks, stock-based-comp, r-and-d, revenue-quarterly, net-income-quarterly) are as filed in XBRL company facts, public domain, and carry source: "sec-edgar-companyfacts". See data quality and lineage.

CSV format

?format=csv answers text/csv with the same content: leading # comment lines carry the metric, as-of date, methodology, any applicability/note honest-state signal, and the terms line, followed by a date,value header and one row per stored point at full precision. Readers that honor a comment character (pandas comment="#", R comment.char="#") load it directly.

# TGMCharts — KO P/E Ratio (pe-ratio)
# as of: <ISO date-time>
# methodology: <registry methodology, verbatim>
# terms: https://tgmcharts.com/terms — attribution required (data by TGMCharts, tgmcharts.com)
date,value
<YYYY-MM-DD>,<number>
…