You need reliable, machine-readable South Africa 10-year sovereign yields that plug straight into models, dashboards, and risk tools. By the end of this guide, you will know how to fetch the latest ZA 10Y yield, query specific historical dates, build a time series and a full ZA curve, compute US–ZA 10Y spread in basis points, and incorporate intraday snapshots—all via the Bonds API REST endpoints.
What you will build and how yields are expressed
This article focuses on South Africa (ISO2: ZA) and the 10-year (10Y) sovereign yield. All endpoints are HTTP GET on https://bonds-api.com/api/v1/ and require an API key. Yields are returned as percentages (for example, 4.52 means 4.52%). Spreads are returned in basis points (for example, 215 means 2.15%). Dates are Y-m-d (for example, 2026-10-01). Intraday timestamps are ISO 8601 in UTC (for example, 2026-10-01T12:00:00Z).
You can combine multiple maturities to build a ZA yield curve or stick to 10Y for macro and risk analysis. Market calendars and holidays matter; daily endpoints reflect the latest available business day. Intraday snapshots give you multiple readings on the same date and are useful for trading hours monitoring; cache them conservatively if you surface them into dashboards.
Links for reference: visit bonds-api.com and the developer MCP to browse models and tools.
Official sample (copy exactly)
The following official sample demonstrates a live response shape for the latest 10Y ZA yield. Copy it verbatim to quickly verify connectivity.
curl -s "https://bonds-api.com/api/v1/latest?countries=ZA&maturities=10Y&api_key=YOUR_API_KEY"{
"success": true,
"date": "2026-10-01",
"rates": {
"ZA_10Y": 8.955
},
"dates": {
"ZA_10Y": "2026-10-01"
},
"currencies": {
"ZA_10Y": "ZAR"
},
"meta": {
"request_id": "79f8cbd9-f27a-482e-b2e4-2725bc54bed7",
"timestamp": "2026-10-01T00:04:05+00:00"
}
}How to read this sample:
- ZA_10Y is the South Africa 10-year tenor.
- rates.ZA_10Y is the yield level (percentage). 8.955 means 8.955%.
- date and dates.ZA_10Y are in Y-m-d. meta.timestamp is ISO 8601 UTC.
- currencies.ZA_10Y shows the local currency context (ZAR).
Endpoint: Latest yields (current level)
Use this to fetch the latest available ZA yields. You can request multiple maturities in one call to assemble a snapshot curve (for example, 2Y and 10Y together). Authentication is via X-API-Key header.
cURL
JSON response
Fields:
- yield: percentage value (for example, 4.52 means 4.52%).
- date: Y-m-d for the business day associated with the yield.
- source: origin tag (for example, official).
Python (requests)
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "ZA", "maturities": "2Y,10Y"}
)
resp.raise_for_status()
data = resp.json()
za_2y = data["data"]["ZA"]["2Y"]["yield"]
za_10y = data["data"]["ZA"]["10Y"]["yield"]
za_10y_date = data["data"]["ZA"]["10Y"]["date"]
print("ZA 2Y:", za_2y, "%", "ZA 10Y:", za_10y, "% on", za_10y_date)JavaScript (fetch)
const url = "https://bonds-api.com/api/v1/latest?countries=ZA&maturities=2Y,10Y";
fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(json => {
const tenY = json.data.ZA["10Y"].yield;
const date = json.data.ZA["10Y"].date;
console.log(`ZA 10Y ${tenY}% on ${date}`);
});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=ZA&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
echo "ZA 10Y: " . $data["data"]["ZA"]["10Y"]["yield"] . "%\n";Endpoint: Historical (yield on a specific date)
Fetch the ZA 10Y value on a single date (business day). If the date is a non-trading day or holiday, expect a 404 if no data is available for that exact date.
cURL
JSON response
Fields:
- yield: percentage (for example, 4.38%).
- date: Y-m-d exact query date.
Python
import requests
params = {"country": "ZA", "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)
r.raise_for_status()
hist = r.json()
print(hist["maturity"], hist["date"], hist["yield"])JavaScript
const u = "https://bonds-api.com/api/v1/historical?country=ZA&maturity=10Y&date=2025-06-15";
fetch(u, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log(`ZA ${j.maturity} on ${j.date}: ${j.yield}%`));PHP
<?php
$ctx = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$url = "https://bonds-api.com/api/v1/historical?country=ZA&maturity=10Y&date=2025-06-15";
$out = file_get_contents($url, false, $ctx);
echo $out;Endpoint: Time series (between two dates)
Pull a continuous ZA 10Y series between start and end (inclusive). Data points typically align with business days; weekends/holidays will be omitted.
cURL
JSON response
Fields:
- series: array of daily points; date as Y-m-d; yield as percentage.
Python
import requests
params = {"country": "ZA", "maturity": "10Y",
"start": "2025-10-01", "end": "2026-10-01"}
res = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
res.raise_for_status()
ts = res.json()["series"]
print("Observations:", len(ts), "First:", ts[0])JavaScript
const tsUrl = "https://bonds-api.com/api/v1/timeseries?country=ZA&maturity=10Y&start=2025-10-01&end=2026-10-01";
fetch(tsUrl, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
const last = j.series[j.series.length - 1];
console.log(`Last ZA 10Y: ${last.yield}% on ${last.date}`);
});PHP
<?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=ZA&maturity=10Y&start=2025-10-01&end=2026-10-01";
echo file_get_contents($url, false, $ctx);Endpoint: Spread vs benchmark (basis points)
Compare ZA to a benchmark (for example, US Treasuries) at a specified maturity. The default maturity is 10Y if omitted. Output is the spread in basis points along with each underlying yield.
cURL
JSON response
Fields:
- spread_bps: difference in basis points (1 bp = 0.01%).
- country_yield, benchmark_yield: percentage yields for ZA and the benchmark.
Python
import requests
p = {"country": "ZA", "benchmark": "US", "maturity": "10Y"}
r = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p)
j = r.json()
print(f"ZA-US 10Y spread: {j['spread_bps']} bps (ZA {j['country_yield']}% vs US {j['benchmark_yield']}%)")JavaScript
const sUrl = "https://bonds-api.com/api/v1/spread?country=ZA&benchmark=US&maturity=10Y";
fetch(sUrl, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log(`Spread: ${j.spread_bps} bps`));PHP
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$url = "https://bonds-api.com/api/v1/spread?country=ZA&benchmark=US&maturity=10Y";
$out = file_get_contents($url, false, $ctx);
echo $out;Endpoint: Curve (full yield curve for ZA)
Request the full ZA curve for the latest available date, or a specific date. Use this to power curve visualizations or curve-fit models. The response flags whether the curve is inverted.
cURL
JSON response
Fields:
- curve: maturity-to-yield map; values are percentages.
- inverted: true if short maturities exceed long ones.
Python
import requests
r = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "ZA"})
curve = r.json()
ten_y = curve["curve"]["10Y"]
print("ZA curve date", curve["date"], "10Y", ten_y, "%", "inverted:", curve["inverted"])JavaScript
const cUrl = "https://bonds-api.com/api/v1/curve?country=ZA";
fetch(cUrl, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
const points = Object.entries(j.curve);
console.log(`ZA curve on ${j.date}:`, points);
});PHP
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$url = "https://bonds-api.com/api/v1/curve?country=ZA";
echo file_get_contents($url, false, $ctx);Endpoint: Intraday snapshots
For a given date and maturity, fetch multiple intraday snapshots (UTC-stamped). Use this for monitoring moves during trading hours and computing intraday volatility. Cache respectfully; do not hammer the endpoint if you show the same data within short intervals.
cURL
JSON response
Fields:
- snapshots[].yield: percentage; fetched_at: ISO 8601 UTC.
- count: number of snapshots returned; meta.timezone gives context (UTC).
Python
import requests
p = {"country": "ZA", "maturity": "10Y", "date": "2026-10-01"}
r = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p)
snap = r.json()["snapshots"]
for s in snap:
print(s["fetched_at"], s["yield"])JavaScript
const iUrl = "https://bonds-api.com/api/v1/intraday?country=ZA&maturity=10Y&date=2026-10-01";
fetch(iUrl, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
j.snapshots.forEach(s => console.log(`${s.fetched_at} ${s.yield}%`));
});PHP
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$url = "https://bonds-api.com/api/v1/intraday?country=ZA&maturity=10Y&date=2026-10-01";
echo file_get_contents($url, false, $ctx);Endpoint: Fluctuation (change, min, max over a period)
Compute change, min, and max for ZA over a period at a given maturity. This is useful for risk reports and performance summaries.
cURL
JSON response
Fields:
- start_yield, end_yield, change, min, max: percentages across the specified period.
Python
import requests
p = {"countries": "ZA", "maturity": "10Y", "start": "2025-10-01", "end": "2026-10-01"}
r = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p)
stats = r.json()["data"]["ZA"]
print("Δ:", stats["change"], "Min:", stats["min"], "Max:", stats["max"])JavaScript
const fUrl = "https://bonds-api.com/api/v1/fluctuation?countries=ZA&maturity=10Y&start=2025-10-01&end=2026-10-01";
fetch(fUrl, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log(j.data.ZA));PHP
<?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=ZA&maturity=10Y&start=2025-10-01&end=2026-10-01";
echo file_get_contents($url, false, $ctx);Building a South Africa yield curve and working with market calendars
There are two approaches to plotting the ZA curve:
- Single-call curve: Use /curve for a ready-to-plot maturity map and the inverted flag.
- Assemble from latest: Use /latest with multiple maturities (for example, 1Y,2Y,5Y,10Y,30Y) to assemble your own curve snapshot, helpful if you need a subset of tenors.
Practical notes:
- Business days and holidays: Returns align to the latest available business day for South Africa. On non-trading days, the latest endpoint returns the most recent day with data; historical requires an exact date (and may 404 if no data for that date).
- Update frequency: Daily endpoints reflect the most recent official update; intraday provides multiple UTC-stamped snapshots for the requested date.
- Caching: Cache daily endpoints (latest, curve) for the session or page lifespan. Cache intraday more conservatively if polling (for example, per-minute or based on UI refresh cycles). Handle 429 responses with backoff.
- Units and parsing: Treat yields as percentages. Time series and daily dates are Y-m-d; intraday timestamps are ISO 8601 UTC.
- Error handling: Check success and handle status-specific errors noted below.
ZA maturities commonly available
The curve response example shows a broad span of ZA tenors that are typically available:
| Maturity | Use |
|---|---|
| 1M, 3M, 6M | Cash and bill curve; short-rate and policy expectations. |
| 1Y, 2Y | Front-end bond curve; near-term macro sensitivity. |
| 5Y | Intermediate point for curve shape. |
| 10Y | Benchmark long-end for macro, CDS proxy, and valuations. |
| 30Y | Long duration; liability and ALM analysis. |
Sovereign bonds and common analytics on ZA 10Y
Sovereign bonds are debt issued by national governments. The yield is the market’s required return; it reflects inflation expectations, policy rates, fiscal outlook, and risk premia. For ZA 10Y, analysts often monitor:
- Level and trend: Latest yield and its time-series trajectory.
- Curve shape: 2s10s and 5s30s moves for macro signals and carry/roll risk.
- Cross-market spread: ZA 10Y vs US 10Y in basis points via /spread.
- Intraday dynamics: Session highs/lows from /intraday for event studies.
Use cases include financial dashboards, portfolio risk widgets, and macro research notebooks. You can build all of these directly from bonds-api.com endpoints above.
Error handling and operational notes
Common error response shape: success=false with an error message string. Typical HTTP statuses:
- 401: Missing or invalid X-API-Key.
- 403: Account quota exceeded.
- 404: No data for the requested country/maturity/date combination.
- 422: Invalid parameter (for example, wrong date format).
- 429: Rate limit exceeded.
- 500: Server error.
Implementation tips:
- Validate inputs (ISO2 codes, maturities, date formats) before calling.
- Retry/backoff on 429/500; do not retry 4xx except 429 after a waiting period.
- Log success flags and the parsed dates to ensure you are using the intended business day.
End-to-end example workflow for ZA 10Y
A minimal fixed income dashboard flow:
- Fetch the latest ZA 10Y and 2Y via /latest to show levels and 2s10s slope.
- Load a 1-year ZA 10Y /timeseries for the sparkline and compute 20d/60d averages.
- Call /spread with benchmark=US to show the cross-market differential in bps.
- If the user selects “curve,” query /curve and plot the maturity map; annotate inverted if true.
- On trading days, optionally pull /intraday to show today’s moves and session high/low.
This flow uses only GET endpoints and the X-API-Key header. For quick API exploration, you can also visit the Bonds API MCP and the links below to register.
Additional references and links
FAQ
How are yields expressed in the API?
All yields are percentages. For example, 4.52 means 4.52%.
What timezone are timestamps in?
Daily dates are Y-m-d without timezone. Intraday fetched_at values are ISO 8601 in UTC and meta.timezone indicates UTC.
How do I handle holidays and weekends?
Daily endpoints reflect the most recent business day with data. If you query a historical date that is a non-trading day and no data exists for that date, expect a 404.
Can I request multiple maturities at once?
Yes. Use /latest with maturities like 1Y,2Y,5Y,10Y,30Y for a snapshot. Or call /curve for the full maturity set and an inverted flag.
What’s the unit of the spread endpoint?
spread_bps is in basis points (1 bp = 0.01%). The endpoint also returns country_yield and benchmark_yield as percentages.
Build your ZA 10Y integration now. Explore the endpoints above and then get an API key with this one-click link: Register. For model browsing and testing tools, open the MCP.
