You need reliable, machine-readable access to the New Zealand 10-year government bond yield (NZ 10Y) for research, dashboards, or trading models. By the end of this article you will be able to fetch the latest NZ 10Y yield, query historical and intraday data, compute spreads against benchmarks, and assemble a full New Zealand yield curve using the Bonds API over simple GET requests.
Scope and what you can build
This guide focuses on the New Zealand 10-year sovereign bond yield. You will learn how to query:
- Latest NZ 10Y yield for today’s business day
- Historical daily yields and longer time series
- Intraday snapshots for research and monitoring
- Spreads vs. a benchmark (e.g., US 10Y)
- The full New Zealand yield curve and how to use it
All endpoints come from bonds-api.com and return JSON, suitable for fixed-income analytics, portfolio risk tooling, and fintech integrations.
Data model: yields, dates, and time
Unless otherwise noted, yields are expressed as percentages (e.g., 4.52 means 4.52% per annum). Spread fields ending in “_bps” are basis points (1 bp = 0.01%). Daily dates use the YYYY-MM-DD format (ISO 8601 calendar date). Timestamps use ISO 8601 with timezone, typically in UTC (e.g., 2026-10-16T12:00:00Z). Currency fields indicate the sovereign’s local currency; for New Zealand, that is NZD.
Authentication and base URL
All endpoints are HTTP GET and served from:
https://bonds-api.com/api/v1/
Authentication is required for every request. Use your API key as an HTTP header:
- X-API-Key: YOUR_API_KEY
To obtain your key, visit Register or Register for Bonds API. You can also explore developer tools at the MCP and the plain link Bonds API MCP.
Official live sample for NZ 10Y
The following live sample shows a direct call for the New Zealand 10Y via the latest endpoint. Copy it to verify connectivity and data shape on your system.
curl -s "https://bonds-api.com/api/v1/latest?countries=NZ&maturities=10Y&api_key=YOUR_API_KEY"{
"success": true,
"date": "2026-10-16",
"rates": {
"NZ_10Y": 4.985
},
"dates": {
"NZ_10Y": "2026-10-16"
},
"currencies": {
"NZ_10Y": "NZD"
},
"meta": {
"request_id": "8905b02d-f697-4078-9673-3381511243b3",
"timestamp": "2026-10-16T00:04:45+00:00"
}
}How to read this:
- rates.NZ_10Y is the 10-year New Zealand sovereign yield in percent.
- date and dates.NZ_10Y provide the effective market date (YYYY-MM-DD).
- currencies.NZ_10Y shows NZD.
- meta.timestamp is an ISO 8601 timestamp, typically in UTC.
Current yields: /latest
Use this endpoint to fetch the latest available NZ yields. You can request multiple maturities to build a curve or a dashboard table.
cURL
JSON response
Interpretation:
- data.NZ.10Y.yield is the 10-year yield in percent.
- data.NZ.10Y.date is the market date (YYYY-MM-DD) for that quote.
- source indicates the 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": "NZ", "maturities": "2Y,10Y"}
)
resp.raise_for_status()
data = resp.json()
nz_10y = data["data"]["NZ"]["10Y"]["yield"]
nz_10y_date = data["data"]["NZ"]["10Y"]["date"]
print("NZ 10Y:", nz_10y, "on", nz_10y_date)JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.searchParams.set("countries", "NZ");
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 y = json.data.NZ["10Y"].yield;
const d = json.data.NZ["10Y"].date;
console.log(`NZ 10Y: ${y}% on ${d}`);
});PHP (file_get_contents)
<?php
$url = "https://bonds-api.com/api/v1/latest?countries=NZ&maturities=2Y,10Y";
$opts = ["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]];
$ctx = stream_context_create($opts);
$json = file_get_contents($url, false, $ctx);
$data = json_decode($json, true);
$nz10 = $data["data"]["NZ"]["10Y"]["yield"];
$dt = $data["data"]["NZ"]["10Y"]["date"];
echo "NZ 10Y: {$nz10}% on {$dt}\n";Historical daily yield: /historical
Retrieve the NZ 10Y yield for a specific calendar date. If the date is a non-trading day, the dataset returns an error; use the nearest business day or switch to /timeseries.
cURL
JSON response
Fields:
- yield: percent
- date: YYYY-MM-DD for the requested observation
- source: provenance label
Python
import requests
params = {"country": "NZ", "maturity": "10Y", "date": "2025-06-15"}
res = requests.get(
"https://bonds-api.com/api/v1/historical",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params
)
res.raise_for_status()
j = res.json()
print(j["maturity"], j["yield"], j["date"])JavaScript
const u = new URL("https://bonds-api.com/api/v1/historical");
u.searchParams.set("country", "NZ");
u.searchParams.set("maturity", "10Y");
u.searchParams.set("date", "2025-06-15");
fetch(u.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log(j.maturity, j.yield, j.date));PHP
<?php
$u = "https://bonds-api.com/api/v1/historical?country=NZ&maturity=10Y&date=2025-06-15";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$body = file_get_contents($u, false, $ctx);
$j = json_decode($body, true);
echo $j["maturity"] . " " . $j["yield"] . " " . $j["date"] . PHP_EOL;Time series: /timeseries
Fetch an NZ 10Y daily series between two dates inclusive. This is the basis for backtests, trend analysis, and volatility estimates. If the date range spans weekends or New Zealand market holidays, those days simply do not appear in the series.
cURL
JSON response
Interpretation:
- series is an array of daily observations with date in YYYY-MM-DD and yield in percent.
Python
import requests
q = {
"country": "NZ",
"maturity": "10Y",
"start": "2025-10-16",
"end": "2026-10-16"
}
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"]
print("Observations:", len(ts), "First:", ts[0])JavaScript
const tsUrl = new URL("https://bonds-api.com/api/v1/timeseries");
Object.entries({
country: "NZ",
maturity: "10Y",
start: "2025-10-16",
end: "2026-10-16"
}).forEach(([k, v]) => tsUrl.searchParams.set(k, v));
fetch(tsUrl.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log("Count:", j.series.length));PHP
<?php
$u = "https://bonds-api.com/api/v1/timeseries?country=NZ&maturity=10Y&start=2025-10-16&end=2026-10-16";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$raw = file_get_contents($u, false, $ctx);
$j = json_decode($raw, true);
echo "Count: " . count($j["series"]) . PHP_EOL;Spread vs benchmark: /spread
Compute the NZ 10Y spread vs a benchmark (e.g., US 10Y). Spreads are returned in basis points (bps). You can omit the maturity to default to 10Y.
cURL
JSON response
Interpretation:
- spread_bps: NZ 10Y minus benchmark 10Y in basis points.
- country_yield and benchmark_yield: both in percent.
Python
import requests
p = {"country": "NZ", "benchmark": "US", "maturity": "10Y"}
s = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p).json()
print("NZ vs US 10Y spread (bps):", s["spread_bps"])JavaScript
const sp = new URL("https://bonds-api.com/api/v1/spread");
sp.searchParams.set("country", "NZ");
sp.searchParams.set("benchmark", "US");
sp.searchParams.set("maturity", "10Y");
fetch(sp.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log(`Spread: ${j.spread_bps} bps`));PHP
<?php
$u = "https://bonds-api.com/api/v1/spread?country=NZ&benchmark=US&maturity=10Y";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$raw = file_get_contents($u, false, $ctx);
$j = json_decode($raw, true);
echo "Spread (bps): " . $j["spread_bps"] . PHP_EOL;Full New Zealand yield curve: /curve
Get a snapshot of NZ yields across maturities to build the curve. You can query the latest or specify a date.
cURL
JSON response
Interpretation:
- curve: key-value map of maturity to yield in percent.
- inverted: boolean flag if shorter maturities exceed longer ones overall.
- date: market date of the curve snapshot.
Python
import requests
r = requests.get("https://bonds-api.com/api/v1/curve",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "NZ"})
curve = r.json()["curve"]
nz10y = curve["10Y"]
print("NZ curve 10Y:", nz10y)JavaScript
const cv = new URL("https://bonds-api.com/api/v1/curve");
cv.searchParams.set("country", "NZ");
fetch(cv.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log("10Y:", j.curve["10Y"], "Inverted:", j.inverted));PHP
<?php
$u = "https://bonds-api.com/api/v1/curve?country=NZ";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$raw = file_get_contents($u, false, $ctx);
$j = json_decode($raw, true);
echo "10Y: " . $j["curve"]["10Y"] . " Inverted: " . ($j["inverted"] ? "yes" : "no") . PHP_EOL;Intraday snapshots: /intraday
Use this for sub-daily NZ 10Y monitoring. Timestamps are returned in UTC; align them to your display timezone as needed. The date parameter identifies the market day whose intraday snapshots you want.
cURL
JSON response
Interpretation:
- snapshots[].yield: percent
- snapshots[].fetched_at: ISO 8601 timestamp (UTC)
- count: number of snapshots for the date
Python
import requests
p = {"country": "NZ", "maturity": "10Y", "date": "2026-10-16"}
j = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=p).json()
for s in j["snapshots"]:
print(s["fetched_at"], s["yield"])JavaScript
const intr = new URL("https://bonds-api.com/api/v1/intraday");
Object.entries({ country: "NZ", maturity: "10Y", date: "2026-10-16" })
.forEach(([k, v]) => intr.searchParams.set(k, v));
fetch(intr.toString(), { 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
<?php
$u = "https://bonds-api.com/api/v1/intraday?country=NZ&maturity=10Y&date=2026-10-16";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$raw = file_get_contents($u, false, $ctx);
$j = json_decode($raw, true);
foreach ($j["snapshots"] as $s) {
echo $s["fetched_at"] . " " . $s["yield"] . PHP_EOL;
}Fluctuation summary: /fluctuation
Summarize NZ 10Y change between two dates, plus min/max in the period. Useful for reporting, alerts, and chart annotations.
cURL
JSON response
Interpretation:
- change: end_yield − start_yield, in percent.
- min and max: period extremes, in percent.
Python
import requests
q = {"countries": "NZ", "maturity": "10Y", "start": "2025-10-16", "end": "2026-10-16"}
j = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q).json()
nz = j["data"]["NZ"]
print("Δ:", nz["change"], "Min:", nz["min"], "Max:", nz["max"])JavaScript
const fl = new URL("https://bonds-api.com/api/v1/fluctuation");
Object.entries({ countries: "NZ", maturity: "10Y", start: "2025-10-16", end: "2026-10-16" })
.forEach(([k, v]) => fl.searchParams.set(k, v));
fetch(fl.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
const x = j.data.NZ;
console.log("Change:", x.change, "Min:", x.min, "Max:", x.max);
});PHP
<?php
$u = "https://bonds-api.com/api/v1/fluctuation?countries=NZ&maturity=10Y&start=2025-10-16&end=2026-10-16";
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$raw = file_get_contents($u, false, $ctx);
$j = json_decode($raw, true);
$nz = $j["data"]["NZ"];
echo "Change: {$nz['change']} Min: {$nz['min']} Max: {$nz['max']}" . PHP_EOL;Working with maturities and building a curve from symbols
To build a NZ yield curve programmatically, you have two options:
- Call /api/v1/curve?country=NZ to receive a ready-to-use curve map across standard maturities in one response.
- Call /api/v1/latest with multiple maturities (e.g., 1M,3M,6M,1Y,2Y,5Y,10Y,30Y) if you need a specific subset or to align with your analytics model.
When requesting multiple maturities on /latest, the response nests yields per maturity under data.NZ.<tenor>. All yields remain in percent. On non-trading days or during New Zealand public holidays, expect the latest available business-day date to be returned (depending on data availability); your application should display the date alongside the yield to avoid confusion.
Update frequency, business days, and caching
- Market days: Daily yields reflect New Zealand sovereign trading calendars. Weekends and public holidays do not produce new observations; use the date field to verify the effective market day.
- Intraday: /intraday returns timestamped snapshots with fetched_at in UTC. For real-time dashboards, poll at a cadence that respects rate limits and your latency requirements.
- Caching: Cache static historical data aggressively. For /latest and /curve, consider short-lived caches tied to market sessions. Always key caches by both country and maturity set.
- Clock and timezone: Normalize all times to UTC in backends. Convert to local time only for display.
Error handling and resiliency
Standardized error responses include success=false and a human-readable error field. Handle these HTTP statuses:
- 401: Missing or invalid X-API-Key
- 403: Account quota exceeded
- 404: No data for requested country/maturity/date combination
- 422: Invalid parameter (e.g., malformed date or unknown ISO2 code)
- 429: Rate limit exceeded
- 500: Server error
For batch workloads: retry with exponential backoff on 429 and 500. For user-facing apps: surface the error message and suggest changing the date or maturity if 404/422 occur.
Use cases for NZ 10Y in fixed-income tooling
- Risk and duration: Pair NZ 10Y time series with your portfolio holdings to estimate DV01 sensitivity under yield shocks.
- Macro dashboards: Display NZ 10Y and its spread to US 10Y using /spread, updating intraday as snapshots arrive.
- Curve analytics: Pull the /curve each day, compute slope metrics (e.g., 2s10s, 5s30s) and flag inversion via the inverted field.
- Event studies: Combine /historical and /timeseries to measure pre/post changes around RBNZ announcements or macro releases.
If you are starting an integration, see bonds-api.com and Get started with Bonds API.
Quick comparison: key NZ maturities often used
| Maturity | What it signals | Typical use |
|---|---|---|
| 2Y | Near-term policy expectations | Rates strategy, front-end hedges |
| 5Y | Intermediate inflation/policy view | Curve trades, swap overlays |
| 10Y | Benchmark long-end rate for NZD | Valuation, discount rates, macro dashboards |
| 30Y | Long-run growth and term premium | ALM, pension duration hedging |
Sovereign context: what the NZ 10Y represents
The New Zealand 10-year government bond yield is the reference long-dated risk-free rate in NZD. Analysts use it to benchmark corporate issuance, price cash flows, and infer the market’s stance on growth and inflation over the next decade. In spreads and cross-market analysis, comparing NZ 10Y to US 10Y or other benchmarks reveals relative value and capital-flow dynamics.
Production checklist
- Always display the yield’s effective date next to the value.
- Normalize times to UTC in storage; convert only at the edge for UI.
- Cache historical endpoints strongly; keep /latest and /curve caches short.
- Use /fluctuation for lightweight summaries in widgets and emails.
- Detect missing days (holidays/weekends) rather than assuming continuity.
FAQ
Q: Are yields returned in percent or decimals?
A: Percent. For example, 4.52 means 4.52% per annum. Spreads with the _bps suffix are basis points.
Q: How do I handle New Zealand public holidays?
A: On holidays and weekends there are no new daily observations. Use /timeseries and rely on the presence or absence of a date to infer business days, or fall back to the latest available business day for displays.
Q: Can I get both NZ 2Y and 10Y in one request?
A: Yes. Use /latest with countries=NZ and maturities=2Y,10Y to compose curve points for a dashboard or spread calculation.
Q: What timezone do intraday timestamps use?
A: Intraday snapshots return ISO 8601 timestamps in UTC. Convert to your preferred timezone for display.
Q: How do I compute the NZ–US 10Y spread?
A: Call /spread with country=NZ, benchmark=US, maturity=10Y. The spread_bps field is the NZ minus US yield in basis points.
Ready to integrate the New Zealand 10-year yield into your tools? Use the Register link to get your API key and start building. For discovery and developer utilities, visit the MCP. You can also Get started with Bonds API or learn more on bonds-api.com.