Financial Data API — Documentation

The rates family is Financial Data API’s interest-rate factor set: the short end (policy and money-market rates), the long end (10-year government bond yields), and a curve measure (the 10Y-3M spread), each with a stable canonical indicator ID that means the same thing in every country. Query the UK policy rate, the US 10-year yield, and a country’s curve spread with the same slugs and filters, and join across countries cleanly. This page leads with the rate series that are available and their units, then shows how to read them through the two observation endpoints.

What data is available

The rates family spans the covered countries, built from a small set of canonical rate shapes, one per country where it exists:

Policy Rate

The central bank’s headline policy rate. Unit: percent.

3-Month Money-Market Benchmark Rate

The short-end money-market benchmark. Unit: percent.

10-Year Government Bond Yield

The 10-year sovereign benchmark yield. Unit: percent.

10Y-3M Yield-Curve Spread

The slope of the curve: 10-year yield minus the 3-month rate. Unit: percentage_points.

These shapes span the covered countries (plus 2/5/30-year yields where published); the exact per-country availability is live, so treat this as a map and read the authoritative, machine-readable list from GET /canonical-indicators and the breadth summary from GET /coverage.

Units

Rate series carry an explicit unit. Two units appear in this family, and branching on unit matters because levels and spreads are not the same thing:

percent

Rate levels: Policy Rate, 3-Month Money-Market Benchmark Rate, 10-Year Government Bond Yield. A value of 4.5 means 4.5 percent.

percentage_points

Differences between two rates: the 10Y-3M Yield-Curve Spread. A value of -0.4 means the 10-year yield is 0.4 percentage points below the 3-month rate (an inverted curve).

A percent value is a level you can read directly. A percentage_points value is a gap: it can be negative when the curve is inverted (short rates above long rates). Do not treat the two units as interchangeable.

Country coverage

Rate series are keyed by ISO 3166-1 alpha-3 country code, drawn from the same covered macro universe:

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

Coverage is not uniform: not every country carries all four rate series, so the family totals fewer series than four times the country count. Confirm exactly which rate series a country carries with GET /coverage and resolve the live indicator universe with GET /canonical-indicators.

These are rate and yield series sourced from institutions of record. Financial Data API publishes official daily FX reference rates separately, 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.

Canonical indicator IDs

Each rate series has a canonical indicator ID, a stable slug identical across countries, returned on every observation as indicatorId. You query by it and join on it. The complete, current list of rate 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();
const rates = indicators.data.filter((ind) => ind.category === "rates");
for (const ind of rates) {
  console.log(ind.indicatorId, ind.indicatorName, ind.unit);
}

Use GET /canonical-indicators to confirm the exact rate slug for the country you want before building queries. Financial Data API fails closed on unknown query parameters and rejects unrecognized indicators with bad_request.

Querying the data

Rate values are served as observations, the same as every other macro factor. An observation is a single value a series describes for a single period, for example the US 10-year government bond yield on a given day. 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 rate observations across periods and vintages. Cursor-paginated.

GET /observations/latest

The snapshot. The single latest public reading per rate indicator. The fastest way to ask “where are rates 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. 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).

string

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

string

Canonical rate indicator slug. Also accepted as indicator_id. Omit it to pull a country’s full set of latest readings in one query, then keep the rate series by matching each row’s indicatorId against the rate indicator IDs from /canonical-indicators (where category is rates).

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. 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 rate series:

string

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

string

Canonical rate indicator slug. Use it to query and join across countries.

string

Human-readable indicator name, for example 10-Year Government Bond Yield.

string

ISO 3166-1 alpha-3 country code.

number

The headline numeric value. A rate level (in percent) or a spread (in percentage_points), per unit.

string

percent for rate levels, percentage_points for the curve spread.

string

Label for the period the value describes, for example 2026-06-10.

string

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

string

Publication cadence.

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 Bank of England.

string

The official source URL for the series.

boolean

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

Examples

A country’s full rates set (latest)

Pull every rate series Financial Data API holds for one country in a single latest call, then keep the rates family. Because /observations/latest returns the latest reading per canonical indicator, one country query gives you the policy rate, the money-market benchmark, the 10-year yield, and the curve spread together.

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

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

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

// Discover the rate indicator IDs once, then keep only those from the latest readings.
const catalog = await client.listIndicators();
const rateIds = new Set(catalog.data.filter((ind) => ind.category === "rates").map((ind) => ind.indicatorId));

const { data } = await client.getLatestObservations({ country: "USA" });
const rates = data.filter((obs) => rateIds.has(obs.indicatorId));
for (const obs of rates) {
  console.log(obs.indicatorName, obs.actual, obs.unit);
}

A latest rates response looks like this:

{
  "data": [
    {
      "observationId": "obs_us_policy_rate_2026_06_10",
      "indicatorId": "policy_rate",
      "indicatorName": "Policy Rate",
      "country": "USA",
      "actual": 4.5,
      "unit": "percent",
      "period": "2026-06-10",
      "periodEnd": "2026-06-10",
      "frequency": "daily",
      "observedAt": "2026-06-10T00:00:00Z",
      "freshnessStatus": "fresh",
      "provider": "Federal Reserve (via FRED)",
      "sourceUrl": "https://fred.stlouisfed.org/",
      "rawAvailable": false
    },
    {
      "observationId": "obs_us_govt_bond_yield_10y_2026_06_10",
      "indicatorId": "govt_bond_yield_10y",
      "indicatorName": "10-Year Government Bond Yield",
      "country": "USA",
      "actual": 4.1,
      "unit": "percent",
      "period": "2026-06-10",
      "periodEnd": "2026-06-10",
      "frequency": "daily",
      "observedAt": "2026-06-10T00:00:00Z",
      "freshnessStatus": "fresh",
      "provider": "Federal Reserve (via FRED)",
      "sourceUrl": "https://fred.stlouisfed.org/",
      "rawAvailable": false
    }
  ],
  "meta": {
    "request_id": "a1b2...",
    "requestId": "a1b2...",
    "api_version": "v1",
    "pagination": { "limit": 100, "cursor": null, "next_cursor": null, "has_more": false }
  },
  "requestId": "a1b2..."
}

The indicatorId values above (policy_rate, govt_bond_yield_10y) illustrate the shape of a rate slug. Confirm the exact IDs from GET /canonical-indicators for the country you query.

10-year yield history

Pull the time series of a country’s 10-year government bond yield, oldest first.

curl -s "https://api.financialdatapi.com/observations?country=USA&indicator=govt_bond_yield_10y&period=2025&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 });

for await (const obs of client.paginate("/observations", {
  country: "USA",
  indicator: "govt_bond_yield_10y",
  order: "asc",
})) {
  console.log(obs.periodEnd, obs.actual);
}

The curve-spread series

The 10Y-3M Yield-Curve Spread is a first-class series in percentage_points: read it directly rather than computing it. A negative value means an inverted curve (short rates above long rates).

curl -s "https://api.financialdatapi.com/observations/latest?country=USA&indicator=yield_curve_spread_10y_3m" \
  -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: "yield_curve_spread_10y_3m",
});

const spread = data[0];
console.log(
  spread.actual,
  spread.unit,
  spread.actual < 0 ? "inverted" : "upward sloping",
);

Financial Data API also serves stored rates analytics (curve spreads and more) as derived indicators, where each derived value records its input observation IDs and source refs. See Derived analytics.

Provenance

Every rate 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_policy_rate_2026_06_10" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

Rate series draw on institutions of record, including FRED, ECB, BIS, 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.

Macro indicators

Inflation, labor, growth, housing, external, income, and consumption factors.

Derived analytics

Stored rates analytics, curve spreads, and other derived indicators with input provenance.

Economic calendar & events

Central-bank actions and scheduled rate decisions as official events.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

Interest rates

What data is available

Policy Rate

3-Month Money-Market Benchmark Rate

10-Year Government Bond Yield

10Y-3M Yield-Curve Spread

Units

percent

percentage_points

Country coverage

Canonical indicator IDs

Querying the data

GET /observations

GET /observations/latest

Authentication

Filters

Response fields

Examples

A country’s full rates set (latest)

10-year yield history

The curve-spread series

Provenance

Errors

Macro indicators

Derived analytics

Economic calendar & events

​What data is available

Policy Rate

3-Month Money-Market Benchmark Rate

10-Year Government Bond Yield

10Y-3M Yield-Curve Spread

​Units

percent

percentage_points

​Country coverage

​Canonical indicator IDs

​Querying the data

GET /observations

GET /observations/latest

​Authentication

​Filters

​Response fields

​Examples

​A country’s full rates set (latest)

​10-year yield history

​The curve-spread series

​Provenance

​Errors

​Related

Macro indicators

Derived analytics

Economic calendar & events

What data is available

Units

Country coverage

Canonical indicator IDs

Querying the data

Authentication

Filters

Response fields

Examples

A country’s full rates set (latest)

10-year yield history

The curve-spread series

Provenance

Errors

Related