Saudi Arabia Historical Bond Yield API

You need reliable, machine-readable historical yields for Saudi Arabian government bonds to power analytics, dashboards, and risk tooling. By the end of this guide you will query, parse, and combine Bonds API endpoints to fetch Saudi Arabia (ISO2: SA) yields across maturities, construct yield curves, compute spreads, and analyze historical and intraday movements—using only documented REST GET calls that return clean JSON.

What the data covers and how to interpret it

Saudi sovereign bonds are fixed-income instruments issued by the Kingdom of Saudi Arabia. The Bonds API serves their yields as daily percentages per maturity, with intraday snapshots available for select maturities. A few key points:

• Yields are expressed in percent with decimal precision (for example, 4.52 means 4.52%).
• Dates are ISO 8601 (Y-m-d) like 2026-10-21. Intraday timestamps are UTC ISO 8601 (e.g., 2026-10-21T12:00:00Z).
• Spreads are returned in basis points (bps). 1 basis point = 0.01%.
• Coverage spans short bills (1M) through long bonds (30Y, and up to 50Y in general coverage).

All endpoints are HTTP GET only under the base URL https://bonds-api.com/api/v1/. Authentication is supplied via an X-API-Key header. Explore the platform at https://bonds-api.com and the MCP for environment details, then Register for an API key to integrate.

Authentication and request patterns

Every request must include:

• Base URL: https://bonds-api.com/api/v1/
• Method: GET
• Header: X-API-Key: YOUR_API_KEY

Never place the key in query parameters in production; pass it in the X-API-Key header. JSON responses include success flags, data payloads, and consistent error shapes for common errors like 401, 404, and 429. Visit bonds-api.com for platform context and limits.

Get current Saudi yields: /latest

Use /latest to retrieve the most recent available yields for Saudi Arabia across one or more maturities. If you omit maturities, the endpoint returns all available points on the curve for SA.

cURL

curl -s "https://bonds-api.com/api/v1/latest?countries=SA&maturities=10Y&api_key=YOUR_API_KEY"

Python (requests)

import requests

resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "SA", "maturities": "2Y,10Y"}
)
data = resp.json()
# Example access:
# sa_2y = data["data"]["SA"]["2Y"]["yield"]
# sa_10y = data["data"]["SA"]["10Y"]["yield"]

JavaScript (fetch)

const url = new URL("https://bonds-api.com/api/v1/latest");
url.search = new URLSearchParams({ countries: "SA", maturities: "2Y,10Y" }).toString();

fetch(url.toString(), {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json())
.then(json => {
// const sa2y = json.data.SA["2Y"].yield;
// const sa10y = json.data.SA["10Y"].yield;
});

PHP (file_get_contents)

<?php
$params = http_build_query(["countries" => "SA", "maturities" => "2Y,10Y"]);
$opts = ["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]];
$context = stream_context_create($opts);
$json = file_get_contents("https://bonds-api.com/api/v1/latest?$params", false, $context);
$data = json_decode($json, true);
// $sa2y = $data["data"]["SA"]["2Y"]["yield"];
// $sa10y = $data["data"]["SA"]["10Y"]["yield"];

JSON response example

{
"success": false,
"error": "No data found for the specified parameters.",
"code": "not_found"
}

Reading the payload:

• yield: percent (e.g., 4.25 means 4.25%).
• date: ISO day the yield is associated with (Y-m-d).
• source: “official” indicates an official source for the listed yield.

Official sample (verbatim)

The following is an official sample block, included verbatim for completeness:

Get a specific historical Saudi yield: /historical

Use /historical to retrieve the Saudi yield for a specific maturity on a single calendar date.

cURL

Python

import requests

resp = requests.get(
"https://bonds-api.com/api/v1/historical",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "SA", "maturity": "10Y", "date": "2025-06-15"}
)
j = resp.json()
# j["yield"] is the 10Y yield in percent on 2025-06-15

JavaScript

const params = new URLSearchParams({ country: "SA", maturity: "10Y", date: "2025-06-15" });
fetch(`https://bonds-api.com/api/v1/historical?${params}`, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json())
.then(j => {
// j.yield, j.date
});

PHP

<?php
$params = http_build_query(["country" => "SA", "maturity" => "10Y", "date" => "2025-06-15"]);
$context = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/historical?$params", false, $context);
$h = json_decode($json, true);
// $h["yield"] is percent; $h["date"] is Y-m-d

JSON response example

Key fields: yield (percent), date (Y-m-d), source (data provenance). If the date falls on a weekend or holiday without an official fix, expect a 404 not found.

Get a Saudi yield time series: /timeseries

/timeseries returns a continuous daily series for a chosen maturity between start and end dates (inclusive, when data exists on those days).

cURL

Python

import requests

resp = requests.get(
"https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "SA", "maturity": "10Y", "start": "2025-10-21", "end": "2026-10-21"}
)
ts = resp.json()
# ts["series"] is a list of { "date": "Y-m-d", "yield": float }

JavaScript

const p = new URLSearchParams({ country: "SA", maturity: "10Y", start: "2025-10-21", end: "2026-10-21" });
fetch(`https://bonds-api.com/api/v1/timeseries?${p}`, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json())
.then(ts => {
// ts.series: [{ date: "2025-01-02", yield: 4.21 }, ...]
});

PHP

<?php
$params = http_build_query(["country" => "SA", "maturity" => "10Y", "start" => "2025-10-21", "end" => "2026-10-21"]);
$context = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/timeseries?$params", false, $context);
$ts = json_decode($json, true);

JSON response example

Series data is per business day; weekends and market holidays will not have entries. Use this endpoint for return calculations, trend analysis, and volatility estimation.

Compute Saudi vs. benchmark spread: /spread

Compare Saudi yields against a benchmark country (for example, US Treasuries) at a given maturity. The endpoint returns the spread in basis points and the underlying country and benchmark yields.

cURL

Python

import requests

r = requests.get(
"https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "SA", "benchmark": "US", "maturity": "10Y"}
)
sp = r.json()
# sp["spread_bps"] is an integer number of basis points

JavaScript

const qp = new URLSearchParams({ country: "SA", benchmark: "US", maturity: "10Y" });
fetch(`https://bonds-api.com/api/v1/spread?${qp}`, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json())
.then(sp => {
// sp.spread_bps, sp.country_yield, sp.benchmark_yield
});

PHP

<?php
$params = http_build_query(["country" => "SA", "benchmark" => "US", "maturity" => "10Y"]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/spread?$params", false, $ctx);
$sp = json_decode($json, true);

JSON response example

Interpretation: spread_bps is 215 bps (2.15%) with Saudi 10Y at 4.52% and the US 10Y at 2.37%. Positive spread_bps indicates the country yield is higher than the benchmark at that maturity.

Get the Saudi yield curve: /curve

Fetch the full Saudi yield curve for the latest available date or a specified date. The response indicates if the curve is inverted (shorter maturities yielding more than longer ones overall).

cURL

Python

import requests

r = requests.get(
"https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "SA"}
)
curve = r.json()
# curve["curve"] is a dict keyed by maturity (e.g., "1M","2Y","10Y") with yields in percent

JavaScript

const paramsCurve = new URLSearchParams({ country: "SA" });
fetch(`https://bonds-api.com/api/v1/curve?${paramsCurve}`, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json())
.then(curve => {
// curve.curve, curve.date, curve.inverted
});

PHP

<?php
$params = http_build_query(["country" => "SA"]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/curve?$params", false, $ctx);
$curve = json_decode($json, true);

JSON response example

Each field in curve is a maturity key mapped to a yield percentage. Use inverted to quickly assess curve shape in dashboards.

Intraday Saudi yield snapshots: /intraday

When you need multiple observations within a day (e.g., for market monitors), /intraday returns intra-session snapshots for a specific maturity on a given date, with UTC timestamps.

cURL

Python

import requests

r = requests.get(
"https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "SA", "maturity": "10Y", "date": "2026-10-21"}
)
intra = r.json()
# intra["snapshots"] is a list of { "yield": float, "fetched_at": "YYYY-MM-DDThh:mm:ssZ", "source": "market" }

JavaScript

const q = new URLSearchParams({ country: "SA", maturity: "10Y", date: "2026-10-21" });
fetch(`https://bonds-api.com/api/v1/intraday?${q}`, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json())
.then(intra => {
// intra.snapshots, intra.count, intra.meta.timezone === "UTC"
});

PHP

<?php
$params = http_build_query(["country" => "SA", "maturity" => "10Y", "date" => "2026-10-21"]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/intraday?$params", false, $ctx);
$intra = json_decode($json, true);

JSON response example

Use fetched_at to order points. All timestamps are in UTC; convert to your users’ local time on the client.

Period fluctuations for Saudi yields: /fluctuation

/fluctuation summarizes the start, end, absolute change, and observed min/max for a maturity over a date range. It supports multiple countries; here we focus on SA.

cURL

Python

import requests

r = requests.get(
"https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "SA", "maturity": "10Y", "start": "2025-10-21", "end": "2026-10-21"}
)
fl = r.json()
# fl["data"]["SA"] has start_yield, end_yield, change, min, max (all in percent)

JavaScript

const flp = new URLSearchParams({ countries: "SA", maturity: "10Y", start: "2025-10-21", end: "2026-10-21" });
fetch(`https://bonds-api.com/api/v1/fluctuation?${flp}`, {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
}).then(r => r.json())
.then(fl => {
// fl.data.SA.start_yield, .end_yield, .change, .min, .max
});

PHP

<?php
$params = http_build_query(["countries" => "SA", "maturity" => "10Y", "start" => "2025-10-21", "end" => "2026-10-21"]);
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$json = file_get_contents("https://bonds-api.com/api/v1/fluctuation?$params", false, $ctx);
$fl = json_decode($json, true);

JSON response example

All values are in percent. change equals end_yield - start_yield. This is handy for high-level reporting and risk attribution.

Practical implementation notes (Saudi market focus)

• Maturities: Common Saudi points include short-term bills (1M, 3M, 6M), and bonds around 1Y, 2Y, 5Y, 10Y, 30Y. Use /curve for a complete snapshot; /latest with maturities lets you pick specific tenors.
• Business days and holidays: Expect gaps on weekends and Saudi market holidays. /timeseries and /historical reflect the days where official data exists. Your code should not assume consecutive calendar days.
• Update frequency: /latest reflects the most recent available day. /intraday offers multiple within-day snapshots with UTC timestamps for finer monitoring.
• Caching: Cache immutable historical responses (by date) client-side to reduce calls. For dashboards, set short-lived caches for /latest and /curve and back off if you encounter HTTP 429 (rate limit exceeded).
• Error handling: The API uses a consistent error shape. Handle:
  • 401: Missing/invalid X-API-Key
  • 403: Quota exceeded
  • 404: No data for the country/maturity/date combination
  • 422: Invalid parameters (e.g., date format must be Y-m-d)
  • 429: Rate limit exceeded—retry with exponential backoff
  • 500: Server error—retry later

Building a Saudi yield curve and spreads programmatically

For a full curve at a point in time, prefer /curve for completeness and simplicity. If you need only a subset of maturities frequently, use /latest with the maturities parameter to reduce payload size and latency. Examples:

• Curve display: Call /curve once per refresh tick. Show inverted and date to label the chart.
• Custom tenor set: Call /latest with maturities=2Y,5Y,10Y,30Y. Combine with /spread against US or DE for relative valuation widgets.
• Term structure analytics: Use /timeseries for each tenor you analyze, then compute PCA, carry/roll, or forward rates in your app.

End-to-end example: combine endpoints for Saudi dashboards

Steps

1. Fetch the latest Saudi curve via /curve and render a line chart.
2. Pull Saudi 10Y /timeseries for the past year to chart historical levels and compute realized volatility.
3. Request /spread versus US at 10Y to display the current differential in basis points.
4. For a trading day view, query /intraday for SA 10Y to show within-day moves and annotate the chart with fetched_at in UTC.
5. Summarize performance using /fluctuation to provide min/max and absolute change over a chosen period.

All calls are simple GET requests with the same header and country code (SA), so you can centralize auth and error handling.

Appendix: Complete endpoint catalog for Saudi Arabia

Below is a concise recap of each endpoint, required parameters, and units:

• /latest: countries (SA), optional maturities (e.g., 2Y,10Y). Returns yields in percent and the associated date.
• /historical: country=SA, maturity, date=Y-m-d. Returns the single-day yield in percent.
• /timeseries: country=SA, maturity, start, end (Y-m-d). Returns daily series of yields in percent.
• /spread: country=SA, benchmark (e.g., US or DE), optional maturity (default 10Y). Returns spread_bps plus both yields.
• /curve: country=SA, optional date=Y-m-d. Returns the full curve and inverted flag.
• /intraday: country=SA, maturity, date=Y-m-d. Returns snapshots with UTC timestamps and yields in percent.
• /fluctuation: countries=SA, maturity, start, end. Returns start/end yields, change, min, max (all percent).

For production usage, standardize your maturity list, centralize symbol constants (SA), and write parsers that strongly type yields (float percent), spreads (integer bps), dates (Y-m-d), and timestamps (UTC ISO).

Use cases for analysts and developers

• Financial dashboards: Display the Saudi curve, movements, and US-spread in real time with automatic refresh.
• Portfolio risk: Monitor DV01 exposure by pinning holdings to SA maturities and updating valuations as yields change (use /latest and /timeseries).
• Economic research: Estimate policy stance transmission by tracking short-tenor bills vs. long bonds and checking inversion status.
• Relative value screens: Compare Saudi yields to US or German benchmarks using /spread, and alert when spreads breach thresholds.

Testing tips and reliability

• Clock and timezone: Treat server-provided times (intraday) as UTC; convert in your frontend for user display.
• Missing days: If /historical 404s for a non-business day, shift to the previous business day or notify the user.
• Caching strategy: Cache per-date endpoints aggressively; revalidate /latest and /curve at your desired refresh rate.
• Validation: Check success before accessing payload fields, and surface the error message to logs on failure.

FAQ

Which country code should I use for Saudi Arabia?
Use the ISO2 code SA across all endpoints.

In which units are yields and spreads returned?
Yields are in percent (e.g., 4.52 means 4.52%). Spreads are returned in basis points (e.g., 215 bps equals 2.15%).

What timezone are intraday timestamps in?
Intraday fetched_at values are UTC ISO 8601 timestamps (e.g., 2026-10-21T12:00:00Z). Convert client-side as needed.

How should I handle weekends and holidays?
Expect no data for non-business days. /timeseries will skip those dates; /historical may 404 if you request a date without an official fixing.

How do I authenticate?
Send your key in the X-API-Key header for all GET requests to https://bonds-api.com/api/v1/.

Ship your Saudi Arabia yield integration now. Explore the MCP, browse endpoints at bonds-api.com, and Register to get your API key and start pulling Saudi bond yields into your tools today.