Japan Bond Curve API

Building a reliable Japan government bond yield curve inside your own tools usually means stitching together multiple maturities, handling business days and holidays, and keeping the data fresh. By the end of this guide, you will query live and historical Japan (JP) sovereign yields from Bonds API, compute spreads, fetch intraday snapshots, and assemble a full yield curve for analytics and dashboards.

What you get from Bonds API and how yields are expressed

Bonds API serves sovereign bond yields over simple GET endpoints at https://bonds-api.com/api/v1/. All requests are authenticated with an X-API-Key header and return JSON. Yields are expressed in percent (for example, 4.52 means 4.52%). Spreads are returned in basis points (bps), where 1 basis point = 0.01%. All dates are day-level strings formatted as YYYY-MM-DD. Intraday timestamps are ISO-8601 UTC strings.

Coverage includes 60+ countries and standard maturities from 1M bills to long bonds such as 30Y and 50Y where available. For Japan, use ISO2 code JP. Visit bonds-api.com to learn more about coverage and endpoints, and see the MCP for operational status.

To start integrating, you will need an API key. Register to get one and follow along with the examples below.

Maturities, business days, updates, and caching

Japan’s sovereign curve typically includes money-market tenors like 1M, 3M, and 6M, short notes like 1Y and 2Y, intermediate tenors like 5Y and 10Y, and long bonds such as 30Y. Availability may vary by date. When you omit maturities from certain endpoints, the API returns whatever is available for that country on the requested day.

Market holidays and weekends mean there may be no new official close for those dates; latest endpoints return the most recent available trading day. For intraday snapshots, timestamps are in UTC to avoid timezone ambiguity.

For caching, treat daily endpoints (latest, historical, curve) as day-level resources: cache until the next trading session or refresh after market close. For intraday, choose a refresh cadence aligned with your UX (for example, every 5–15 minutes), and respect 429 rate-limit responses by backing off. Error codes are included below.

Endpoint: Latest Japan yields (GET /latest)

Use this to fetch the most recent available yields for Japan, optionally filtered by specific maturities.

cURL

curl -s "https://bonds-api.com/api/v1/latest?countries=US&maturities=10Y&api_key=YOUR_API_KEY"

official JSON response

{
"success": true,
"date": "2026-09-30",
"rates": {
"US_10Y": 5.278
},
"dates": {
"US_10Y": "2026-09-30"
},
"currencies": {
"US_10Y": "USD"
},
"meta": {
"request_id": "cda2528a-3972-4065-a163-480a45185d3c",
"timestamp": "2026-09-30T17:58:34+00:00"
}
}

Fields:

• yield: percentage (e.g., 4.52 means 4.52%).
• date: YYYY-MM-DD, the trading day for that official close.
• source: data provenance, e.g., “official”.

Python (requests)

import requests

resp = requests.get(
'https://bonds-api.com/api/v1/latest',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'countries': 'JP', 'maturities': '2Y,10Y'}
)
resp.raise_for_status()
data = resp.json()
jp_2y = data['data']['JP']['2Y']['yield']
jp_10y = data['data']['JP']['10Y']['yield']
as_of = data['data']['JP']['10Y']['date']
print('JP 2Y:', jp_2y, 'JP 10Y:', jp_10y, 'as of', as_of)

JavaScript (fetch)

const url = new URL('https://bonds-api.com/api/v1/latest');
url.searchParams.set('countries', 'JP');
url.searchParams.set('maturities', '2Y,10Y');

fetch(url, { headers: { 'X-API-Key': 'YOUR_API_KEY' } })
.then(res => res.json())
.then(json => {
const jp = json.data.JP;
console.log('JP 2Y', jp['2Y'].yield, 'JP 10Y', jp['10Y'].yield, 'as of', jp['10Y'].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=JP&maturities=2Y,10Y';
$json = file_get_contents($url, false, $context);
$data = json_decode($json, true);
$jp10y = $data['data']['JP']['10Y']['yield'];
echo "JP 10Y: {$jp10y}\n";

Endpoint: Historical yield on a given date (GET /historical)

Fetch Japan’s yield for an exact maturity on an exact calendar date (business day resolution). If the date is a holiday/weekend, you will receive a 404 if there is no data for that day.

cURL

official JSON response

Fields:

• yield: percentage on the specified date.
• date: requested YYYY-MM-DD.

Python

import requests

params = {'country': 'JP', '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)
if r.status_code == 404:
print('No data for requested combination')
else:
r.raise_for_status()
out = r.json()
print(out['country'], out['maturity'], out['date'], out['yield'])

JavaScript

const params = new URLSearchParams({ country: 'JP', 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(d => console.log(d.country, d.maturity, d.date, d.yield));

PHP

<?php
$q = http_build_query(['country' => 'JP', 'maturity' => '10Y', 'date' => '2025-06-15']);
$opts = ['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]];
$ctx = stream_context_create($opts);
$body = file_get_contents('https://bonds-api.com/api/v1/historical?' . $q, false, $ctx);
echo $body;

Endpoint: Time series between two dates (GET /timeseries)

Pull a continuous daily series for one maturity across a start–end range. Missing days (weekends/holidays) are skipped.

cURL

official JSON response

Fields:

• series: array of objects with date (YYYY-MM-DD) and yield (percent).

Python

import requests

params = {'country': 'JP', 'maturity': '10Y', 'start': '2025-09-30', 'end': '2026-09-30'}
r = requests.get('https://bonds-api.com/api/v1/timeseries',
headers={'X-API-Key': 'YOUR_API_KEY'},
params=params)
r.raise_for_status()
series = r.json()['series']
# Example: compute simple average
avg = sum(pt['yield'] for pt in series) / len(series) if series else None
print('Obs:', len(series), 'Avg yield:', avg)

JavaScript

const p = new URLSearchParams({ country: 'JP', maturity: '10Y', start: '2025-09-30', end: '2026-09-30' });
fetch('https://bonds-api.com/api/v1/timeseries?' + p.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(json => {
const s = json.series;
const avg = s.reduce((a, b) => a + b.yield, 0) / (s.length || 1);
console.log('Count', s.length, 'Avg', avg);
});

PHP

<?php
$params = http_build_query(['country' => 'JP', 'maturity' => '10Y', 'start' => '2025-09-30', 'end' => '2026-09-30']);
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$res = file_get_contents('https://bonds-api.com/api/v1/timeseries?' . $params, false, $ctx);
$data = json_decode($res, true);
echo 'Points: ' . count($data['series']) . PHP_EOL;

Endpoint: Spread vs benchmark (GET /spread)

Compute the spread between Japan and a benchmark sovereign at a given maturity. Spread is returned in basis points (bps). For instance, a 215 bps spread means Japan is 2.15% higher than the benchmark at that maturity.

cURL

official JSON response

Fields:

• spread_bps: integer basis points (e.g., 215 = 2.15%).
• country_yield, benchmark_yield: percentage yields.

Python

import requests

r = requests.get('https://bonds-api.com/api/v1/spread',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'JP', 'benchmark': 'US', 'maturity': '10Y'})
r.raise_for_status()
s = r.json()
print('JP- US 10Y spread (bps):', s['spread_bps'])

JavaScript

const q = new URLSearchParams({ country: 'JP', benchmark: 'US', maturity: '10Y' });
fetch('https://bonds-api.com/api/v1/spread?' + q.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(s => console.log('Spread bps:', s.spread_bps));

PHP

<?php
$q = http_build_query(['country' => 'JP', 'benchmark' => 'US', 'maturity' => '10Y']);
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
$out = file_get_contents('https://bonds-api.com/api/v1/spread?' . $q, false, $ctx);
echo $out;

Endpoint: Full Japan yield curve (GET /curve)

Retrieve Japan’s entire available curve for a recent day (or a specific date). This is the simplest way to build and render a term structure for pricing, scenario analysis, and duration/convexity profiling.

cURL

official JSON response

Fields:

• curve: mapping maturity -> yield percent.
• inverted: boolean indicating short rates above long rates in aggregate.
• date: the curve’s trading day (YYYY-MM-DD).

Building a yield curve in code

The endpoint already returns a complete curve. In client code, sort maturities by tenor to render plots or to feed bootstrapping routines.

Python

import requests

r = requests.get('https://bonds-api.com/api/v1/curve',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'JP'})
r.raise_for_status()
curve = r.json()['curve']
tenors = sorted(curve.keys(), key=lambda k: ['M','Y'].index(k[-1]) or 0)
points = [(t, curve[t]) for t in tenors]
print(points)

JavaScript

fetch('https://bonds-api.com/api/v1/curve?country=JP', {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(c => {
const curve = c.curve;
const order = (t) => {
const unit = t.endsWith('M') ? 'M' : 'Y';
const n = parseInt(t);
return unit === 'M' ? n : 12 * n;
};
const sorted = Object.keys(curve).sort((a,b) => order(a) - order(b));
console.log(sorted.map(t => [t, curve[t]]));
});

PHP

<?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=JP', false, $ctx);
$data = json_decode($json, true);
foreach ($data['curve'] as $tenor => $y) {
echo $tenor . ': ' . $y . PHP_EOL;
}

Endpoint: Intraday snapshots (GET /intraday)

When you need to show Japan yields moving inside the day—for example, in a trading dashboard—use intraday snapshots. All timestamps are UTC in ISO-8601 format (fetched_at), so convert to local timezones on the client.

cURL

official JSON response

Fields:

• snapshots: array where yield is percent; fetched_at is UTC timestamp.
• count: number of snapshots for the day.

Python

import requests
from datetime import datetime, timezone

p = {'country': 'JP', 'maturity': '10Y', 'date': '2026-09-30'}
r = requests.get('https://bonds-api.com/api/v1/intraday', headers={'X-API-Key': 'YOUR_API_KEY'}, params=p)
r.raise_for_status()
data = r.json()
for s in data['snapshots']:
ts = datetime.fromisoformat(s['fetched_at'].replace('Z', '+00:00')).astimezone(timezone.utc)
print(ts.isoformat(), s['yield'])

JavaScript

const params = new URLSearchParams({ country: 'JP', maturity: '10Y', date: '2026-09-30' });
fetch('https://bonds-api.com/api/v1/intraday?' + params.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(d => {
d.snapshots.forEach(s => console.log(new Date(s.fetched_at).toISOString(), s.yield));
});

PHP

<?php
$params = http_build_query(['country' => 'JP', 'maturity' => '10Y', 'date' => '2026-09-30']);
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/intraday?' . $params, false, $ctx);

Endpoint: Fluctuation over a period (GET /fluctuation)

Obtain the start, end, change, and min/max yields for Japan across a period at a given maturity—handy for sparklines, summaries, and risk dashboards.

cURL

official JSON response

Fields:

• start_yield, end_yield: percentages at the window endpoints.
• change: absolute change in percent (end - start).
• min, max: extremes within [start, end].

Python

import requests

params = {'countries': 'JP', 'maturity': '10Y', 'start': '2025-09-30', 'end': '2026-09-30'}
r = requests.get('https://bonds-api.com/api/v1/fluctuation',
headers={'X-API-Key': 'YOUR_API_KEY'}, params=params)
r.raise_for_status()
stats = r.json()['data']['JP']
print('Δ (pp):', stats['change'], 'min:', stats['min'], 'max:', stats['max'])

JavaScript

const p = new URLSearchParams({ countries: 'JP', maturity: '10Y', start: '2025-09-30', end: '2026-09-30' });
fetch('https://bonds-api.com/api/v1/fluctuation?' + p.toString(), {
headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
.then(r => r.json())
.then(j => console.log(j.data.JP));

PHP

<?php
$params = http_build_query(['countries' => 'JP', 'maturity' => '10Y',
'start' => '2025-09-30', 'end' => '2026-09-30']);
$ctx = stream_context_create(['http' => ['method' => 'GET', 'header' => "X-API-Key: YOUR_API_KEY\r\n"]]);
echo file_get_contents('https://bonds-api.com/api/v1/fluctuation?' . $params, false, $ctx);

Practical integration notes for Japan fixed income

• Maturities: when you need a multi-point yield curve and don’t require every tenor, call /latest with countries=JP and maturities=1Y,2Y,5Y,10Y,30Y for a compact payload. If you need the full term structure, prefer /curve.
• Business days: Japan market holidays vary; some are not co-incident with US/EU calendars. If you receive a 404 on /historical for a given date, pick the prior business day or switch to /latest.
• Update frequency: official daily closes stabilize after market close; intraday snapshots are meant for mid-session display. Cache /curve and /latest per trading day; refresh /intraday to match your UX needs.
• Caching headers: responses are JSON without forced caching semantics; implement client-side caching and conditional refresh based on your latency and quota requirements.
• Spreads: for cross-market analyses (e.g., JP vs US), use /spread, which avoids you needing to fetch two series and compute manually. Remember spread_bps is basis points.

If you need to automate these flows at scale, bookmark bonds-api.com and keep the Bonds API MCP handy for checking service components.

Error handling and status codes

Common error shapes are consistent across endpoints: success=false with an error message. HTTP status codes include:

• 401: Missing or invalid X-API-Key
• 403: Account quota exceeded
• 404: No data for requested country/maturity/date
• 422: Invalid parameter (date format must be YYYY-MM-DD; unknown ISO2 code like a typo in “JP”)
• 429: Rate limit exceeded (back off and retry later)
• 500: Server error (implement retry with jitter)

Sovereign bond fundamentals (2-minute refresher)

A sovereign bond’s yield is the market’s rate of return to maturity, reflecting monetary policy, inflation expectations, and credit/liquidity premia. The term structure (yield curve) relates yield to maturity: upward sloping in typical expansions, flatter or inverted when policy is tight or recession risks rise.

For development and quant work, the curve can drive discount curves, risk metrics (DV01, duration/convexity), carry/roll analyses, and spread trades versus benchmarks. Japan’s curve is often a reference in Asia rates strategies and cross-market relative value with US Treasuries and German Bunds.

Putting it together: assemble and display a Japan yield curve

Two common build paths:

• Quick rendering: call /api/v1/curve?country=JP, sort keys by tenor, and plot.
• Custom selection: call /api/v1/latest with countries=JP and maturities=1Y,2Y,5Y,10Y,30Y to render a compact, stable set across sessions.

If you need a prior business day’s curve (for example, T-1 close), add date=YYYY-MM-DD to /curve. For an animated intraday panel, pair /intraday (for 10Y) with /spread to show real-time Japan–US 10Y moves in bps.

Reference table: core Japan curve points

Maturity	Use case	Endpoint parameters
1M, 3M, 6M	Money market tone, short-end policy signal	latest: maturities=1M,3M,6M; curve: full map
1Y, 2Y	Front-end rates, policy path	latest/historical/timeseries maturity=1Y or 2Y
5Y, 10Y	Benchmark belly, risk proxies	spread with benchmark=US, maturity=10Y
30Y	Long-end, liability hedging	curve or latest maturity=30Y

Endpoint quick-start bundle you can copy

Below is a single cURL you can run right now to confirm access, followed by a Python snippet to parse and display a few Japan points.

cURL (copy-paste)

Realistic JSON (fields documented above)

How to read it: yields are percents; date is the trading day; inverted=false means the curve is not broadly inverted.

Python: fetch curve and compute simple slopes

import requests

r = requests.get('https://bonds-api.com/api/v1/curve',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'country': 'JP'})
r.raise_for_status()
c = r.json()['curve']
slope_2s10s = c['10Y'] - c['2Y']
slope_10s30s = c['30Y'] - c['10Y']
print('2s10s:', slope_2s10s, '10s30s:', slope_10s30s)

Use cases: dashboards, risk tools, and research

• Financial dashboards: show JP 10Y and intraday ticks beside a sparkline of the last 30 days from /timeseries.
• Portfolio risk: compute DV01 buckets by mapping holdings to nearest on-the-run tenors from /curve and stress with +/- 25 bps shifts.
• Economic research: pull monthly endpoints at month-end dates via /historical for long-run regressions with inflation and FX data.
• Cross-market RV: monitor /spread JP vs US at 10Y to track relative value and policy divergence in real time.

Frequently asked questions

How often are Japan yields updated?
Daily endpoints (latest, historical, curve) reflect the most recent available trading day. Intraday snapshots are captured multiple times per day and timestamped in UTC.

Which units should I expect?
Yields are percentages; spreads are basis points (bps). Convert bps to percent by dividing by 100.

What happens on weekends and Japan market holidays?
There may be no data for those dates; /historical will return 404 if the requested date has no observation. Use /latest or move to the previous business day.

Can I request multiple maturities at once?
Yes. Use /latest with maturities=2Y,5Y,10Y or call /curve for all available tenors on a day.

How should I handle rate limits?
If you receive 429, implement exponential backoff and consider caching daily endpoints per session. Check the MCP if you suspect a transient issue.

Get your key and start shipping your Japan fixed-income integration in minutes: Register. You can also explore more at bonds-api.com and monitor components via the Bonds API MCP.

Register for Bonds API

Bonds API MCP

Get started with Bonds API