> ## Documentation Index > Fetch the complete documentation index at: https://docs.financialdatapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Derived analytics > Financial Data API's own computed signals — surprise indices, COT positioning percentiles, valuation multiples, rates analytics, and a risk-regime composite — served as observations alongside official data. Financial Data API computes a set of analytics on top of its official-source observations and SEC fundamentals, then stores the results and serves them **as observations**, in the same envelope, with the same provenance, as the official data underneath. You read precomputed values, not a live calculator, and each one traces back to the inputs it was built from. This page leads with the derived datasets you can get and the indicator slugs that identify them, then shows how to query them. ## What data is available Every derived dataset is a canonical indicator with its own `indicatorId`, queryable through the standard observation endpoints. Filter by the `category` to pull a whole family. | Family | `category` | Example indicator IDs | What it tells you | | --------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Surprise indices | `surprise` | `inflation_surprise_index`, `growth_surprise_index` | How much recent data beat or missed expectations (standardized, in sigma). | | COT positioning percentiles | `positioning` | `cot_positioning_percentile`, `cot_tff_percentile` | A trader cohort's net positioning as a 3-year historical percentile (0–100) — how stretched it is versus its own history. Full weekly panels: legacy COT since 1992 (972 CFTC contracts), TFF leveraged funds since 2006 (117 financial futures). | | Valuation multiples | `valuation_multiples` | `trailing_pe_ratio`, `earnings_yield`, `dividend_yield`, `price_to_book_ratio`, `ev_to_ebitda_ratio`, `ev_to_sales_ratio`, `peg_ratio` | Equity valuation derived from SEC fundamentals and price inputs, per company. All 13 trailing multiples are daily series from 2007 to today for \~500 US companies, computed from raw as-traded prices and point-in-time TTM fundamentals. | | Central-bank sentiment | `central_bank` | `cb_statement_sentiment`, `cb_statement_sentiment_llm` | Hawk/dove scores for policy statements. The deterministic lexicon feed covers 244 FOMC statements from 1994; the model-scored feed covers 831 statements across the Fed, ECB, Bank of England, Bank of Canada and RBA. See [Central bank sentiment](/apis/central-bank-sentiment). | | Rates analytics | `rates` | `real_yield_10y`, `real_policy_rate`, `policy_cycle_state`, `yield_curve_spread_10y_2y`, `yield_10y_change` | Real rates, curve measures, and policy-cycle state derived from policy rates and yields. | | Risk-regime composite | `risk` | `risk_regime` | A composite signal summarizing the prevailing risk environment. | The catalog is live. Resolve the full set of derived slugs and their categories from `GET /canonical-indicators` (the same registry that lists macro indicators), and treat the examples above as a map rather than an exhaustive list. ### The forecast baseline Financial Data API also computes a **statistical macro forecast baseline** with prediction intervals — its own model output, **never** a vendor, sell-side, or street consensus. Where it is published, it populates the `forecast` field (and its interval bounds) on the relevant macro observation, gated by out-of-sample skill, so a series only carries a forecast where the baseline has earned it. The consensus and forecast numbers used to compute surprise indices are a separate, calendar-sourced input (see [Economic calendar and events](/apis/economic-calendar)), not the baseline. ## How derived analytics work Financial Data API ingests official observations (CPI prints, yields, CFTC positioning) and SEC fundamentals, then a derivation step computes higher-level values and persists them as observations. Because the result is stored: * Reads are fast and stable. You retrieve a value; you do not trigger a computation on request. * Each value is auditable. It carries the same `sourceUrl`, `provider`, and provenance chain as any observation, and you can trace it to the official releases underneath via `GET /provenance/observations/{observationId}`. * The product is read-only. You cannot pass your own formula or change the methodology; you read what Financial Data API has computed. Derived values are served through the **same** observation endpoints as official data — there is no separate calculator API. Query them by `indicatorId` or pull a whole family by `category`. ## Querying derived analytics Send your API key on every request (`x-api-key` header or `Authorization: Bearer`); derived routes require the `data:read` scope. All paths are relative to `https://api.financialdatapi.com`. ### Latest value of a derived series ```bash cURL theme={"theme":"css-variables"} curl "https://api.financialdatapi.com/observations/latest?indicator_id=inflation_surprise_index&country=USA" \ -H "x-api-key: $FINANCIALDATA_API_KEY" ``` ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"} import { FinancialDataApiClient } from "@financialdatapi/client"; const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY }); const { data } = await client.getLatestObservations({ indicator_id: "inflation_surprise_index", country: "USA", }); console.log(data[0].actual, data[0].unit, data[0].periodEnd); ``` ### A derived time series ```bash cURL theme={"theme":"css-variables"} curl "https://api.financialdatapi.com/observations?indicator_id=cot_positioning_percentile&limit=20&order=desc" \ -H "x-api-key: $FINANCIALDATA_API_KEY" ``` ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"} import { FinancialDataApiClient } from "@financialdatapi/client"; const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY }); for await (const obs of client.paginate("/observations", { indicator_id: "trailing_pe_ratio", order: "desc", })) { console.log(obs.periodEnd, obs.actual, obs.unit); } ``` ```json Response theme={"theme":"css-variables"} { "data": [ { "observationId": "obs_inflation_surprise_index_country_usa_2026-05-31", "indicatorId": "inflation_surprise_index", "indicatorName": "Inflation surprise index", "category": "surprise", "country": "USA", "actual": 0.628, "unit": "sigma", "periodEnd": "2026-05-31", "observedAt": "2026-06-12T06:00:00.000Z", "provider": "Financial Data API", "sourceUrl": "https://api.financialdatapi.com", "rawAvailable": true } ], "meta": { "request_id": "8f1c0e2a-6b3d-4f0a-9c11-1d2e3f4a5b6c", "requestId": "8f1c0e2a-6b3d-4f0a-9c11-1d2e3f4a5b6c", "api_version": "v1", "pagination": { "limit": 20, "cursor": null, "next_cursor": null, "has_more": false } }, "requestId": "8f1c0e2a-6b3d-4f0a-9c11-1d2e3f4a5b6c" } ``` Units vary by family: surprise indices are in `sigma`, COT percentiles in `percentile`, valuation multiples are a `ratio` (or `percent` for yields). Always branch on the `unit` field. ## Worked example: gold positioning at the extremes The COT percentile panel is deep enough to test against history. Gold in the week of its August 2011 all-time-high top: ```bash cURL theme={"theme":"css-variables"} curl "https://api.financialdatapi.com/observations?indicator_id=cot_positioning_percentile&entity=instrument_cftc_gold_commodity_exchange_inc&start_date=2011-08-01&end_date=2011-08-05" \ -H "x-api-key: $FINANCIALDATA_API_KEY" ``` That week printed **93.3** (`crowded_long`). The same query over 2015-07-24 to 2015-07-31 returns **2.9** (`crowded_short`) for 2015-07-28 — the cycle bottom. Each row also carries `net`, `weeklyChange`, `percentile1y`, `percentile3y`, and `zScore3y` in metadata. ## FOMC statement sentiment `cb_statement_sentiment` scores every FOMC policy statement on a hawk/dove scale — 244 statements from February 1994 to today, keyed to `country_usa` with one event-frequency row per statement date. The score is deterministic, not model-generated: a versioned lexicon (`fdapi_hawk_dove_v1`) counts hawkish and dovish phrases in the statement text and nets them into a score in \[−1, +1]. `valueText` labels the row `hawkish` (score above 0.2), `dovish` (below −0.2), or `neutral`. Metadata carries a full audit trail: `lexiconVersion`, the matched hawkish and dovish phrases, phrase counts, word count, and `deltaVsPrior` — the change versus the previous statement, which is usually the tradable number. ```bash cURL theme={"theme":"css-variables"} curl "https://api.financialdatapi.com/observations?indicator_id=cb_statement_sentiment&entity=country_usa&start_date=2022-06-01&end_date=2022-06-30" \ -H "x-api-key: $FINANCIALDATA_API_KEY" ``` The series tracks the eras you would expect it to: | Statement | Score | Reading | | ------------------------------------------- | ----- | ------------------------------ | | December 2008 (ZIRP, "all available tools") | −1.0 | Maximally dovish | | July 2019 (the "hawkish cut") | +0.14 | Eased policy, hawkish language | | June 2022 (75bp, inflation fight) | +1.0 | Maximally hawkish | Each row's `sourceUrl` links to the Federal Reserve statement it was scored from, so every value is verifiable against the public-domain original. ## Trace a derived value to its inputs Because every derived value is an observation, it carries full provenance. You can walk from a derived value back to the official releases it was built on — this is what makes derived analytics auditable. Pull the derived value from `GET /observations` (or `/observations/latest`) and capture its `observationId`. Call `GET /provenance/observations/{observationId}` to reach the named source, the source URL, the raw payload reference metadata, and the ingestion run behind it. Raw provider payload bodies are never exposed by the product API. Provenance returns reference metadata (source, URL, ingestion run, raw payload id), not the original payload contents. ## Notes Derived values are precomputed and persisted. The number you read was computed earlier; the request does not recompute it. You cannot pass your own formula or change the methodology through the API. The macro forecast baseline is Financial Data API's own statistical baseline, published with prediction intervals and gated by out-of-sample skill. It is never a vendor, sell-side, or street consensus. Where consensus is available for surprise computation, it comes from the economic calendar and is a separate input. Derived datasets follow the same rights model as the rest of the API, and trace to the same official provenance. Raw vendor and real-time market price-tick data is deliberately not part of the product and is never served on the public surface. ## Related The raw CFTC COT and TFF series behind the positioning percentile. Where the consensus and forecast inputs behind surprise indices come from. The official observations that feed derived values, and how to query them. The SEC fundamentals behind valuation multiples.