You need reliable, programmable access to the Saudi Arabia 10-year government bond yield so you can power a dashboard, compute spreads, or backtest fixed-income strategies. By the end of this guide, you will be able to fetch the latest Saudi 10Y yield, query specific historical dates, stream intraday snapshots, pull a full yield curve, and compute US–Saudi spreads using Bonds API over simple GET requests.
What the Saudi 10-Year Yield Represents and Why It Matters
The Saudi Arabia 10-year sovereign bond yield (country code SA; maturity 10Y) is a reference rate for medium-to-long-term SAR interest rates and risk premia. Analysts use it to construct yield curves, discount cash flows, model macro scenarios, and measure spreads versus benchmarks like the US Treasury 10Y. Developers need consistent JSON with clear units, business-day handling, and timestamps to integrate this into tools, risk engines, and research pipelines.
Bonds API provides sovereign bond yields across maturities as JSON over REST with an API key. All endpoints use GET and return machine-readable fields for direct integration. Explore product details at https://bonds-api.com and the MCP tools at MCP.
Base URL, Authentication, Units, and Timestamps
Base URL for all requests: https://bonds-api.com/api/v1/
- HTTP method: GET for all endpoints.
- Authentication: Use the X-API-Key header with your key (example: X-API-Key: YOUR_API_KEY).
- Units: All yields are expressed in percent (e.g., 4.52 means 4.52%). Spreads are in basis points (bps), where 1 bps = 0.01%.
- Dates: Fields named date are in YYYY-MM-DD (calendar day with data). Intraday timestamps use ISO 8601 UTC (e.g., 2026-11-05T12:00:00Z).
Business days and market holidays: If a market is closed, the latest endpoint returns the most recent business day with available data. Time series will only include dates with data; holiday and weekend gaps are normal. The intraday endpoint returns UTC-stamped snapshots for the requested date when available.
Caching and retries: For time-invariant queries (historical, curve by date), use long-lived caches. For latest and intraday, cache briefly (e.g., 1–5 minutes) to smooth burst traffic and respect rate limits. Always check for error responses and handle 401/403/404/422/429/500 gracefully.
Official Sample: Error Response Example
The following sample demonstrates an error response format from a live call. Note that, in production, authenticate using the X-API-Key header as shown in subsequent sections.
curl -s "https://bonds-api.com/api/v1/latest?countries=SA&maturities=10Y&api_key=YOUR_API_KEY"
{
"success": false,
"error": "No data found for the specified parameters.",
"code": "not_found"
}
Error shape guidance: success=false with an error message and optional code. Your integration should branch on success and log the error payload. See the common errors section later in this article.
Endpoint 1: Latest — Current Yields for Saudi Arabia
Use this to fetch the latest available yields. You can restrict to specific maturities (e.g., 10Y) or request the full set for SA.
cURL
JSON response
How to read it:
- yield: percent.
- date: latest business day with data (YYYY-MM-DD).
- source: data origin label (e.g., official).
Python (requests)
import requests
response = requests.get(
'https://bonds-api.com/api/v1/latest',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'countries': 'SA', 'maturities': '2Y,10Y'}
)
data = response.json()
if data.get('success'):
sa = data['data']['SA']
ten_y = sa['10Y']['yield']
ten_y_date = sa['10Y']['date']
print('SA 10Y:', ten_y, 'on', ten_y_date)
else:
print('Error:', data.get('error'))
JavaScript (fetch)
const url = new URL('https://bonds-api.com/api/v1/latest');
url.searchParams.set('countries', 'SA');
url.searchParams.set('maturities', '2Y,10Y');
fetch(url.toString(), {
method: 'GET',
headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(data => {
if (data.success) {
const sa10 = data.data.SA['10Y'];
console.log('SA 10Y', sa10.yield, 'as of', sa10.date);
} else {
console.error('Error:', data.error);
}
});
PHP (file_get_contents)
<?php
$context = stream_context_create([
'http' => [
'method' => 'GET',
'header' => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = 'https://bonds-api.com/api/v1/latest?countries=SA&maturities=2Y,10Y';
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
if ($data['success']) {
$sa10 = $data['data']['SA']['10Y'];
echo 'SA 10Y ' . $sa10['yield'] . ' as of ' . $sa10['date'];
} else {
echo 'Error: ' . $data['error'];
}
?
Endpoint 2: Historical — Yield on a Specific Date
Fetch the Saudi 10Y yield for a single date for point-in-time analysis, auditing, or backfills.
cURL
JSON response
- country: ISO2 code (SA).
- maturity: requested tenor (10Y).
- date: requested calendar date.
- yield: percent.
Python (requests)
import requests
params = {'country': 'SA', 'maturity': '10Y', 'date': '2025-06-15'}
r = requests.get('https://bonds-api.com/api/v1/historical',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params)
data = r.json()
print(data)
JavaScript (fetch)
const h = new URL('https://bonds-api.com/api/v1/historical');
h.searchParams.set('country', 'SA');
h.searchParams.set('maturity', '10Y');
h.searchParams.set('date', '2025-06-15');
fetch(h, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(console.log);
PHP (Guzzle)
<?php
require 'vendor/autoload.php';
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://bonds-api.com/api/v1/'
]);
$response = $client->get('historical', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'SA', 'maturity' => '10Y', 'date' => '2025-06-15']
]);
echo $response->getBody();
?
Endpoint 3: Time Series — Daily Yields Between Two Dates
Get a continuous series to chart the Saudi 10Y or compute volatility, drawdowns, and rolling stats.
cURL
JSON response
- series: array of {date, yield}, where yield is percent and date is YYYY-MM-DD.
Python (requests)
import requests
params = {
'country': 'SA',
'maturity': '10Y',
'start': '2025-11-05',
'end': '2026-11-05'
}
resp = requests.get('https://bonds-api.com/api/v1/timeseries',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params)
ts = resp.json()
print(ts)
JavaScript (fetch)
const t = new URL('https://bonds-api.com/api/v1/timeseries');
t.searchParams.set('country', 'SA');
t.searchParams.set('maturity', '10Y');
t.searchParams.set('start', '2025-11-05');
t.searchParams.set('end', '2026-11-05');
fetch(t, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(data => {
if (data.success) {
const dates = data.series.map(p => p.date);
const values = data.series.map(p => p.yield);
console.log(dates[0], values[0]);
}
});
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$url = 'https://bonds-api.com/api/v1/timeseries?country=SA&maturity=10Y&start=2025-11-05&end=2026-11-05';
echo file_get_contents($url, false, $ctx);
?
Endpoint 4: Spread — Saudi vs. Benchmark (e.g., US 10Y)
Compute the spread in basis points between Saudi Arabia and a benchmark such as the US Treasury for the same maturity.
cURL
JSON response
- spread_bps: difference in basis points (country minus benchmark).
- country_yield and benchmark_yield: percent.
Python (requests)
import requests
params = {'country': 'SA', 'benchmark': 'US', 'maturity': '10Y'}
r = requests.get('https://bonds-api.com/api/v1/spread',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params)
print(r.json())
JavaScript (fetch)
const s = new URL('https://bonds-api.com/api/v1/spread');
s.searchParams.set('country', 'SA');
s.searchParams.set('benchmark', 'US');
s.searchParams.set('maturity', '10Y');
fetch(s, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(console.log);
PHP (Guzzle)
<?php
require 'vendor/autoload.php';
$g = new \GuzzleHttp\Client(['base_uri' => 'https://bonds-api.com/api/v1/']);
$res = $g->get('spread', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'SA', 'benchmark' => 'US', 'maturity' => '10Y']
]);
echo $res->getBody();
?
Endpoint 5: Curve — Full Saudi Yield Curve
Get the full Saudi Arabia yield curve on the latest available date or a specified date to build analytics curves and interpolate durations.
cURL
JSON response
- curve: maturity-to-yield map, yields in percent.
- inverted: boolean flag indicating if short rates exceed long rates overall.
Saudi Curve Snapshot
| Maturity | Yield (%) |
|---|---|
| 1M | 5.31 |
| 3M | 5.27 |
| 6M | 5.18 |
| 1Y | 4.98 |
| 2Y | 4.25 |
| 5Y | 4.39 |
| 10Y | 4.52 |
| 30Y | 4.71 |
Python (requests)
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()
if curve.get('success'):
yc = curve['curve']
ten_y = yc.get('10Y')
print('SA 10Y from curve:', ten_y)
else:
print('Error:', curve.get('error'))
JavaScript (fetch)
const c = new URL('https://bonds-api.com/api/v1/curve');
c.searchParams.set('country', 'SA');
fetch(c, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(data => {
if (data.success) {
console.log('Inverted curve?', data.inverted);
console.log('10Y:', data.curve['10Y']);
}
});
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/curve?country=SA', false, $ctx);
?
Endpoint 6: Intraday — Saudi 10Y Snapshots Within a Day
For trading dashboards or alerting, pull UTC-stamped intraday snapshots for the Saudi 10Y on a requested date.
cURL
JSON response
- snapshots: array of intraday points with yield (percent) and fetched_at in UTC.
- count: number of snapshots returned.
- meta.timezone: "UTC" clarifies timestamp zone.
Python (requests)
import requests
params = {'country': 'SA', 'maturity': '10Y', 'date': '2026-11-05'}
resp = requests.get('https://bonds-api.com/api/v1/intraday',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params)
data = resp.json()
if data.get('success'):
for s in data['snapshots']:
print(s['fetched_at'], s['yield'])
else:
print('Error:', data.get('error'))
JavaScript (fetch)
const iurl = new URL('https://bonds-api.com/api/v1/intraday');
iurl.searchParams.set('country', 'SA');
iurl.searchParams.set('maturity', '10Y');
iurl.searchParams.set('date', '2026-11-05');
fetch(iurl, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(data => {
if (data.success) {
data.snapshots.forEach(s => console.log(s.fetched_at, s.yield));
}
});
PHP (Guzzle)
<?php
require 'vendor/autoload.php';
$g = new \GuzzleHttp\Client(['base_uri' => 'https://bonds-api.com/api/v1/']);
$res = $g->get('intraday', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'SA', 'maturity' => '10Y', 'date' => '2026-11-05']
]);
echo $res->getBody();
?
Endpoint 7: Fluctuation — Change, Minimum, Maximum Over a Period
Summarize the Saudi 10Y over a window: start yield, end yield, absolute change, and range. Useful for risk reports and monitoring.
cURL
JSON response
- start_yield and end_yield: percent on the boundary dates.
- change: end minus start (percent points).
- min and max: extremes within the window (percent).
Python (requests)
import requests
q = {
'countries': 'SA',
'maturity': '10Y',
'start': '2025-11-05',
'end': '2026-11-05'
}
r = requests.get('https://bonds-api.com/api/v1/fluctuation',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=q)
print(r.json())
JavaScript (fetch)
const f = new URL('https://bonds-api.com/api/v1/fluctuation');
f.searchParams.set('countries', 'SA');
f.searchParams.set('maturity', '10Y');
f.searchParams.set('start', '2025-11-05');
f.searchParams.set('end', '2026-11-05');
fetch(f, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(console.log);
PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$url = 'https://bonds-api.com/api/v1/fluctuation?countries=SA&maturity=10Y&start=2025-11-05&end=2026-11-05';
echo file_get_contents($url, false, $ctx);
?
Reading Dates, Handling Business-Day Gaps, and Building a Yield Curve
Dates returned by latest, historical, timeseries, and curve are day-level YYYY-MM-DD and represent the business day for which the yield is reported. Weekends and holidays will appear as gaps in the timeseries array; do not assume daily continuity. For intraday, fetched_at is the precise UTC timestamp for each snapshot.
To build a Saudi yield curve, you have two common paths:
- Use /curve to retrieve the full curve in one request, including short bills and longer-dated bonds, plus an inverted flag for high-level diagnostics.
- Use /latest with countries=SA and a maturities list (e.g., 1M,3M,6M,1Y,2Y,5Y,10Y,30Y) to compose a curve; ensure all yields share the same date from the payload.
In both cases, yields are in percent. If you need interpolated yields for non-standard tenors, apply your preferred method (e.g., cubic spline) on the maturity–yield map returned by /curve or stitched from /latest.
Use Cases: From Dashboards to Risk Engines
- Financial dashboards: display SA 10Y alongside intraday ticks for traders and finance teams. Use /intraday for a selected date and /latest for session summaries.
- Portfolio risk: recompute DV01 and PV based on updated 10Y levels and full curves from /curve; track spread moves via /spread vs. US Treasuries.
- Economic research: run event studies with /historical and /timeseries; summarize windows using /fluctuation.
- Backtesting: seed models with daily 10Y series from /timeseries and verify stability with range statistics from /fluctuation.
Explore more at bonds-api.com. When you’re ready, you can Register for an API key and start integrating.
Error Handling and Operational Notes
- 401: Missing or invalid X-API-Key. Ensure your header is present and correct.
- 403: Quota exceeded. Back off, implement retries with jitter, and consider caching.
- 404: No data for the requested country/maturity/date; check parameters or try a nearby business day.
- 422: Invalid parameter (date format YYYY-MM-DD, ISO2 country code like SA, known maturity like 10Y).
- 429: Rate limit exceeded. Use client-side throttling and small cache windows for latest/intraday.
- 500: Server error. Retry with exponential backoff and alert your monitoring.
Quick Integration Checklist
- Always send X-API-Key in the request header.
- Normalize yields as decimals or keep as percent consistently in your code; spreads from /spread are in bps.
- Parse date as YYYY-MM-DD; parse fetched_at as UTC ISO 8601.
- Cache curve and historical data; lightly cache latest/intraday.
- Check success before reading fields; log error payloads for observability.
FAQ
Q: How often are Saudi 10Y “latest” yields updated?
A: The latest endpoint returns the most recent business day with available data. For within-day monitoring, use /intraday on the current date to get UTC-stamped snapshots as they become available.
Q: Are yields quoted in percent or basis points?
A: All yields in latest, historical, timeseries, intraday, and curve are percent (e.g., 4.52 means 4.52%). Only the /spread endpoint returns spread_bps in basis points.
Q: How do I align series for spread calculations?
A: Use /spread to avoid alignment issues. If you compute spreads yourself from /timeseries, align on the intersection of business days across both countries and maturities.
Q: Can I construct a full Saudi curve without multiple requests?
A: Yes. Use /curve?country=SA to retrieve all maturities and an inverted flag in a single call. Alternatively, /latest supports a maturities list if you need a subset.
Q: What timezone should I assume for timestamps?
A: Dates are day-level (no timezone), while intraday timestamps are in UTC per the meta.timezone field and the fetched_at ISO 8601 Z suffix.
Build your Saudi Arabia 10-year yield integration now. Generate an API key and start testing in minutes: Register. You can also explore tools at the MCP and review endpoints at bonds-api.com.