You need clean, up-to-date Qatar 10-year sovereign yields you can query from your code, plus the rest of the Qatari curve for risk, pricing, and research. By the end of this article, you’ll be able to fetch the latest QA 10Y yield, retrieve history and intraday snapshots, compute spreads versus a benchmark, and build a full Qatar yield curve using Bonds API over a simple, key-authenticated REST interface.
What you’ll build: Qatar 10Y and the Qatar curve, ready for analytics
Bonds API returns sovereign bond yields as JSON over HTTPS. Yields are expressed in percent (for example 4.52 means 4.52%). Spreads are expressed in basis points (1 bp = 0.01%). Dates are ISO-8601 (YYYY-MM-DD). Intraday timestamps are ISO-8601 with time and Z for UTC, for example 2026-10-02T12:00:00Z.
You will use GET endpoints only, authenticated with an API key in the X-API-Key request header. The base URL is https://bonds-api.com/api/v1/.
Useful links while you read:
Note on the live sample block from the docs
The following block is provided by the documentation and must be reproduced verbatim. It shows a live-style sample for the US 10Y using a query-string API key and an alternate response shape. Use it to sanity-check connectivity. The rest of this tutorial focuses on Qatar (QA) and uses the documented X-API-Key header and the /api/v1/ endpoints and schemas.
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"{
"success": true,
"date": "2026-10-02",
"rates": {
"US_10Y": 5.252
},
"dates": {
"US_10Y": "2026-10-02"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "a6d610d1-c2e6-4858-8b4f-15915fa8a6fe",
"timestamp": "2026-10-02T00:06:04+00:00"
}
}Authentication, countries, maturities, and units
Authentication: send your key in the X-API-Key header (example: X-API-Key: YOUR_API_KEY). Countries use ISO2 codes; for Qatar, use QA. Maturities use standard codes such as 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y. All Bonds API requests use the GET method.
Data units and formats:
- yield: percentage (e.g., 4.52 means 4.52%)
- spread_bps: basis points (e.g., 215 means 2.15%)
- date: YYYY-MM-DD (trading days; if you query a non-business day, the latest available day’s data is generally returned by “latest” endpoints)
- fetched_at (intraday): ISO-8601 timestamp in UTC (e.g., 2026-10-02T12:00:00Z)
To get an API key, visit Register. You can also explore endpoints interactively in the MCP.
Latest yields: get the current QA 10Y (and more)
Use /api/v1/latest to retrieve current Qatar yields. Provide one or more countries, and optionally a subset of maturities if you only need certain tenors.
cURL
Python (requests)
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "QA", "maturities": "2Y,10Y"}
)
data = resp.json()
# Example: read QA 10Y yield and date
qa_10y_yield = data["data"]["QA"]["10Y"]["yield"]
qa_10y_date = data["data"]["QA"]["10Y"]["date"]
print("QA 10Y:", qa_10y_yield, "on", qa_10y_date)JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.search = new URLSearchParams({ countries: "QA", maturities: "2Y,10Y" });
fetch(url.toString(), {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
const qa10 = json.data.QA["10Y"];
console.log(`QA 10Y ${qa10.yield}% on ${qa10.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=QA&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$qa10 = $data["data"]["QA"]["10Y"];
echo "QA 10Y {$qa10["yield"]}% on {$qa10["date"]}\n";JSON response (official)
How to read it:
- yield is in percent.
- date is the valuation date (YYYY-MM-DD) for the yield.
- source indicates provenance of the figure (e.g., official).
Historical: Qatar 10Y on a specific date
Use /api/v1/historical to retrieve the QA 10Y yield for an exact date. The date parameter is YYYY-MM-DD.
cURL
Python
import requests
params = {"country": "QA", "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)
h = r.json()
print(h["country"], h["maturity"], h["date"], h["yield"])JavaScript
const params = new URLSearchParams({
country: "QA",
maturity: "10Y",
date: "2025-06-15"
});
fetch("https://bonds-api.com/api/v1/historical?" + params.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(h => console.log(h.country, h.maturity, h.date, h.yield));PHP (Guzzle)
<?php
require 'vendor/autoload.php';
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://bonds-api.com/api/v1/'
]);
$res = $client->request('GET', 'historical', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'QA', 'maturity' => '10Y', 'date' => '2025-06-15']
]);
$h = json_decode($res->getBody(), true);
echo $h['yield'];JSON response (official)
Fields:
- yield: percent
- date: the exact valuation date requested
- source: data provenance
Time series: daily QA 10Y between two dates
Use /api/v1/timeseries to retrieve daily yields between start and end (inclusive). The series will follow business days; weekends/holidays are typically excluded.
cURL
Python
import requests
params = {
"country": "QA", "maturity": "10Y",
"start": "2025-10-02", "end": "2026-10-02"
}
r = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
ts = r.json()["series"]
# Compute simple changes
chg = ts[-1]["yield"] - ts[0]["yield"]
print("Obs:", len(ts), "Change:", round(chg, 2), "%")JavaScript
const params = new URLSearchParams({
country: "QA", maturity: "10Y",
start: "2025-10-02", end: "2026-10-02"
});
fetch("https://bonds-api.com/api/v1/timeseries?" + params.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => {
const series = j.series;
console.log("First", series[0].date, series[0].yield);
console.log("Last", series[series.length - 1].date, series[series.length - 1].yield);
});PHP (file_get_contents)
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$q = http_build_query(["country" => "QA", "maturity" => "10Y", "start" => "2025-10-02", "end" => "2026-10-02"]);
$json = file_get_contents("https://bonds-api.com/api/v1/timeseries?$q", false, $ctx);
$data = json_decode($json, true);
echo count($data["series"]);JSON response (official)
Fields:
- series: array of daily observations with date (YYYY-MM-DD) and yield (percent)
Spread: QA versus a benchmark (e.g., US 10Y)
Use /api/v1/spread to compute the spread in basis points between Qatar and a benchmark (e.g., US for U.S. Treasuries) at a specific maturity (defaults to 10Y).
cURL
Python
import requests
sp = requests.get(
"https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "QA", "benchmark": "US", "maturity": "10Y"}
).json()
print("Spread (bps):", sp["spread_bps"],
"QA:", sp["country_yield"], "US:", sp["benchmark_yield"])JavaScript
const params = new URLSearchParams({ country: "QA", benchmark: "US", maturity: "10Y" });
fetch("https://bonds-api.com/api/v1/spread?" + params.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(sp => console.log(`Spread ${sp.spread_bps} bps (QA ${sp.country_yield}% vs US ${sp.benchmark_yield}%)`));PHP (Guzzle)
<?php
$client = new \GuzzleHttp\Client(['base_uri' => 'https://bonds-api.com/api/v1/']);
$res = $client->request('GET', 'spread', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'QA', 'benchmark' => 'US', 'maturity' => '10Y']
]);
$sp = json_decode($res->getBody(), true);
echo $sp['spread_bps'];JSON response (official)
Fields:
- spread_bps: difference in basis points (country minus benchmark)
- country_yield, benchmark_yield: both in percent
Curve: full Qatar term structure
Use /api/v1/curve to retrieve the QA curve for the latest available date (or a specific date). Returns maturities across bills and bonds where available, plus an inverted flag.
cURL
Python
import requests
cv = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "QA"}).json()
curve = cv["curve"]
tenors = ["1M","3M","6M","1Y","2Y","5Y","10Y","30Y"]
print("Date:", cv["date"], "Inverted:", cv["inverted"])
for t in tenors:
if t in curve:
print(t, curve[t])JavaScript
fetch("https://bonds-api.com/api/v1/curve?country=QA", {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(cv => {
console.log("Curve date:", cv.date, "Inverted:", cv.inverted);
console.log(cv.curve);
});PHP (file_get_contents)
<?php
$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?country=QA", false, $ctx);
$cv = json_decode($json, true);
echo $cv["date"] . " inverted=" . ($cv["inverted"] ? "yes" : "no");JSON response (official)
Fields:
- curve: mapping from tenor to yield in percent
- inverted: true if short-end yields exceed long-end in a way that signals inversion (boolean)
- date: the curve’s valuation date
| Maturity | Example key | How to use |
|---|---|---|
| 1M, 3M, 6M | 1M, 3M, 6M | Short-term funding and discounting |
| 1Y, 2Y | 1Y, 2Y | Policy-sensitive segment |
| 5Y, 10Y | 5Y, 10Y | Benchmark curve points (duration/risk) |
| 30Y | 30Y | Long-end pricing, ALM |
Intraday: QA 10Y snapshots within a day
Use /api/v1/intraday to obtain multiple yield snapshots for a specific date and maturity. Timestamps are in UTC.
cURL
Python
import requests
itd = requests.get("https://bonds-api.com/api/v1/intraday", headers={"X-API-Key": "YOUR_API_KEY"}, params={
"country": "QA", "maturity": "10Y", "date": "2026-10-02"
}).json()
for s in itd["snapshots"]:
print(s["fetched_at"], s["yield"], s["source"])JavaScript
const qs = new URLSearchParams({ country: "QA", maturity: "10Y", date: "2026-10-02" });
fetch("https://bonds-api.com/api/v1/intraday?" + qs, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => j.snapshots.forEach(s => console.log(s.fetched_at, s.yield, s.source)));PHP (Guzzle)
<?php
$client = new \GuzzleHttp\Client(['base_uri' => 'https://bonds-api.com/api/v1/']);
$res = $client->request('GET', 'intraday', [
'headers' => ['X-API-Key' => 'YOUR_API_KEY'],
'query' => ['country' => 'QA', 'maturity' => '10Y', 'date' => '2026-10-02']
]);
$j = json_decode($res->getBody(), true);
echo $j['count'];JSON response (official)
Fields:
- snapshots[].yield: percent
- snapshots[].fetched_at: UTC timestamp
- count: number of snapshots returned
- meta.timezone: “UTC”
Fluctuation: change, min, and max for QA 10Y over a period
Use /api/v1/fluctuation to summarize begin/end yields, change, and range over a period for one or more countries at a given maturity.
cURL
Python
import requests
fq = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "QA", "maturity": "10Y", "start": "2025-10-02", "end": "2026-10-02"}).json()
qa = fq["data"]["QA"]
print("Start", qa["start_yield"], "End", qa["end_yield"], "Change", qa["change"], "Min", qa["min"], "Max", qa["max"])JavaScript
const params = new URLSearchParams({
countries: "QA", maturity: "10Y", start: "2025-10-02", end: "2026-10-02"
});
fetch("https://bonds-api.com/api/v1/fluctuation?" + params.toString(), {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(j => console.log(j.data.QA));PHP (file_get_contents)
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$q = http_build_query(["countries" => "QA", "maturity" => "10Y", "start" => "2025-10-02", "end" => "2026-10-02"]);
$j = file_get_contents("https://bonds-api.com/api/v1/fluctuation?$q", false, $ctx);
$fq = json_decode($j, true);
print_r($fq["data"]["QA"]);JSON response (official)
Fields:
- start_yield, end_yield, change: percent and percent change (end minus start)
- min, max: period’s min and max yields in percent
Operational details: maturities, business days, updates, and caching
Maturities: the curve endpoint for Qatar includes short bills (1M–6M), belly (1Y–5Y), and long end (10Y, 30Y) where available. For single maturities, use codes like 10Y consistently across endpoints. When you need multiple points, prefer /api/v1/curve to avoid stitching multiple single calls.
Business days and market holidays: daily time series typically contain business days only. If you request a non-business day in /historical, expect a 404 if that exact date has no data; for “latest,” the API returns the most recent available day. Design your UI to handle gaps around holidays and weekends.
Update frequency: latest yields are updated when source markets publish or when official sources release new figures. Intraday snapshots provide multiple timestamps within a calendar day (UTC). Use /intraday for time-of-day sensitivity; otherwise, daily series are sufficient.
Caching guidance:
- Latest and curve: consider a short cache (e.g., 30–120 seconds) for dashboards.
- Historical/time series: can be cached longer since inputs are immutable.
- Intraday: cache per time bucket (e.g., 1–5 minutes) if you refresh screens frequently.
Error handling: all endpoints return success=false with an error message on failures. Common cases include 401 (missing/invalid key), 403 (quota), 404 (no data for requested key/date), 422 (invalid parameter), 429 (rate limit), and 500 (server error). Build clear fallbacks and user notices for these states.
How to assemble a Qatar 10Y view and curve in your app
For a live 10Y tile: call /api/v1/latest with countries=QA&maturities=10Y. Show yield (percent) with date in YYYY-MM-DD to signal staleness on holidays. For a period chart: call /api/v1/timeseries with start and end; plot yield over time, using date strings as x-axis categories.
For the curve: one request to /api/v1/curve with country=QA yields a tenor-to-yield map. Sort tenors in logical order (1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y) for plotting. If cv["inverted"] is true, flag your curve chart accordingly.
For relative value: /api/v1/spread with country=QA, benchmark=US, maturity=10Y returns spread_bps and both leg yields. Convert bps to percent by dividing by 100 if needed (e.g., 215 bps = 2.15%).
Use cases for fixed-income analytics
- Portfolio risk: drive DV01 scenarios off QA 10Y and curve shifts using /timeseries, /fluctuation, and /curve.
- Dashboarding: show latest QA 2Y/10Y with a 2s10s spread computed client-side from /latest (two maturities) or server-side via /curve.
- Economics and research: compare QA 10Y versus US 10Y level and vol using /spread and /fluctuation, and annotate macro events.
- Pricing utilities: interpolate missing points on the curve after fetching the available QA curve to feed discount factors or par-based models.
Explore more endpoints and examples at bonds-api.com. When you’re ready to integrate, Register for an API key and test queries in the MCP.
Troubleshooting and common patterns
- Missing data for a tenor on a date: use /curve for the same date to confirm availability of nearby points; interpolate if appropriate for your model.
- Handling multiple symbols: /latest supports multiple countries and maturities; use comma-separated lists and parse the nested data map.
- Time zones: daily dates are day-level values; intraday timestamps are UTC. Normalize to UTC in servers before local display formatting.
- Resilience: back off and retry on 429 with exponential delays; capture error.error strings in logs for faster diagnosis.
FAQ
What unit are yields and spreads returned in?
Yields are in percent (e.g., 4.52 for 4.52%). Spreads are in basis points (e.g., 215 for 2.15%).
What time zone are timestamps in?
Daily date fields use YYYY-MM-DD without time. Intraday “fetched_at” timestamps are in UTC with a trailing Z (e.g., 2026-10-02T12:00:00Z).
How do I fetch several Qatar maturities at once?
Use /api/v1/curve to get the full QA curve, or /api/v1/latest with maturities like 2Y,5Y,10Y comma-separated.
How do I compute the QA–US 10Y spread?
Call /api/v1/spread with country=QA, benchmark=US, maturity=10Y. Read spread_bps (basis points) and the component yields.
What happens on market holidays?
Daily series typically skip non-business days. /historical on a non-business day may return 404 if no data exists for that exact date; /latest returns the most recent available.
Build your Qatar 10Y tile, curve, and spread tools in minutes. Get started with Bonds API or Register for an API key now, then validate requests in the MCP.