You need precise, machine-readable Taiwan 10-year government bond yields for analytics, dashboards, or automated risk models. By the end of this guide, you will be able to pull the Taiwan 10Y from Bonds API in real time and historically, compute spreads to benchmarks, assemble full yield curves, handle intraday snapshots, and productionize requests with proper headers, date formats, and caching.
What you can fetch for Taiwan (TW) and how yields are represented
Bonds API provides sovereign bond yields as JSON over REST for 60+ countries, including Taiwan (ISO2: TW). You can request:
- Latest yields by country and maturity (e.g., 2Y, 10Y)
- Historical yields on a specific date
- Time series between two dates
- Spreads vs. a benchmark country (e.g., US)
- Full yield curves across multiple maturities
- Intraday snapshots for a given date
- Fluctuation statistics (change, min, max) over a period
Units and formats across endpoints:
- Yields are expressed as percentage values (e.g., 4.52 means 4.52%).
- Spreads are returned in basis points (bps), where 1 basis point = 0.01%.
- Dates are ISO 8601 in Y-m-d format; timestamps use UTC and ISO datetime with timezone offset or Z suffix.
Base URL for all endpoints: https://bonds-api.com/api/v1/ — only GET requests are supported. Authentication is via the X-API-Key header. You can Register to obtain an API key and begin calling the endpoints shown below. Explore more tools at the MCP. Learn more about product coverage at bonds-api.com.
Production details: business days, holidays, updates, and caching
Government bond yields update on market business days and may be unavailable on local holidays and weekends. For Taiwan, expect new official daily values on Taiwan trading days. Intraday snapshots reflect market quotes during the specified date in UTC time. If you query a non-trading date, historical and timeseries endpoints return the values available for the exact dates requested (errors can occur if no data exists for that date).
Cache guidance:
- Latest endpoint: cache by country and maturity for minutes if your application tolerates slight staleness; align with your refresh cycle.
- Historical and timeseries: cache for longer (hours to days) because data for past dates does not change once official values are published.
- Intraday: cache for shorter durations if you are building near-real-time dashboards (e.g., 1–5 minutes).
When building a yield curve, request the country curve endpoint once per update cycle rather than fanning out multiple latest calls per maturity. Always verify the date field in responses to ensure you’re plotting values for the intended day.
Official sample note (US 10Y)
The following “official sample” is provided for consistency checks. It uses the US 10Y and a query parameter for the API key. Copy these blocks verbatim if you need to validate parsing. All other examples in this article for Taiwan use the standard X-API-Key header.
curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"{
"success": true,
"date": "2026-10-09",
"rates": {
"US_10Y": 5.24
},
"dates": {
"US_10Y": "2026-10-09"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "2107a28e-f71a-4d8f-9620-d81dbc0b206d",
"timestamp": "2026-10-10T01:04:04+00:00"
}
}Endpoint: Latest yields for Taiwan
Use this to fetch the current Taiwan 10Y or multiple maturities in one call.
cURL
JSON response
How to read this:
- yield: percentage (4.52 means 4.52%).
- date: official market date in Y-m-d.
- source: provenance label such as "official."
Python (requests)
import requests
headers = {'X-API-Key': 'YOUR_API_KEY'}
params = {'countries': 'TW', 'maturities': '2Y,10Y'}
r = requests.get('https://bonds-api.com/api/v1/latest', headers=headers, params=params)
r.raise_for_status()
data = r.json()
tw_10y = data['data']['TW']['10Y']['yield']
tw_10y_date = data['data']['TW']['10Y']['date']
print('TW 10Y:', tw_10y, 'on', tw_10y_date)JavaScript (fetch)
const url = new URL('https://bonds-api.com/api/v1/latest');
url.searchParams.set('countries', 'TW');
url.searchParams.set('maturities', '2Y,10Y');
fetch(url.toString(), { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(res => res.json())
.then(json => {
const y = json.data.TW['10Y'].yield;
const d = json.data.TW['10Y'].date;
console.log('TW 10Y', y, 'on', d);
});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=TW&maturities=2Y,10Y';
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$tw10 = $data['data']['TW']['10Y']['yield'];
echo "TW 10Y: {$tw10}\n";Endpoint: Historical yield (specific date)
Request Taiwan 10Y for an exact date. If the date is a non-trading day and no official value exists, you will receive a 404.
cURL
JSON response
Fields:
- yield: percentage on the specified date.
- country/maturity/date: echo parameters.
- source: data provenance.
Python (requests)
import requests
r = requests.get(
'https://bonds-api.com/api/v1/historical',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TW', 'maturity': '10Y', 'date': '2025-06-15'}
)
r.raise_for_status()
print(r.json())JavaScript (fetch)
const u = new URL('https://bonds-api.com/api/v1/historical');
u.searchParams.set('country', 'TW');
u.searchParams.set('maturity', '10Y');
u.searchParams.set('date', '2025-06-15');
fetch(u, { headers: { 'X-API-Key': 'YOUR_API_KEY' }})
.then(r => r.json())
.then(j => console.log(j));PHP (file_get_contents)
<?php
$u = 'https://bonds-api.com/api/v1/historical?country=TW&maturity=10Y&date=2025-06-15';
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents($u, false, $ctx);Endpoint: Time series (range of dates)
Build a Taiwan 10Y series for charting or factor models. Start and end are inclusive.
cURL
JSON response
Fields:
- series: array of daily observations; yields in percent; dates in Y-m-d.
Python (requests)
import requests
resp = requests.get(
'https://bonds-api.com/api/v1/timeseries',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TW', 'maturity': '10Y', 'start': '2025-10-10', 'end': '2026-10-10'}
)
resp.raise_for_status()
series = resp.json()['series']
print('Count:', len(series))JavaScript (fetch)
const ts = new URL('https://bonds-api.com/api/v1/timeseries');
ts.searchParams.set('country', 'TW');
ts.searchParams.set('maturity', '10Y');
ts.searchParams.set('start', '2025-10-10');
ts.searchParams.set('end', '2026-10-10');
fetch(ts, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(j => console.log(j.series));PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$ts = 'https://bonds-api.com/api/v1/timeseries?country=TW&maturity=10Y&start=2025-10-10&end=2026-10-10';
$data = json_decode(file_get_contents($ts, false, $ctx), true);
echo "First point: " . $data['series'][0]['date'] . " " . $data['series'][0]['yield'] . "%\n";Endpoint: Spread vs. benchmark
Compare Taiwan 10Y to a benchmark (e.g., US Treasuries). The spread is returned in basis points (bps).
cURL
JSON response
How to read this:
- spread_bps: difference in basis points (e.g., 215 bps = 2.15%).
- country_yield and benchmark_yield: both in percent.
Python (requests)
import requests
r = requests.get(
'https://bonds-api.com/api/v1/spread',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TW', 'benchmark': 'US', 'maturity': '10Y'}
)
r.raise_for_status()
s = r.json()
print('Spread (bps):', s['spread_bps'])JavaScript (fetch)
const sp = new URL('https://bonds-api.com/api/v1/spread');
sp.searchParams.set('country', 'TW');
sp.searchParams.set('benchmark', 'US');
sp.searchParams.set('maturity', '10Y');
fetch(sp, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(j => console.log('TW vs US 10Y spread (bps):', j.spread_bps));PHP (file_get_contents)
<?php
$u = 'https://bonds-api.com/api/v1/spread?country=TW&benchmark=US&maturity=10Y';
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents($u, false, $ctx);Endpoint: Full yield curve (Taiwan)
Fetch a cross-section of maturities for Taiwan to construct a yield curve. This is the most efficient way to power a curve chart or fit a spline for risk models.
cURL
JSON response
Fields:
- curve: keys are maturities; values are yields in percent.
- date: official curve date.
- inverted: true if shorter maturities exceed longer ones (simple inversion flag).
Typical curve points returned
| Maturity | Example field in curve |
|---|---|
| 1M | curve["1M"] |
| 3M | curve["3M"] |
| 6M | curve["6M"] |
| 1Y | curve["1Y"] |
| 2Y | curve["2Y"] |
| 5Y | curve["5Y"] |
| 10Y | curve["10Y"] |
| 30Y | curve["30Y"] |
Python (requests)
import requests
r = requests.get('https://bonds-api.com/api/v1/curve',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TW'})
r.raise_for_status()
curve = r.json()['curve']
ten = curve['10Y']
print('Curve 10Y:', ten)JavaScript (fetch)
const cu = new URL('https://bonds-api.com/api/v1/curve');
cu.searchParams.set('country', 'TW');
fetch(cu, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(j => {
const maturities = Object.keys(j.curve);
const points = maturities.map(m => [m, j.curve[m]]);
console.log(points);
});PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$u = 'https://bonds-api.com/api/v1/curve?country=TW';
$data = json_decode(file_get_contents($u, false, $ctx), true);
echo "Inverted: " . ($data['inverted'] ? 'true' : 'false') . "\n";Endpoint: Intraday snapshots (UTC)
Retrieve multiple intraday snapshots for TW 10Y on a given date. Timestamps are in UTC via fetched_at.
cURL
JSON response
Fields:
- snapshots: array of intraday quotes (yield in percent).
- fetched_at: UTC timestamp.
- count: number of snapshots in the response.
Python (requests)
import requests
r = requests.get(
'https://bonds-api.com/api/v1/intraday',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'TW', 'maturity': '10Y', 'date': '2026-10-10'}
)
r.raise_for_status()
for s in r.json()['snapshots']:
print(s['fetched_at'], s['yield'])JavaScript (fetch)
const id = new URL('https://bonds-api.com/api/v1/intraday');
id.searchParams.set('country', 'TW');
id.searchParams.set('maturity', '10Y');
id.searchParams.set('date', '2026-10-10');
fetch(id, { 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 (file_get_contents)
<?php
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$u = 'https://bonds-api.com/api/v1/intraday?country=TW&maturity=10Y&date=2026-10-10';
$data = json_decode(file_get_contents($u, false, $ctx), true);
foreach ($data['snapshots'] as $s) {
echo $s['fetched_at'] . " " . $s['yield'] . "\n";
}Endpoint: Fluctuation (change, min, max)
Summarize the Taiwan 10Y over a period for dashboards and alerts.
cURL
JSON response
Fields:
- start_yield, end_yield, change: all in percentage points.
- min, max: period extremes, in percent.
Python (requests)
import requests
r = requests.get(
'https://bonds-api.com/api/v1/fluctuation',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'countries': 'TW', 'maturity': '10Y', 'start': '2025-10-10', 'end': '2026-10-10'}
)
r.raise_for_status()
f = r.json()['data']['TW']
print('Change (pp):', f['change'], 'Min:', f['min'], 'Max:', f['max'])JavaScript (fetch)
const fl = new URL('https://bonds-api.com/api/v1/fluctuation');
fl.searchParams.set('countries', 'TW');
fl.searchParams.set('maturity', '10Y');
fl.searchParams.set('start', '2025-10-10');
fl.searchParams.set('end', '2026-10-10');
fetch(fl, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(r => r.json())
.then(j => console.log(j.data.TW));PHP (file_get_contents)
<?php
$ctx = stream_context_create(['http' => ['header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$u = 'https://bonds-api.com/api/v1/fluctuation?countries=TW&maturity=10Y&start=2025-10-10&end=2026-10-10';
echo file_get_contents($u, false, $ctx);How to assemble a Taiwan yield curve and compute spreads
To generate a Taiwan curve for a given day, prefer a single call to /api/v1/curve. If you need a custom subset or additional maturities not included, you can combine /api/v1/latest with the maturities parameter. When constructing spreads:
- Use /api/v1/spread for direct country-vs-benchmark in basis points.
- Alternatively, request /api/v1/latest for both countries separately and subtract yields, then multiply by 100 to get bps.
Check the date field from the curve response to ensure you are plotting a consistent curve snapshot. For day-over-day curve changes, call /api/v1/curve for two consecutive business days and compare each maturity.
Error handling and operational guidance
Common errors returned (shape: success=false, error=message string):
- 401: Missing or invalid X-API-Key.
- 403: Account quota exceeded.
- 404: No data for requested country/maturity/date.
- 422: Invalid parameter (e.g., date format not Y-m-d, unknown ISO2).
- 429: Rate limit exceeded.
- 500: Server error.
In code, always raise for HTTP errors and branch on success in the JSON. When you aggregate multiple endpoints (e.g., curve + spread + intraday), stagger calls and cache by key parameters to reduce rate usage. For charts, surface the response date prominently so users understand the reference day.
Use cases that combine the endpoints
- Financial dashboards: Latest 10Y tile, curve chart (/curve), and benchmark spread (/spread).
- Risk models: Time series for factor regressions (/timeseries) and fluctuation statistics (/fluctuation) for VaR-like sensitivities.
- Research notebooks: Intraday study around macro events (/intraday) plus historical snapshots (/historical) for event windows.
- Alerting: Trigger when spread_bps crosses thresholds or when curve.inverted changes state.
Explore more capabilities and coverage at bonds-api.com. When you are ready to run these calls in production, Get started with Bonds API. To test interactively, visit the Bonds API MCP.
FAQ
How are yields scaled?
All yields are percentages. For example, 4.52 in the response is 4.52%.
What timezone should I assume for timestamps?
Dates are Y-m-d without timezone. Intraday timestamps use UTC (e.g., 2026-10-10T12:00:00Z). Use the meta.timezone field when provided.
How often do Taiwan yields update?
Official daily values update on Taiwan business days. Intraday snapshots provide multiple observations during the market day in UTC.
What parameters are required for authentication?
Send your key in the X-API-Key request header. All endpoints use GET and the base URL https://bonds-api.com/api/v1/.
What’s the recommended way to build a curve?
Use /api/v1/curve with country=TW. It is more efficient than fetching each maturity individually, and it ensures a consistent date across maturities.
Ship your Taiwan 10Y integration now: call the endpoints above with your API key, cache responsibly, and plot yields with correct units and dates. If you need an API key, Register and explore the interactive MCP to validate your requests.