You need reliable, developer-friendly access to Turkey’s sovereign bond yields so you can power dashboards, run fixed-income analytics, and track risk in your models. By the end of this article, you will know exactly how to query Turkey (TR) government bond yields from Bonds API, read the responses, build a yield curve and spreads, and handle practical details like market holidays, update cadence, and caching.
What you can build with Turkey bond yields
Turkey’s sovereign bonds span short-term bills to long-dated bonds, giving you a cross-section of the Turkish rates term structure. With the endpoints below, you can:
- Render a Turkey yield curve for multiple maturities in your frontend.
- Pull point-in-time yields for backtests and T+1 reconciliation.
- Track intraday snapshots for the 10Y benchmark.
- Compute spreads versus a benchmark like US Treasuries in basis points.
- Calculate changes, min, and max over rolling windows to monitor risk.
All data and examples reference bonds-api.com. To start making requests, you’ll need an API key. You can Register for one and explore more tooling at the MCP.
Before you call the API: authentication, units, dates, and markets
Base URL for all endpoints is https://bonds-api.com/api/v1/. All requests are HTTP GET calls, authenticated with your API key via the X-API-Key header. Yields are expressed in percent (for example, 4.52 means 4.52%). Spreads are returned in basis points (bps). Dates are strings in Y-m-d format (for example, 2026-11-09). Timestamps, when provided, are in UTC.
Business days and holidays affect availability. If you query a non-trading day, the latest endpoint will return the most recently available business day (see the examples). Historical, timeseries, and intraday endpoints require explicit dates; if the date is a holiday or no data is available, you will receive a 404 error with a descriptive message.
Update frequency is market-driven: latest and curve update as new official or market data becomes available during the trading day; intraday snapshots capture multiple points across the session in UTC time. Plan to cache latest and curve results for several minutes to reduce load and avoid rate limits, and consider aligning your refresh cadence to business hours in Turkey (with your app logic still using UTC timestamps returned by the API).
Endpoint: Latest Turkey yields
Use this to get the most recent available yields for one or more maturities in Turkey (TR). Omit the maturities parameter to retrieve all available tenors for the country.
cURL
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"
JSON response
{
"success": true,
"date": "2026-11-09",
"rates": {
"US_10Y": 4.856
},
"dates": {
"US_10Y": "2026-11-09"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "4f8e9da1-7153-4823-8d28-73713ee8ee9d",
"timestamp": "2026-11-09T00:04:05+00:00"
}
}
How to read it: yields are percentages; date is the market date (Y-m-d) for the yield; source indicates the data origin (for example, official). For example, TR 10Y is 4.52% as of 2026-11-09.
Python (requests)
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/latest",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "TR", "maturities": "2Y,10Y"}
)
resp.raise_for_status()
data = resp.json()
tr_2y = data["data"]["TR"]["2Y"]["yield"]
tr_10y = data["data"]["TR"]["10Y"]["yield"]
asof = data["data"]["TR"]["10Y"]["date"]
print(f"TR 2Y: {tr_2y}% | TR 10Y: {tr_10y}% (as of {asof})")
JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.searchParams.set("countries", "TR");
url.searchParams.set("maturities", "2Y,10Y");
fetch(url.toString(), {
method: "GET",
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
const twoY = json.data.TR["2Y"].yield;
const tenY = json.data.TR["10Y"].yield;
const date = json.data.TR["10Y"].date;
console.log(`TR 2Y=${twoY}% TR 10Y=${tenY}% as of ${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=TR&maturities=2Y,10Y";
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$y2 = $data["data"]["TR"]["2Y"]["yield"];
$y10 = $data["data"]["TR"]["10Y"]["yield"];
$date = $data["data"]["TR"]["10Y"]["date"];
echo "TR 2Y=$y2% TR 10Y=$y10% as of $date";
Endpoint: Historical yield on a specific date
Use this to retrieve the Turkey yield for a specific maturity on a specific calendar date. This is ideal for backtesting and valuation snapshots.
cURL
JSON response
How to read it: yield is a percentage; date is the requested Y-m-d; maturity is the tenor requested.
Python
import requests
params = {"country": "TR", "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()
row = r.json()
print(f'TR {row["maturity"]} on {row["date"]}: {row["yield"]}%')
JavaScript
const params = new URLSearchParams({ country: "TR", 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(row => console.log(`TR ${row.maturity} on ${row.date}: ${row.yield}%`));
PHP (Guzzle)
<?php
require 'vendor/autoload.php';
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://bonds-api.com/api/v1/',
'headers' => ['X-API-Key' => 'YOUR_API_KEY']
]);
$res = $client->get('historical', ['query' => ['country' => 'TR', 'maturity' => '10Y', 'date' => '2025-06-15']]);
$data = json_decode($res->getBody(), true);
echo "TR {$data['maturity']} on {$data['date']}: {$data['yield']}%";
Endpoint: Time series between two dates
Fetch a continuous daily series for a Turkey maturity between start and end (inclusive of business days in the range). Missing dates due to holidays are naturally excluded.
cURL
JSON response
How to read it: series is an array of daily observations; each yield is a percentage and each date is Y-m-d. Use this directly for charts or to compute rolling statistics.
Python
import requests
q = {"country": "TR", "maturity": "10Y", "start": "2025-11-09", "end": "2026-11-09"}
r = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q)
r.raise_for_status()
ts = r.json()["series"]
# Compute a simple average over the returned series
avg = sum(pt["yield"] for pt in ts) / len(ts)
print(f"Points: {len(ts)} | Average TR 10Y: {avg:.2f}%")
JavaScript
const params = new URLSearchParams({
country: "TR", maturity: "10Y", start: "2025-11-09", end: "2026-11-09"
});
fetch(`https://bonds-api.com/api/v1/timeseries?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
const points = json.series.length;
console.log(`Fetched ${points} observations for TR 10Y`);
});
PHP (file_get_contents)
<?php
$params = http_build_query([
'country' => 'TR', 'maturity' => '10Y', 'start' => '2025-11-09', 'end' => '2026-11-09'
]);
$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/timeseries?$params", false, $ctx);
$data = json_decode($json, true);
echo "Series length: " . count($data['series']);
Endpoint: Spread vs benchmark
Compute the Turkey spread in basis points against a benchmark country (for example, US or DE) at a specified maturity. If maturity is omitted, 10Y is used by default.
cURL
JSON response
How to read it: spread_bps is in basis points (1 bp = 0.01%), computed as TR minus benchmark. country_yield and benchmark_yield are in percent.
Python
import requests
q = {"country": "TR", "benchmark": "US", "maturity": "10Y"}
r = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q)
r.raise_for_status()
sp = r.json()
print(f"TR vs {sp['benchmark']} {sp['maturity']} spread: {sp['spread_bps']} bps")
JavaScript
const params = new URLSearchParams({ country: "TR", benchmark: "US", maturity: "10Y" });
fetch(`https://bonds-api.com/api/v1/spread?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => console.log(`TR-${json.benchmark} ${json.maturity} spread: ${json.spread_bps} bps`));
PHP (Guzzle)
<?php
require 'vendor/autoload.php';
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://bonds-api.com/api/v1/',
'headers' => ['X-API-Key' => 'YOUR_API_KEY']
]);
$res = $client->get('spread', ['query' => ['country' => 'TR', 'benchmark' => 'US', 'maturity' => '10Y']]);
$d = json_decode($res->getBody(), true);
echo "TR vs {$d['benchmark']} {$d['maturity']} spread: {$d['spread_bps']} bps";
Endpoint: Yield curve for Turkey
Retrieve the full yield curve for Turkey for the latest available market date (or a specific date). This is the fastest way to draw the curve and detect inversion.
cURL
JSON response
How to read it: curve contains maturities mapped to yields (percent). inverted is a boolean flag signaling whether short rates exceed long rates on that date.
Python
import requests
r = requests.get(
"https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "TR"}
)
r.raise_for_status()
curve = r.json()
points = curve["curve"]
ordered = ["1M","3M","6M","1Y","2Y","5Y","10Y","30Y"]
series = [(m, points[m]) for m in ordered if m in points]
print("TR curve as of", curve["date"], ":", series, "| inverted:", curve["inverted"])
JavaScript
const params = new URLSearchParams({ country: "TR" });
fetch(`https://bonds-api.com/api/v1/curve?${params}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
console.log(`Date=${json.date}, TR 10Y=${json.curve["10Y"]}% | inverted=${json.inverted}`);
});
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=TR", false, $ctx);
$d = json_decode($json, true);
echo "TR curve date: {$d['date']} | 2Y={$d['curve']['2Y']}% 10Y={$d['curve']['10Y']}%";
Endpoint: Intraday snapshots
Pull multiple yield snapshots within a trading day for a specific maturity. Use this for real-time dashboards and event monitoring.
cURL
JSON response
How to read it: snapshots is an array of yields in percent with fetched_at in ISO-8601 UTC. count equals the number of snapshots returned.
Python
import requests
q = {"country": "TR", "maturity": "10Y", "date": "2026-11-09"}
r = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q)
r.raise_for_status()
snap = r.json()
for pt in snap["snapshots"]:
print(pt["fetched_at"], "TR 10Y", pt["yield"], "%")
JavaScript
const p = new URLSearchParams({ country: "TR", maturity: "10Y", date: "2026-11-09" });
fetch(`https://bonds-api.com/api/v1/intraday?${p}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => json.snapshots.forEach(s => console.log(`${s.fetched_at} TR 10Y=${s.yield}%`)));
PHP (Guzzle)
<?php
require 'vendor/autoload.php';
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://bonds-api.com/api/v1/',
'headers' => ['X-API-Key' => 'YOUR_API_KEY']
]);
$res = $client->get('intraday', ['query' => ['country' => 'TR', 'maturity' => '10Y', 'date' => '2026-11-09']]);
$d = json_decode($res->getBody(), true);
foreach ($d['snapshots'] as $s) {
echo $s['fetched_at'] . " TR 10Y=" . $s['yield'] . "%\n";
}
Endpoint: Fluctuation over a period
Return the start and end yields, absolute change (in percentage points), and range (min, max) for a maturity over a period. Useful for risk summaries and alerts.
cURL
JSON response
How to read it: change is end_yield minus start_yield in percentage points; min and max are the observed extremes in percent during the period.
Python
import requests
q = {"countries": "TR", "maturity": "10Y", "start": "2025-11-09", "end": "2026-11-09"}
r = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q)
r.raise_for_status()
f = r.json()["data"]["TR"]
print(f"Start={f['start_yield']}% End={f['end_yield']}% Change={f['change']} pp Range [{f['min']}, {f['max']}]%")
JavaScript
const qp = new URLSearchParams({ countries: "TR", maturity: "10Y", start: "2025-11-09", end: "2026-11-09" });
fetch(`https://bonds-api.com/api/v1/fluctuation?${qp}`, {
headers: { "X-API-Key": "YOUR_API_KEY" }
})
.then(r => r.json())
.then(json => {
const tr = json.data.TR;
console.log(`TR 10Y change=${tr.change} pp, min=${tr.min}%, max=${tr.max}%`);
});
PHP (file_get_contents)
<?php
$params = http_build_query([
'countries' => 'TR', 'maturity' => '10Y',
'start' => '2025-11-09', 'end' => '2026-11-09'
]);
$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);
$d = json_decode($json, true);
$tr = $d['data']['TR'];
echo "TR 10Y delta={$tr['change']} pp; range {$tr['min']}%-{$tr['max']}%";
Error handling and common responses
If a request fails, you’ll receive JSON with success=false and an error message string. Typical cases include:
- 401: Missing or invalid X-API-Key — ensure the header is set and the key is correct.
- 403: Account quota exceeded — reduce frequency or cache responses.
- 404: No data for the requested country/maturity/date — verify ISO2 code TR, tenor, and valid dates.
- 422: Invalid parameter (for example, wrong date format). Dates must be Y-m-d.
- 429: Rate limit exceeded — back off and retry after a delay.
- 500: Server error — implement retries with jitter.
Production tip: cache latest, curve, and spread responses for a few minutes; cache historical and timeseries for much longer since they are immutable. For intraday, align your polling to the cadence you need, and stop polling after the session ends.
Building a Turkey yield curve and spreads for analytics
There are two common approaches:
- Single call for the entire curve: use /curve to get all available maturities at once (faster and consistent across tenors).
- Selective call with /latest: specify specific maturities when you only need a subset (for example, 2Y, 5Y, 10Y) for a small widget.
For risk dashboards, pair the curve with a spread: call /spread with country=TR and benchmark=US at 10Y to contextualize Turkey’s rates environment vs. US Treasuries. Use the bps result directly in charts and alerts. Because /curve also returns an inverted flag, you can quickly flag curve shapes without additional computation.
Operational notes: maturities, markets, and performance
- Maturities: common tenors include 1M, 3M, 6M, 1Y, 2Y, 5Y, 10Y, 30Y (see /curve output). Availability can vary by date.
- Business days: endpoints that take a date only return observations for trading days; holidays will not appear in time series. Use /latest for the most recent available if markets are closed.
- Timezones: intraday timestamps are UTC; normalize your UI to user locale if needed.
- Caching: store immutable historical results indefinitely; short-cache latest/curve/spread. Make use of ETag or application-level caching to respect rate limits.
- Validation: guard against missing maturities in the curve on certain dates — check for key existence before rendering.
If you need to script, test, or explore, start with the Bonds API docs and the MCP.
Compatibility sample: official US 10Y latest example
The following official sample demonstrates a latest request and response format variant. Copy these blocks verbatim when validating this behavior in your tooling.
cURL (official sample)
JSON (official sample)
How to read it: yields are percentages under rates; dates is the per-symbol date; currencies maps symbols to their currency; timestamp is ISO-8601 UTC. This sample is specific to the US 10Y schema shown here.
Putting it together: from API to production
For a performant Turkey rates module:
- On app load: call /curve?country=TR and render; cache for several minutes.
- If you need intraday visuals: start a lightweight poll against /intraday for 10Y during session hours; throttle outside hours.
- For historical pages: prefetch /timeseries (and /fluctuation for the summary pill) and cache long-term.
- For cross-country context: compute /spread against US at your key tenors.
- Handle errors centrally; on 404 or missing maturities, degrade gracefully with explanatory UI text.
Remember, yields are in percent and spreads in basis points. Dates are Y-m-d; intraday timestamps are UTC. Keep these units consistent across your models to avoid basis errors.
FAQ
What units does the API use for yields and spreads?
Yields are percentages (e.g., 4.52 means 4.52%). Spreads are in basis points (bps), where 100 bps equals 1%.
How should I handle market holidays for Turkey?
Use /latest for “most recent available” behavior. For point-in-time requests (/historical, /timeseries, /intraday), expect no data on holidays; handle 404 errors and, if needed, fall back to the previous business day in your app logic.
What timezone are timestamps in?
Any timestamp fields (for example, intraday fetched_at) are in UTC ISO-8601. The date fields are Y-m-d and correspond to the market date.
How frequently should I poll?
Cache latest and curve for several minutes. For intraday, match your polling interval to UI requirements and rate limits, then disable polling outside trading hours.
Can I compute yield curve inversion?
Yes. The /curve endpoint includes an inverted boolean. You can also compute your own curve diagnostics by comparing short vs. long maturities in the curve map.
Ready to integrate Turkey bond yields into your stack? Acquire your key and start calling the endpoints today: Get started with Bonds API. Explore more tools anytime at bonds-api.com.