Teams building fixed-income dashboards and analytics often struggle to source clean, well-structured Turkey government bond yields they can pull directly into code. By the end of this article, you will be able to fetch the latest Turkish sovereign yields, query historical and intraday values, compute spreads versus benchmarks, and assemble a full Turkey yield curve using the Bonds API over simple GET requests.
What you will build with Turkey sovereign yields
This guide focuses on Turkey (ISO2: TR) using the Bonds API. You will learn how to:
- Pull the latest Turkey yields by maturity and interpret units (percent vs basis points).
- Retrieve historical points, intraday snapshots, and time series for modeling.
- Construct the Turkey yield curve for a specific date and detect inversions.
- Calculate spreads versus a benchmark (e.g., US Treasuries) in basis points.
- Handle business days, holidays, update frequency, and caching strategies.
All examples use GET requests to https://bonds-api.com/api/v1/ with an X-API-Key header. Explore more at bonds-api.com and review the MCP for tooling around the API.
Data model, units, and timestamps
Across endpoints, yields are expressed as percentages (for example, 4.52 means 4.52% annualized yield). When you query spreads, the spread is returned in basis points (bps), where 1 basis point = 0.01%.
- Dates are in Y-m-d format, e.g., 2026-10-25.
- Timestamps, where present (e.g., intraday fetched_at), are ISO 8601 strings with timezone information, typically UTC.
- Sources may be labeled as "official" (daily close/official publications) or "market" (in-session snapshots).
For production systems, cache daily results per country and maturity for the trading day. Intraday snapshots can be cached with shorter TTLs (e.g., minutes) depending on your refresh needs.
Latest Turkey yields by maturity
Use this endpoint to fetch the most recent available daily yields for Turkey across selected or all maturities. If you omit maturities, the API returns all available for the country. This is ideal for displaying a dashboard tile or initializing a curve calculation.
Endpoint
GET /api/v1/latest
- Required: countries (ISO2 comma-separated). For Turkey, use TR.
- Optional: maturities (comma-separated like 2Y,10Y); omit to return all.
cURL
curl -s "https://bonds-api.com/api/v1/latest?countries=US&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': 'TR', 'maturities': '2Y,10Y'}
)
data = resp.json()
# Access yields in percent:
# data['data']['TR']['2Y']['yield'], data['data']['TR']['10Y']['yield']
# Dates are Y-m-d: data['data']['TR']['10Y']['date']
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(data => {
const y2 = data.data.TR['2Y'].yield; // percent
const y10 = data.data.TR['10Y'].yield; // percent
const d10 = data.data.TR['10Y'].date; // Y-m-d
console.log({ y2, y10, d10 });
});
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);
// $data['data']['TR']['10Y']['yield'] is percent
?>
JSON response example
{
"success": true,
"date": "2026-10-23",
"rates": {
"US_10Y": 5
},
"dates": {
"US_10Y": "2026-10-23"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "c7272057-636d-433b-9d01-0ed5c605728a",
"timestamp": "2026-10-25T00:05:55+00:00"
}
}
How to read it: "yield" fields are percentages. "date" is the valuation date in Y-m-d. "source" indicates origin. Use these values directly to compute level differences or to assemble a curve with other maturities from the same date.
Official sample (verbatim)
The following live-format sample is provided verbatim for reference:
Turkey yield on a specific date
To reproducibly backtest or align with an event date, request Turkey’s sovereign yield for a single maturity on a specific date.
Endpoint
GET /api/v1/historical
- Required: country (TR), maturity (e.g., 10Y), date (Y-m-d)
cURL
Python (requests)
import requests
resp = requests.get(
'https://bonds-api.com/api/v1/historical',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TR', 'maturity': '10Y', 'date': '2025-06-15'}
)
h = resp.json()
# h['yield'] is percent, h['date'] is Y-m-d
JavaScript (fetch)
const url = new URL('https://bonds-api.com/api/v1/historical');
url.searchParams.set('country', 'TR');
url.searchParams.set('maturity', '10Y');
url.searchParams.set('date', '2025-06-15');
fetch(url.toString(), { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(h => {
console.log(h.yield, h.date); // percent, Y-m-d
});
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/historical?country=TR&maturity=10Y&date=2025-06-15';
$h = json_decode(file_get_contents($url, false, $ctx), true);
// $h['yield'] in percent
?>
JSON response example
Use this when you need an exact daily close or official published value for a backtest or event study.
Turkey time series for modeling and charts
Pull a date-range series for one Turkey maturity to power charts, regressions, and factor models. The series is sampled on business days; non-trading days (weekends and local holidays) will be absent.
Endpoint
GET /api/v1/timeseries
- Required: country (TR), maturity (e.g., 10Y), start (Y-m-d), end (Y-m-d)
cURL
Python (requests)
import requests
params = {'country': 'TR', 'maturity': '10Y', 'start': '2025-10-25', 'end': '2026-10-25'}
resp = requests.get('https://bonds-api.com/api/v1/timeseries', headers={'X-API-Key': 'YOUR_API_KEY'}, params=params)
ts = resp.json()
# ts['series'] is a list of { 'date': 'Y-m-d', 'yield': percent }
JavaScript (fetch)
const u = new URL('https://bonds-api.com/api/v1/timeseries');
u.searchParams.set('country', 'TR');
u.searchParams.set('maturity', '10Y');
u.searchParams.set('start', '2025-10-25');
u.searchParams.set('end', '2026-10-25');
fetch(u, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(ts => {
// Iterate date-ordered observations
ts.series.forEach(p => console.log(p.date, p.yield));
});
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=TR&maturity=10Y&start=2025-10-25&end=2026-10-25';
$ts = json_decode(file_get_contents($url, false, $ctx), true);
// $ts['series'] is an array of [ 'date' => Y-m-d, 'yield' => percent ]
?>
JSON response example
Each series element contains the business-date and yield in percent. You can compute daily changes or rolling vol directly from this vector.
Spreads: Turkey versus a benchmark
To monitor risk premium or relative value, compute the spread between Turkey and a benchmark country at a given maturity. The spread is returned in basis points, alongside both underlying yields in percent.
Endpoint
GET /api/v1/spread
- Required: country (TR), benchmark (e.g., US)
- Optional: maturity (defaults to 10Y)
cURL
Python (requests)
import requests
resp = requests.get(
'https://bonds-api.com/api/v1/spread',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TR', 'benchmark': 'US', 'maturity': '10Y'}
)
sp = resp.json()
# sp['spread_bps'] is integer/float basis points
# sp['country_yield'], sp['benchmark_yield'] are percents
JavaScript (fetch)
const s = new URL('https://bonds-api.com/api/v1/spread');
s.searchParams.set('country', 'TR');
s.searchParams.set('benchmark', 'US');
s.searchParams.set('maturity', '10Y');
fetch(s, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(sp => {
console.log(sp.spread_bps, sp.country_yield, sp.benchmark_yield);
});
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/spread?country=TR&benchmark=US&maturity=10Y';
$sp = json_decode(file_get_contents($url, false, $ctx), true);
// $sp['spread_bps'] in basis points; yields in percent
?>
JSON response example
Interpretation: A positive spread_bps means Turkey’s yield is higher than the benchmark by that many basis points. Convert to percent if needed by dividing by 100.
Full Turkey yield curve
To price fixed-income portfolios or run curve trades, fetch the entire Turkey curve for a single date. You can also request a historical date to compare curves across time.
Endpoint
GET /api/v1/curve
- Required: country (TR)
- Optional: date (Y-m-d); if omitted, returns the latest available
cURL
Python (requests)
import requests
resp = requests.get(
'https://bonds-api.com/api/v1/curve',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TR'}
)
curve = resp.json()
# curve['curve'] is a dict of maturity => yield (percent)
# curve['inverted'] is boolean
JavaScript (fetch)
fetch('https://bonds-api.com/api/v1/curve?country=TR', {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
}).then(r => r.json())
.then(curve => {
const tenY = curve.curve['10Y']; // percent
const inverted = curve.inverted; // boolean
console.log(tenY, inverted);
});
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/curve?country=TR';
$c = json_decode(file_get_contents($url, false, $ctx), true);
// $c['curve'] associative array of maturity => percent
// $c['inverted'] boolean indicator
?>
JSON response example
Interpretation: Each maturity maps to a percent yield at the given date. The inverted flag is a quick diagnostic of a downward-sloping segment. Use these points to interpolate a par or zero curve in your pricing stack.
Turkey curve maturities at a glance
| Maturity | Use in analytics |
|---|---|
| 1M, 3M, 6M | Short-end liquidity and policy rate expectations |
| 1Y, 2Y | Near-term funding and macro expectations |
| 5Y, 10Y | Benchmark curve anchors, risk premium |
| 30Y | Long-duration hedging and ALM |
Intraday snapshots for Turkey
When you need within-day monitoring (e.g., trading apps and alerting systems), request intraday snapshots for a date and maturity. Timestamps are in UTC.
Endpoint
GET /api/v1/intraday
- Required: country (TR), maturity (e.g., 10Y), date (Y-m-d)
cURL
Python (requests)
import requests
resp = requests.get(
'https://bonds-api.com/api/v1/intraday',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TR', 'maturity': '10Y', 'date': '2026-10-25'}
)
intra = resp.json()
# intra['snapshots'] elements: { 'yield': percent, 'fetched_at': ISO8601 UTC, 'source': 'market' }
JavaScript (fetch)
const intr = new URL('https://bonds-api.com/api/v1/intraday');
intr.searchParams.set('country', 'TR');
intr.searchParams.set('maturity', '10Y');
intr.searchParams.set('date', '2026-10-25');
fetch(intr, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(s => {
s.snapshots.forEach(pt => {
console.log(pt.fetched_at, pt.yield);
});
});
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/intraday?country=TR&maturity=10Y&date=2026-10-25';
$intra = json_decode(file_get_contents($url, false, $ctx), true);
// Use $intra['snapshots'] with UTC 'fetched_at' for charting
?>
JSON response example
Interpretation: Use fetched_at to align intraday points. These are practical for threshold alerts and for calculating in-session volatility.
Fluctuation summary (change, min, max) for Turkey
To quickly report the change over a period and bounds for Turkey yields, use the fluctuation endpoint. It returns the start and end levels, absolute change in percent, and period min and max.
Endpoint
GET /api/v1/fluctuation
- Required: countries (ISO2 comma-separated), maturity, start (Y-m-d), end (Y-m-d)
cURL
Python (requests)
import requests
params = {
'countries': 'TR', 'maturity': '10Y', 'start': '2025-10-25', 'end': '2026-10-25'
}
resp = requests.get('https://bonds-api.com/api/v1/fluctuation', headers={'X-API-Key': 'YOUR_API_KEY'}, params=params)
fl = resp.json()
# fl['data']['TR'] contains start_yield, end_yield, change, min, max (all percents)
JavaScript (fetch)
const f = new URL('https://bonds-api.com/api/v1/fluctuation');
f.searchParams.set('countries', 'TR');
f.searchParams.set('maturity', '10Y');
f.searchParams.set('start', '2025-10-25');
f.searchParams.set('end', '2026-10-25');
fetch(f, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(fl => {
const s = fl.data.TR;
console.log(s.start_yield, s.end_yield, s.change, s.min, s.max);
});
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=TR&maturity=10Y&start=2025-10-25&end=2026-10-25';
$fl = json_decode(file_get_contents($url, false, $ctx), true);
// Access $fl['data']['TR']['change'] in percent (end - start)
?>
JSON response example
Interpretation: All values are percents. change = end_yield − start_yield. Use this for KPI summaries and period-over-period reporting.
Operational considerations: business days, holidays, updates, and caching
Business day sampling: Daily endpoints return values for trading days. Weekends and Turkish market holidays may be absent. When requesting a historical date that is not a trading day, you may receive a 404 (no data) response; adjust to the nearest prior business day.
Update frequency: Daily "official" values are typically available after the close or official publication. Intraday snapshots use UTC timestamps and can arrive multiple times during the trading session. For consistent dashboards, cache daily endpoints for a full day and set shorter TTLs (e.g., a few minutes) for intraday requests.
Error handling: Respect 401 (X-API-Key missing/invalid), 403 (quota exceeded), 404 (no data for the parameters), 422 (invalid parameters), 429 (rate limit), and 500 (server error). Implement idempotent retries with backoff on 429/500 and fast-fail on validation errors (422) until corrected.
Scaling: If you need the full curve plus selected points, prefer one /curve call rather than multiple /latest maturities to reduce request volume. Where multiple symbols are supported (e.g., /latest with a maturities list), batch them to minimize round trips.
Sovereign bond fundamentals (brief)
Turkey’s sovereign bonds are obligations of the Republic of Turkey. Their yields reflect policy expectations, inflation, growth, and risk premiums. Short maturities anchor to policy and liquidity, while the 5–10–30Y segments embed term premium and macro expectations. The yield curve shape (e.g., steepening, flattening, or inversion) is a key signal for growth and inflation scenarios, hedging, and duration positioning.
All data in this article is accessed via GET requests to the Bonds API under the base URL https://bonds-api.com/api/v1/. For broader documentation and tooling, visit bonds-api.com and the MCP.
Common error responses (shape and handling)
All errors share the shape success=false with an error message string. Anticipate these codes in your client:
- 401: Missing or invalid X-API-Key — fix credentials or environment variables.
- 403: Account quota exceeded — reduce calls or wait for quota reset.
- 404: No data for requested country/maturity/date — adjust to business day or supported maturities.
- 422: Invalid parameter (format or unknown code) — correct ISO codes or date formats (Y-m-d).
- 429: Rate limit exceeded — backoff and retry later.
- 500: Server error — retry with exponential backoff; add circuit breaker logic.
Putting it together: building a Turkey curve and spreads dashboard
For a minimal dashboard:
- On load, call /api/v1/curve?country=TR to populate the full curve snapshot. Cache for the trading day.
- For headline tiles, call /api/v1/latest with countries=TR and maturities=2Y,5Y,10Y to show key benchmarks.
- For historical charts, call /api/v1/timeseries across the desired window (e.g., trailing 1 year for 10Y).
- Add a spread tile by calling /api/v1/spread?country=TR&benchmark=US&maturity=10Y; display spread_bps.
- If you support intraday, poll /api/v1/intraday during market hours at a reasonable interval and throttle updates.
This setup balances comprehensive coverage with request efficiency. Where possible, batch maturities in /latest and prefer /curve for curve-wide data. Cache responses keyed by country, maturity, and date to avoid duplicative calls.
FAQ
Q: Are yields returned in percent or basis points?
A: Yields are returned in percent across endpoints. Only spread_bps in /spread is in basis points. Convert bps to percent by dividing by 100.
Q: How do I handle non-trading days for historical requests?
A: If you receive a 404 for a given date, adjust to the prior business day in Turkey and retry. Time series omit weekends and local holidays by design.
Q: Can I build the curve without multiple calls?
A: Yes. Use /api/v1/curve for the entire Turkey curve on one date. If you only need a few tenors, /api/v1/latest supports a maturities list to fetch them in a single call.
Q: What timezone are intraday timestamps in?
A: Intraday fetched_at values are ISO 8601 timestamps in UTC. The meta.timezone field confirms this.
Q: How should I cache results?
A: Cache daily endpoints (latest, historical, curve, fluctuation, spread) for the trading day, and cache intraday snapshots with a short TTL aligned to your UI refresh interval. Include error and backoff handling for 429/500 responses.
Get production-grade access to Turkey sovereign yields today. Use your API key with the X-API-Key header and start integrating the endpoints shown above. Register to obtain your key, or explore tools via the MCP.