> ## 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.

# Macro indicators

> Canonical macro factors (inflation, labor, growth, housing, external, income, consumption) as point-in-time observations across 17 countries.

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](/apis/interest-rates)). 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).                                                                                                                                                                        |

<Info>
  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](/apis/interest-rates).
</Info>

### Units you will see

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

<Columns cols={3}>
  <Card title="percent" icon="percent">
    Rates of change and ratios: CPI Inflation YoY, Real GDP Growth, Unemployment Rate.
  </Card>

  <Card title="index" icon="chart-line">
    Level indices: CPI index, Core CPI index, PCE Price Index.
  </Card>

  <Card title="thousands" icon="hashtag">
    Counts in thousands: Nonfarm Payroll Employment, Initial Jobless Claims, Housing Starts, Building Permits.
  </Card>

  <Card title="persons" icon="users">
    Headcounts reported in persons where the source publishes them that way.
  </Card>

  <Card title="USD millions" icon="dollar-sign">
    External-sector flows: Trade Balance, Exports, Imports.
  </Card>
</Columns>

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:

```text theme={"theme":"css-variables"}
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`.

<Note>
  Financial Data API publishes official daily [FX reference rates](/apis/fx) (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](/apis/derived-analytics).
</Note>

## 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:

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -s "https://api.financialdatapi.com/canonical-indicators" \
    -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 indicators = await client.listIndicators();
  for (const ind of indicators.data) {
    console.log(ind.indicatorId, ind.category, ind.unit);
  }
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

## 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.

<CardGroup cols={2}>
  <Card title="GET /observations" icon="list">
    The history. Time series of public observations across periods and vintages. Cursor-paginated.
  </Card>

  <Card title="GET /observations/latest" icon="bolt">
    The snapshot. The single latest public reading per canonical indicator. The fastest way to ask "where are things now."
  </Card>
</CardGroup>

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

```bash theme={"theme":"css-variables"}
-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](/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).

<ParamField query="country" type="string">
  ISO 3166-1 alpha-3 country code, for example `USA`, `GBR`, `JPN`. One of the covered countries.
</ParamField>

<ParamField query="indicator" type="string">
  Canonical indicator slug, for example `cpi_inflation_yoy`. Also accepted as `indicator_id`.
</ParamField>

<ParamField query="frequency" type="string">
  Publication cadence: `daily`, `weekly`, `monthly`, `quarterly`, or `annual`.
</ParamField>

<ParamField query="freshness" type="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.
</ParamField>

<ParamField query="source_id" type="string">
  Financial Data API source id, for example `source_bls_public_api`. Filter to a single institution of record.
</ParamField>

<ParamField query="provider_id" type="string">
  Financial Data API provider id or name. Also accepted as `provider`.
</ParamField>

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

<ParamField query="period" type="string">
  Convenience filter on the described period: `YYYY`, `YYYY-MM`, or `YYYY-Qn`.
</ParamField>

<ParamField query="period_end" type="string">
  Upper bound on the described period (`YYYY-MM-DD`).
</ParamField>

<ParamField query="start_date" type="string">
  Lower bound on knowledge-time (`observed_at`).
</ParamField>

<ParamField query="end_date" type="string">
  Upper bound on knowledge-time (`observed_at`).
</ParamField>

<ParamField query="as_of" type="string">
  Returns the latest vintage known on or before a timestamp. See the caveat below.
</ParamField>

<ParamField query="limit" type="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.
</ParamField>

<Warning>
  `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."
</Warning>

### Response fields

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

<ResponseField name="observationId" type="string">
  Stable ID for this observation. Pass it to `GET /provenance/observations/{observationId}` for the full source chain.
</ResponseField>

<ResponseField name="indicatorId" type="string">
  Canonical indicator slug, for example `cpi_inflation_yoy`. Use it to query and join across countries.
</ResponseField>

<ResponseField name="indicatorName" type="string">
  Human-readable indicator name, for example `CPI Inflation (YoY)`.
</ResponseField>

<ResponseField name="country" type="string">
  ISO 3166-1 alpha-3 country code.
</ResponseField>

<ResponseField name="actual" type="number">
  The headline numeric value of the reading.
</ResponseField>

<ResponseField name="unit" type="string">
  Unit of the value, for example `percent`, `index`, `thousands`, `persons`, `USD millions`.
</ResponseField>

<ResponseField name="period" type="string">
  Label for the period the value describes, for example `2026-05`.
</ResponseField>

<ResponseField name="periodEnd" type="string">
  End of the described period (`YYYY-MM-DD`).
</ResponseField>

<ResponseField name="frequency" type="string">
  Publication cadence: `daily`, `weekly`, `monthly`, `quarterly`, or `annual`.
</ResponseField>

<ResponseField name="observedAt" type="string">
  Knowledge-time: the point at which the value is observed.
</ResponseField>

<ResponseField name="freshnessStatus" type="string">
  Freshness label: `fresh`, `stale`, or `unknown`.
</ResponseField>

<ResponseField name="provider" type="string">
  The provider name behind the source, for example `U.S. Bureau of Labor Statistics`.
</ResponseField>

<ResponseField name="sourceUrl" type="string">
  The official source URL for the series.
</ResponseField>

<ResponseField name="rawAvailable" type="boolean">
  Whether a raw payload reference is exposed for this observation through the provenance endpoint.
</ResponseField>

## Examples

### Latest US CPI inflation

Get the single latest US CPI Inflation YoY reading.

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -s "https://api.financialdatapi.com/observations/latest?country=USA&indicator=cpi_inflation_yoy" \
    -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({
    country: "USA",
    indicator: "cpi_inflation_yoy",
  });

  console.log(data[0].actual, data[0].unit, data[0].period);
  ```
</CodeGroup>

A public observation looks like this:

```json theme={"theme":"css-variables"}
{
  "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.

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  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"
  ```

  ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"}
  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);
  }
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -s "https://api.financialdatapi.com/observations/latest?country=GBR&indicator=unemployment_rate&freshness=fresh" \
    -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 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);
    }
  }
  ```
</CodeGroup>

## 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.

```bash theme={"theme":"css-variables"}
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.                                                   |

## Related

<Columns cols={2}>
  <Card title="Interest rates" icon="percent" href="/apis/interest-rates">
    Policy Rate, 3-Month Money-Market Benchmark Rate, 10-Year Government Bond Yield, and the 10Y-3M Yield-Curve Spread.
  </Card>

  <Card title="Economic calendar & events" icon="calendar" href="/apis/economic-calendar">
    Scheduled and released macro events with actual, forecast, consensus, previous, and revised values.
  </Card>

  <Card title="Derived analytics" icon="function" href="/apis/derived-analytics">
    Surprise indices, COT positioning percentiles, valuation multiples, and rates analytics.
  </Card>
</Columns>