API Documentation

The Bonds API provides RESTful access to sovereign bond yield data for 60+ countries. All responses are JSON-formatted with consistent structure and error handling.

Quick start: Sign up for a 7-day free trial, create an API key in the dashboard, and start making requests. Full access to all endpoints during your trial.
Log in to auto-fill your API key in all snippets and run endpoints directly from this documentation.

Authentication

All API requests require an API key passed via api_key query parameter:

curl "https://bonds-api.com/api/v1/latest?countries=US&api_key=bnd_live_your_key_here"

Base URL

https://bonds-api.com/api/v1

Rate Limits

Rate limits depend on your plan. When you exceed them, you'll receive a 429 response.

PlanMonthly RequestsRate
Starter1,00060/min
Professional10,000120/min
Enterprise100,000300/min
GET /latest

Get the latest bond yields for specified countries and maturities.

Parameters

Name Type Required Description
countries string required Comma-separated ISO country codes (e.g., US,DE,ES)
maturities string optional Comma-separated maturities (e.g., 2Y,10Y). Defaults to all available.

Code Example

Log in to run

Sample Response

{
  "success": true,
  "date": "2026-04-14",
  "rates": {
    "US_2Y": 3.80,
    "US_10Y": 4.25,
    "DE_2Y": 2.66,
    "DE_10Y": 3.00,
    "ES_2Y": 2.85,
    "ES_10Y": 3.50
  }
}
GET /historical

Get the bond yield for a specific country, maturity, and date.

Parameters

Name Type Required Description
country string required ISO country code (e.g., US)
maturity string required Bond maturity (e.g., 10Y)
date string required Date in YYYY-MM-DD format

Code Example

Log in to run

Sample Response

{
  "success": true,
  "data": {
    "country": "ES",
    "maturity": "10Y",
    "yield": 3.17,
    "date": "2025-06-15"
  }
}
GET /timeseries

Get a time series of yields over a date range.

Parameters

Name Type Required Description
country string required ISO country code
maturity string required Bond maturity
start string required Start date (YYYY-MM-DD)
end string required End date (YYYY-MM-DD)

Code Example

Log in to run

Sample Response

{
  "success": true,
  "country": "US",
  "maturity": "10Y",
  "timeseries": [
    {"date": "2025-01-02", "yield": 4.24},
    {"date": "2025-01-03", "yield": 4.28},
    {"date": "2025-01-06", "yield": 4.31}
  ],
  "count": 252
}
GET /spread

Calculate the yield spread between a country and a benchmark.

Parameters

Name Type Required Description
country string required ISO country code
benchmark string required Benchmark country code (e.g., DE for Bund, US for Treasury)
maturity string optional Bond maturity (default: 10Y)

Code Example

Log in to run

Sample Response

{
  "success": true,
  "data": {
    "country": "IT",
    "benchmark": "DE",
    "maturity": "10Y",
    "country_yield": 3.78,
    "benchmark_yield": 3.00,
    "spread_bps": 78.0,
    "unit": "basis_points"
  }
}
GET /curve

Get the full yield curve for a country (all available maturities).

Parameters

Name Type Required Description
country string required ISO country code
date string optional Date in YYYY-MM-DD format (defaults to latest)

Code Example

Log in to run

Sample Response

{
  "success": true,
  "data": {
    "country": "US",
    "date": "2026-04-14",
    "curve": [
      {"maturity": "3M", "yield": 4.30},
      {"maturity": "6M", "yield": 4.22},
      {"maturity": "2Y", "yield": 3.80},
      {"maturity": "5Y", "yield": 4.05},
      {"maturity": "10Y", "yield": 4.25},
      {"maturity": "30Y", "yield": 4.55}
    ],
    "spread_2y_10y": 45.0,
    "inverted": false
  }
}
GET /intraday

Get all intraday yield snapshots for a given country, maturity, and date.

Parameters

Name Type Required Description
country string required ISO country code
maturity string required Bond maturity
date string required Date in YYYY-MM-DD format

Code Example

Log in to run

Sample Response

{
  "success": true,
  "country": "US",
  "maturity": "10Y",
  "date": "2026-04-14",
  "snapshots": [
    {"yield": 4.2513, "fetched_at": "2026-04-14T06:00:00Z", "source": "fred"},
    {"yield": 4.2487, "fetched_at": "2026-04-14T12:00:00Z", "source": "treasury"},
    {"yield": 4.2530, "fetched_at": "2026-04-14T18:00:00Z", "source": "treasury"}
  ],
  "count": 3
}
GET /fluctuation

Get yield change, min, max, and percentage change over a date range.

Parameters

Name Type Required Description
countries string required Comma-separated ISO country codes
maturity string required Bond maturity
start string required Start date (YYYY-MM-DD)
end string required End date (YYYY-MM-DD)

Code Example

Log in to run

Sample Response

{
  "success": true,
  "maturity": "10Y",
  "fluctuations": {
    "IT": {
      "start_yield": 3.52,
      "end_yield": 3.68,
      "change": 0.16,
      "change_pct": 4.55,
      "min": 3.21,
      "max": 3.95
    },
    "GR": {
      "start_yield": 3.15,
      "end_yield": 3.31,
      "change": 0.16,
      "change_pct": 5.08,
      "min": 2.98,
      "max": 3.62
    }
  }
}

Error Codes

All errors return a JSON object with success: false and an error message.

CodeDescription
401Invalid or missing API key
403No active subscription or insufficient permissions
404No data found for the given parameters
422Validation error — check required parameters
429Rate limit or monthly quota exceeded
500Internal server error
 
{
  "success": false,
  "error": "Monthly request quota exceeded. Upgrade your plan for more requests.",
  "code": 429
}

Supported Country Codes

Use standard ISO 3166-1 alpha-2 codes. All codes are case-insensitive.

🇺🇸 US United States 🇨🇦 CA Canada 🇧🇷 BR Brazil 🇲🇽 MX Mexico 🇦🇷 AR Argentina 🇨🇱 CL Chile 🇨🇴 CO Colombia 🇵🇪 PE Peru 🇩🇪 DE Germany 🇬🇧 GB United Kingdom 🇫🇷 FR France 🇪🇸 ES Spain 🇮🇹 IT Italy 🇵🇹 PT Portugal 🇬🇷 GR Greece 🇳🇱 NL Netherlands 🇧🇪 BE Belgium 🇦🇹 AT Austria 🇨🇭 CH Switzerland 🇸🇪 SE Sweden 🇳🇴 NO Norway 🇩🇰 DK Denmark 🇫🇮 FI Finland 🇮🇪 IE Ireland 🇵🇱 PL Poland 🇨🇿 CZ Czech Republic 🇭🇺 HU Hungary 🇷🇴 RO Romania 🇭🇷 HR Croatia 🇧🇬 BG Bulgaria 🇷🇸 RS Serbia 🇸🇰 SK Slovakia 🇸🇮 SI Slovenia 🇱🇹 LT Lithuania 🇱🇻 LV Latvia 🇺🇦 UA Ukraine 🇯🇵 JP Japan 🇨🇳 CN China 🇦🇺 AU Australia 🇳🇿 NZ New Zealand 🇰🇷 KR South Korea 🇮🇳 IN India 🇸🇬 SG Singapore 🇹🇭 TH Thailand 🇲🇾 MY Malaysia 🇮🇩 ID Indonesia 🇵🇭 PH Philippines 🇻🇳 VN Vietnam 🇹🇼 TW Taiwan 🇭🇰 HK Hong Kong 🇧🇩 BD Bangladesh 🇵🇰 PK Pakistan 🇶🇦 QA Qatar 🇮🇱 IL Israel 🇹🇷 TR Turkey 🇿🇦 ZA South Africa 🇪🇬 EG Egypt 🇳🇬 NG Nigeria 🇰🇪 KE Kenya

Supported Maturities

The API covers the full sovereign curve, from short-term T-bills to ultra-long bonds. Not every country issues at every tenor — responses only include the maturities that actually exist for the requested country.

Short-term (T-bills)
1M 2M 3M 4M 5M 6M 7M 9M
Medium-term (notes)
1Y 2Y 3Y 4Y 5Y 6Y 7Y 8Y 9Y 10Y
Long-term (bonds)
11Y 12Y 13Y 14Y 15Y 20Y 25Y 30Y
Ultra-long (select markets)
40Y 50Y

Available primarily for Japan, the UK, and other issuers with long-dated debt programs.