Financial Data API — Documentation

Financial Data API’s macro factor data is a set of canonical economic indicators, each with a stable ID that means the same thing in every country. Query US CPI, UK unemployment, and German GDP growth with the same indicator slugs and the same filters, and join across countries without reconciling vendor field names. This page leads with the data that is available (the indicator families, the real series in each, and the country coverage), then shows how to read it through the two observation endpoints.

What data is available

Public canonical indicators are grouped into families. The counts and series below describe the macro families (interest rates have their own page). The catalog is live, so treat the table as a map and read the authoritative, machine-readable list from GET /canonical-indicators and the breadth summary from GET /coverage.

Family	Indicators	Real series in this family
`inflation`	13	CPI Inflation YoY, Core CPI, CPI index, Core CPI index, PCE Price Index, Core PCE Price Index, Producer Price Index (PPI), plus per-country CPI YoY (US, Euro Area, UK, Japan, and more).
`labor`	11	Unemployment Rate, Nonfarm Payroll Employment, Initial Jobless Claims, plus per-country unemployment.
`growth`	9	Real GDP Growth and GDP Growth, per country.
`housing`	2	Housing Starts, Building Permits (US).
`external`	3	Trade Balance, Exports, Imports (US).
`income`	1	Personal Income (US).
`consumption`	1	Retail Sales (US).

Interest-rate series (Policy Rate, 3-Month Money-Market Benchmark Rate, 10-Year Government Bond Yield, and the 10Y-3M Yield-Curve Spread) live in the rates family. See Interest rates.

Units you will see

Macro values carry an explicit unit. Across these families the units are:

percent

Rates of change and ratios: CPI Inflation YoY, Real GDP Growth, Unemployment Rate.

index

Level indices: CPI index, Core CPI index, PCE Price Index.

thousands

Counts in thousands: Nonfarm Payroll Employment, Initial Jobless Claims, Housing Starts, Building Permits.

persons

Headcounts reported in persons where the source publishes them that way.

USD millions

External-sector flows: Trade Balance, Exports, Imports.

Always branch on the unit field rather than assuming. The same family can mix a rate (percent) and a level (index), and a count series can be reported in thousands or persons depending on the source.

Country coverage

The macro catalog spans 17 countries and region codes, keyed by ISO 3166-1 alpha-3 code. Per-country breadth varies — a core set (USA, the euro area, GBR, JPN, AUS, CAN, CHE, NZL) carries the full factor set, others a subset:

ARE AUS CAN CHE DEU EUR GBR HKG JPN KOR
NOR NZL QAT SAU SGP SWE USA

Coverage is not uniform across every series. Some indicators (for example Housing Starts, Building Permits, Trade Balance, Personal Income, Retail Sales) are US-only in the catalog, while CPI Inflation YoY, Unemployment Rate, and GDP Growth are broad. Check exactly what a country carries with GET /coverage, and resolve the live indicator universe with GET /canonical-indicators.

Financial Data API publishes official daily FX reference rates (the fx category), but it does not sell raw vendor or real-time market price-tick data: that is redistribution-blocked and deliberately not part of the product. For derived rate analytics (curve spreads and more) see Derived analytics.

Canonical indicator IDs

Every series has a canonical indicator ID, a stable slug that is identical across countries. You query by it, you join on it, and you read it back on every observation as indicatorId. Examples:

Indicator ID	Indicator	Typical unit
`cpi_inflation_yoy`	CPI Inflation, year over year	`percent`
`unemployment_rate`	Unemployment Rate	`percent`
`gdp_growth`	GDP Growth	`percent`

These three are illustrative, not the full set. The complete, current list of indicator IDs (with names, families, and units) is served live:

curl -s "https://api.financialdatapi.com/canonical-indicators" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

const indicators = await client.listIndicators();
for (const ind of indicators.data) {
  console.log(ind.indicatorId, ind.category, ind.unit);
}

Use GET /canonical-indicators as the source of truth for valid IDs before you build queries. Financial Data API fails closed on unknown query parameters and rejects nonexistent indicators with bad_request, so confirming the slug first saves a round trip.

Querying the data

Macro indicator values are served as observations. An observation is a single value a series describes for a single period, for example May 2026 US CPI Inflation YoY. Two public endpoints cover the two shapes you need: a time series, and the latest value per indicator.

GET /observations

The history. Time series of public observations across periods and vintages. Cursor-paginated.

GET /observations/latest

The snapshot. The single latest public reading per canonical indicator. The fastest way to ask “where are things now.”

Both endpoints go to https://api.financialdatapi.com, require a key with the data:read scope, and send the key in the x-api-key header (or Authorization: Bearer). They share one filter set and one response shape.

Authentication

-H "x-api-key: $FINANCIALDATA_API_KEY"

A data:read scope is required. A handful of endpoints need no key (/health, /ready, /openapi.json, /llms.txt, /llms-full.txt), but the observation endpoints are not among them. See Authentication.

Filters

Both endpoints accept the same filters. Combine them freely; they are AND-ed. Unknown query parameters are rejected with bad_request (Financial Data API fails closed rather than silently ignoring typos).

string

ISO 3166-1 alpha-3 country code, for example USA, GBR, JPN. One of the covered countries.

string

Canonical indicator slug, for example cpi_inflation_yoy. Also accepted as indicator_id.

string

Publication cadence: daily, weekly, monthly, quarterly, or annual.

string

Keep only readings with a given freshness label: fresh, stale, or unknown. The label is set by a per-frequency age gate, independent of any source self-report.

string

Financial Data API source id, for example source_bls_public_api. Filter to a single institution of record.

string

Financial Data API provider id or name. Also accepted as provider.

Time filters run on two axes (period: what a value describes; knowledge-time: when it became known):

string

Convenience filter on the described period: YYYY, YYYY-MM, or YYYY-Qn.

string

Upper bound on the described period (YYYY-MM-DD).

string

Lower bound on knowledge-time (observed_at).

string

Upper bound on knowledge-time (observed_at).

string

Returns the latest vintage known on or before a timestamp. See the caveat below.

integer

Page size, 1 to 500. Defaults to 100. Follow meta.pagination.next_cursor with cursor while has_more is true. sort and order (asc, desc) control ordering.

as_of currently approximates the ingestion timestamp, not full provider-vintage reconstruction. Revisions are retained and never overwritten, so the revision history is visible, but reconstructing the exact value a provider had published at an arbitrary past instant is future work. Read as_of as “what Financial Data API knew by this time.”

Response fields

Public observations come back in camelCase. The fields most relevant to macro indicators:

string

Stable ID for this observation. Pass it to GET /provenance/observations/{observationId} for the full source chain.

string

Canonical indicator slug, for example cpi_inflation_yoy. Use it to query and join across countries.

string

Human-readable indicator name, for example CPI Inflation (YoY).

string

ISO 3166-1 alpha-3 country code.

number

The headline numeric value of the reading.

string

Unit of the value, for example percent, index, thousands, persons, USD millions.

string

Label for the period the value describes, for example 2026-05.

string

End of the described period (YYYY-MM-DD).

string

Publication cadence: daily, weekly, monthly, quarterly, or annual.

string

Knowledge-time: the point at which the value is observed.

string

Freshness label: fresh, stale, or unknown.

string

The provider name behind the source, for example U.S. Bureau of Labor Statistics.

string

The official source URL for the series.

boolean

Whether a raw payload reference is exposed for this observation through the provenance endpoint.

Examples

Latest US CPI inflation

Get the single latest US CPI Inflation YoY reading.

curl -s "https://api.financialdatapi.com/observations/latest?country=USA&indicator=cpi_inflation_yoy" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

const { data } = await client.getLatestObservations({
  country: "USA",
  indicator: "cpi_inflation_yoy",
});

console.log(data[0].actual, data[0].unit, data[0].period);

A public observation looks like this:

{
  "data": [
    {
      "observationId": "obs_us_cpi_inflation_yoy_2026_05",
      "indicatorId": "cpi_inflation_yoy",
      "indicatorName": "CPI Inflation (YoY)",
      "country": "USA",
      "actual": 3.4,
      "unit": "percent",
      "period": "2026-05",
      "periodEnd": "2026-05-31",
      "frequency": "monthly",
      "observedAt": "2026-06-11T12:30:00Z",
      "freshnessStatus": "fresh",
      "provider": "U.S. Bureau of Labor Statistics",
      "sourceUrl": "https://www.bls.gov/cpi/",
      "rawAvailable": false
    }
  ],
  "meta": {
    "request_id": "0c8f...",
    "requestId": "0c8f...",
    "api_version": "v1",
    "pagination": { "limit": 100, "cursor": null, "next_cursor": null, "has_more": false }
  },
  "requestId": "0c8f..."
}

US CPI inflation history

Pull the full vintage history of US CPI Inflation YoY, oldest first.

curl -s "https://api.financialdatapi.com/observations?country=USA&indicator=cpi_inflation_yoy&period=2020&order=asc&limit=500" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

// paginate() auto-follows the cursor across every page
for await (const obs of client.paginate("/observations", {
  country: "USA",
  indicator: "cpi_inflation_yoy",
  order: "asc",
})) {
  console.log(obs.periodEnd, obs.actual);
}

Latest unemployment across a country set, fresh only

Compare the latest Unemployment Rate, keeping only values that pass the freshness gate. Query country by country with the shared indicator and freshness filters.

curl -s "https://api.financialdatapi.com/observations/latest?country=GBR&indicator=unemployment_rate&freshness=fresh" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

const countries = ["USA", "GBR", "DEU", "JPN", "CAN"];

for (const country of countries) {
  const { data } = await client.getLatestObservations({
    country,
    indicator: "unemployment_rate",
    freshness: "fresh",
  });
  if (data.length) {
    console.log(country, data[0].actual, data[0].unit);
  }
}

Provenance

Every macro value traces back to an official release. Pass an observationId to the provenance endpoint for the named source, source URL, raw payload reference metadata, and the ingestion run.

curl -s "https://api.financialdatapi.com/provenance/observations/obs_us_cpi_inflation_yoy_2026_05" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

Sources behind the macro families are institutions of record, including FRED, BLS, ECB, OECD, BIS, Eurostat, Bank of England, and Bank of Japan, across roughly 87 source connectors (53 providers).

Errors

Non-2xx responses share the standard envelope with a stable, machine-readable code.

Code	Status	Meaning
`bad_request`	400	Malformed query, an unknown query parameter, or an unrecognized indicator.
`unauthorized`	401	Missing or invalid API key.
`forbidden`	403	Key lacks the `data:read` scope.
`not_found`	404	Resource does not exist.
`rate_limited`	429	Rate limit exceeded; see `details`.
`internal_error`	500	Unexpected server error.

Interest rates

Policy Rate, 3-Month Money-Market Benchmark Rate, 10-Year Government Bond Yield, and the 10Y-3M Yield-Curve Spread.

Economic calendar & events

Scheduled and released macro events with actual, forecast, consensus, previous, and revised values.

Derived analytics

Surprise indices, COT positioning percentiles, valuation multiples, and rates analytics.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

Macro indicators

What data is available

Units you will see

percent

index

thousands

persons

USD millions

Country coverage

Canonical indicator IDs

Querying the data

GET /observations

GET /observations/latest

Authentication

Filters

Response fields

Examples

Latest US CPI inflation

US CPI inflation history

Latest unemployment across a country set, fresh only

Provenance

Errors

Interest rates

Economic calendar & events

Derived analytics

​What data is available

​Units you will see

percent

index

thousands

persons

USD millions

​Country coverage

​Canonical indicator IDs

​Querying the data

GET /observations

GET /observations/latest

​Authentication

​Filters

​Response fields

​Examples

​Latest US CPI inflation

​US CPI inflation history

​Latest unemployment across a country set, fresh only

​Provenance

​Errors

​Related

Interest rates

Economic calendar & events

Derived analytics

What data is available

Units you will see

Country coverage

Canonical indicator IDs

Querying the data

Authentication

Filters

Response fields

Examples

Latest US CPI inflation

US CPI inflation history

Latest unemployment across a country set, fresh only

Provenance

Errors

Related