Name: Economic Data API: Treasury Yields, Inflation and CPI
Brand: martindata
SKU: api-martindata-economicdatasuite-api
Availability: InStock
Author: API Market

Martin Petrov

# Economic Data API

## Overview

The Economic Data API bundles two macro data endpoints in one subscription. `/m/treasury-yields-api` returns official US Treasury rates from the Daily Treasury Par Yield Curve and the other Treasury rate tables, with five modes: `latest`, `date`, `history`, `spreads` and `inversion`. `/m/inflation-cpi-api` returns inflation, CPI and other indicators by country from the World Bank, with the newest monthly HICP from Eurostat for EU countries, and an `adjust` mode that converts an amount between years with CPI.

It is built for fintech apps, pricing and salary tools, economics dashboards and research teams that want yields and inflation through one key. In our tests the latest nominal curve returned 13 November 2026 with the 10-year at 5.15% and the 2-year at 4.88%, the inflation call returned US inflation of 2.95% for 2024 and German inflation of 2.17% for 2025 with an October 2026 HICP of 2.8%, and an invalid date or unknown country returned a clear `400`.

## Features

*   **2 endpoints**: US Treasury yields and inflation and macro indicators by country.
*   **Treasury modes**: latest, date, history, spreads and inversion for the nominal, real, bills and long-term curves.
*   **Inflation modes**: latest, history, monthly, adjust, indicators and countries.
*   **Official sources**: US Treasury daily rate tables, World Bank WDI and Eurostat HICP, named in every row.
*   **Clear errors**: invalid dates and unknown countries return `400` with the reason.
*   **Billed per result**: one unit per result returned, shown in the `billed` field.

## Use Cases

*   **Fintech apps**: show current Treasury rates next to inflation.
*   **Pricing and salary tools**: index amounts to CPI with the adjust mode.
*   **Recession dashboards**: track 10Y-2Y spreads and curve inversion.
*   **Research**: pull clean yearly and daily macro series.

## API Documentation

### Base URL

All requests use the following base URL.

```
https://prod.api.market/api/v1/martindata/economicdatasuite-api
```

### Authentication

All requests are authenticated with the `x-api-market-key` header.

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Get Treasury yields

Returns one item per day with yields by maturity, spreads, inversion flags and the one-day change in basis points.

**Method:** `POST`

**Endpoint:** `/m/treasury-yields-api`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | `latest`, `date`, `history`, `spreads` or `inversion` | string | No | `latest` | - |
| `curve` | body | `nominal`, `real`, `bills` or `longterm` | string | No | `nominal` | - |
| `date` | body | For `date`: the day, `YYYY-MM-DD` | string | No | - | - |
| `startDate` | body | For `history`, `spreads` and `inversion`: first day, `YYYY-MM-DD` | string | No | 30 days before `endDate` | - |
| `endDate` | body | For `history`, `spreads` and `inversion`: last day, `YYYY-MM-DD` | string | No | today | - |
| `maturities` | body | Filter, for example `2Y`, `10Y`, `3M` | array of strings | No | all | - |
| `frequency` | body | For `history` and `spreads`: `daily`, `weekly` or `monthly` | string | No | `daily` | - |
| `limit` | body | Maximum rows returned, newest kept | integer | No | 20 | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/economicdatasuite-api/m/treasury-yields-api' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "latest", "curve": "nominal"}'
```

**Example Response (200 OK):**

```json
{
  "billed": 1,
  "count": 1,
  "items": [
    {
      "change1d": {
        "1.5M": 0,
        "10Y": 5,
        "1M": -2,
        "1Y": 0,
        "20Y": 4,
        "2M": 0,
        "2Y": 2,
        "30Y": 4,
        "3M": 0,
        "3Y": 2,
        "4M": -1,
        "5Y": 3,
        "6M": 0,
        "7Y": 3
      },
      "curve": "nominal",
      "date": "2026-11-13",
      "inverted10y2y": false,
      "inverted10y3m": false,
      "source": "U.S. Treasury, Daily Treasury Par Yield Curve Rates",
      "sourceUrl": "https://home.treasury.gov/resource-center/data-chart-center/interest-rates/TextView?type=daily_treasury_yield_curve&field_tdr_date_value=2026",
      "spreads": {
        "10Y-2Y": 0.27,
        "10Y-3M": 0.83,
        "2Y-3M": 0.56,
        "30Y-5Y": 0.49
      },
      "unit": "percent",
      "yields": {
        "1.5M": 4.18,
        "10Y": 5.15,
        "1M": 4.1,
        "1Y": 4.65,
        "20Y": 5.52,
        "2M": 4.26,
        "2Y": 4.88,
        "30Y": 5.47,
        "3M": 4.32,
        "3Y": 4.92,
        "4M": 4.34,
        "5Y": 4.98,
        "6M": 4.42,
        "7Y": 5.05
      }
    }
  ]
}
```

An invalid request returns `400`:

```json
{
  "error": "invalid input: date must be a real date in YYYY-MM-DD format (got '2024-13-45')"
}
```

#### 2. Get inflation and economic indicators

Returns one item per country and indicator (latest), per year (history) or per conversion (adjust).

**Method:** `POST`

**Endpoint:** `/m/inflation-cpi-api`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `mode` | body | `latest`, `history`, `monthly`, `adjust`, `indicators` or `countries` | string | No | `latest` | - |
| `countries` | body | ISO2, ISO3 or English names. Empty uses US, DE, GB, JP and BG. | array of strings | No | - | 50 |
| `indicators` | body | For `latest`: `inflation`, `cpi`, `gdp`, `gdpGrowth`, `gdpPerCapita`, `unemployment`, `population`, `interestRate` or a World Bank code | array of strings | No | `inflation` | - |
| `indicator` | body | For `history`: one indicator key | string | No | `inflation` | - |
| `startYear` | body | For `history`: first year, 1960 or later | integer | No | 10 years ago | - |
| `endYear` | body | For `history`: last year | integer | No | latest year | - |
| `startMonth` | body | For `monthly`: first month, `YYYY-MM` | string | No | 24 months back | - |
| `endMonth` | body | For `monthly`: last month, `YYYY-MM` | string | No | newest month | - |
| `amount` | body | For `adjust`: the money amount | number | No | 100 | - |
| `country` | body | For `adjust`: one country | string | No | `US` | - |
| `fromYear` | body | For `adjust`: year of the original amount | integer | No | 10 years before `toYear` | - |
| `toYear` | body | For `adjust`: target year | integer | No | latest CPI year | - |
| `limit` | body | Maximum rows returned | integer | No | 20 | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/martindata/economicdatasuite-api/m/inflation-cpi-api' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "latest", "countries": ["US", "DE"], "indicators": ["inflation"], "limit": 4}'
```

**Example Response (200 OK):**

```json
{
  "billed": 2,
  "count": 2,
  "items": [
    {
      "change": -1.1668,
      "country": "US",
      "countryName": "United States",
      "fetchedAt": "2026-11-13T17:25:02Z",
      "indicator": "inflation",
      "indicatorCode": "FP.CPI.TOTL.ZG",
      "iso3": "USA",
      "previousValue": 4.1163,
      "previousYear": 2023,
      "source": "World Bank, World Development Indicators (FP.CPI.TOTL.ZG), licence CC BY 4.0",
      "unit": "% per year",
      "value": 2.9495,
      "year": 2024
    }
  ]
}
```

The `items` list above is shortened to one of two rows. An unknown country returns `400`:

```json
{
  "error": "invalid input: unknown country 'XX'; use an ISO2 code (US, DE, BG), ISO3 code (USA, DEU) or the English name (Germany); mode=countries lists all"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 400 | Bad Request | The JSON body is invalid, a required field is missing or a value is not supported. The message says which. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The path does not match an endpoint of this API. Check the Base URL and path. |
| 429 | Too Many Requests | You went over 10 requests per second or used up the units of your plan. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 10 requests per second. The Free trial includes 100 units, Pro includes 10,000 units per month for $19, and PAYG is billed $0.002 per unit. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **What does an empty request return?**
    Treasury returns the latest nominal yield curve, and inflation returns the latest inflation for the default countries US, DE, GB, JP and BG.

*   **How fresh is the data?**
    Treasury rates update every US business day after the Treasury publishes them. World Bank values are yearly and published with a delay, so EU countries also get the newest monthly HICP.

*   **What does change1d mean?**
    The change from the previous business day in basis points, per maturity.

*   **How many units does a call use?**
    One unit per result returned. The `billed` field shows the count.

*   **Are identical requests cached?**
    Yes. Identical requests are cached for up to 6 hours, so repeat calls return quickly.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


US Treasury yield curve, spreads and inversion plus inflation, CPI and GDP by country from the World Bank and Eurostat, in one economic data API.