Teams building fixed-income dashboards, risk tools, and research notebooks often struggle to source clean, up-to-date sovereign yield data and assemble it into yield curves and spreads. By the end of this article, you will query New Zealand (NZ) government bond yields from Bonds API, retrieve the latest, historical, intraday, and time-series data, compute spreads versus benchmarks, and assemble a full NZ yield curve programmatically.
Scope, maturities, and how NZ yields are represented
Bonds API provides sovereign bond yields for New Zealand across money-market and bond maturities, from 1M bills to 30Y bonds, with broader coverage across 60+ countries. All requests are HTTP GET to the base URL https://bonds-api.com/api/v1/ and authenticated via the X-API-Key header. Yields are expressed as percentages (e.g., 4.52 means 4.52%), spreads are in basis points (bps), and timestamps are ISO 8601. You can learn more and explore endpoints on bonds-api.com.
The New Zealand yield curve example from the API includes these maturities:
| Maturity | Typical Instrument | Use in Curve |
|---|---|---|
| 1M | Bill | Short end anchor |
| 3M | Bill | Money market |
| 6M | Bill | Money market |
| 1Y | Note/Bill | Transition to bond curve |
| 2Y | Bond | Short/intermediate |
| 5Y | Bond | Intermediate |
| 10Y | Bond | Benchmark long end |
| 30Y | Bond | Long end |
If you are just getting started, you can Register for an API key and test the endpoints below. For a quick way to inspect requests and responses, see the MCP.
Authentication, units, dates, and time zones
Authentication is supplied via the X-API-Key header. All yields are percentages. Spread values (spread_bps) are basis points (1 bps = 0.01%). Responses include dates in Y-m-d format (e.g., 2026-10-31) and ISO 8601 timestamps (e.g., 2026-10-31T12:00:00Z). Intraday snapshots are timestamped in UTC, as indicated by the meta.timezone.
On non-trading days (weekends and local market holidays), daily endpoints return the latest available business-day data. For missing combinations (e.g., unsupported maturity on a date), a 404 error is returned with a message. Cache your results per business day for historical queries and consider short-lived caching for intraday to reduce repeated fetches during a session.
Explore the API and documentation at bonds-api.com. When ready to integrate, Get started with Bonds API.
Latest yields for New Zealand
Use the latest endpoint to fetch current yields for one or more maturities. Provide ISO2 country codes and optional maturities. Yields are percentages and the date indicates the business day for the rate.
Official sample (verbatim)
The following official sample demonstrates a latest request and response. Copying these two blocks verbatim is required for reference.
curl -s "https://bonds-api.com/api/v1/latest?countries=NZ&maturities=10Y&api_key=YOUR_API_KEY"
{
"success": true,
"date": "2026-10-30",
"rates": {
"NZ_10Y": 4.838
},
"dates": {
"NZ_10Y": "2026-10-30"
},
"currencies": {
"NZ_10Y": "NZD"
},
"meta": {
"request_id": "d4b19f20-146f-4ce6-b657-487368e614e5",
"timestamp": "2026-10-31T00:04:06+00:00"
}
}
How to read this sample:
- rates.NZ_10Y is the 10-year New Zealand government bond yield in percent (4.838 means 4.838%).
- date/dates.NZ_10Y are the data dates in Y-m-d.
- currencies.NZ_10Y shows the base currency (NZD) associated with the instrument.
- meta.timestamp is the fetch time in ISO 8601, UTC.
Production pattern (header authentication and structured response)
Below is the standard latest endpoint format (header-based auth). You can request multiple maturities to build a quick curve snapshot.
cURL
JSON response
Field notes:
- yield: percentage (e.g., 4.52% = 0.0452 as decimal).
- date: Y-m-d trading day for the yield.
- source: yield origin (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"},
timeout=10
)
resp.raise_for_status()
data = resp.json()
nz_2y = data["data"]["NZ"]["2Y"]["yield"]
nz_10y = data["data"]["NZ"]["10Y"]["yield"]
print("NZ 2Y:", nz_2y, "NZ 10Y:", nz_10y)
JavaScript (fetch)
const url = new URL("https://bonds-api.com/api/v1/latest");
url.search = new URLSearchParams({ countries: "NZ", maturities: "2Y,10Y" }).toString();
fetch(url.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
const twoY = j.data.NZ["2Y"].yield;
const tenY = j.data.NZ["10Y"].yield;
console.log("NZ 2Y:", twoY, "NZ 10Y:", tenY);
});
PHP (file_get_contents)
<?php
$context = stream_context_create([
"http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]
]);
$q = http_build_query(["countries" => "NZ", "maturities" => "2Y,10Y"]);
$json = file_get_contents("https://bonds-api.com/api/v1/latest?$q", false, $context);
$data = json_decode($json, true);
echo "NZ 10Y: " . $data["data"]["NZ"]["10Y"]["yield"] . PHP_EOL;
Historical yield on a specific date (point-in-time NZ yield)
Query the on-the-day yield for a country and maturity. Use Y-m-d for the date.
cURL
JSON response
Read yield as a percentage; date uses Y-m-d. Use this endpoint for compliance-grade backfills and point-in-time analysis.
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/historical",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "NZ", "maturity": "10Y", "date": "2025-06-15"},
timeout=10
)
resp.raise_for_status()
hist = resp.json()
print(hist["date"], hist["maturity"], hist["yield"])
JavaScript
const url = new URL("https://bonds-api.com/api/v1/historical");
url.search = new URLSearchParams({ country: "NZ", maturity: "10Y", date: "2025-06-15" });
fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log(j.date, j.maturity, j.yield));
PHP
<?php
$params = http_build_query(["country" => "NZ", "maturity" => "10Y", "date" => "2025-06-15"]);
$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/historical?$params", false, $ctx);
echo $out;
Time series for New Zealand yields
Fetch daily yields between two dates to power charts, factor models, and risk backtests.
cURL
JSON response
Series is an array of date/yield objects. Values are daily business-day closes where available.
Python
import requests
r = requests.get(
"https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "NZ", "maturity": "10Y", "start": "2025-10-31", "end": "2026-10-31"},
)
ts = r.json()["series"]
print("Points:", len(ts))
JavaScript
const qs = new URLSearchParams({ country: "NZ", maturity: "10Y", start: "2025-10-31", end: "2026-10-31" });
fetch("https://bonds-api.com/api/v1/timeseries?" + qs, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log("First point:", j.series[0]));
PHP
<?php
$q = http_build_query(["country" => "NZ", "maturity" => "10Y", "start" => "2025-10-31", "end" => "2026-10-31"]);
$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/timeseries?$q", false, $ctx);
Spread versus a benchmark (New Zealand vs US)
Compute the NZ yield spread (in basis points) versus a benchmark such as the US Treasury at a given maturity.
cURL
JSON response
Field notes:
- spread_bps: difference in basis points (NZ minus benchmark).
- country_yield, benchmark_yield: both in percent.
Python
import requests
res = requests.get(
"https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "NZ", "benchmark": "US", "maturity": "10Y"},
)
sp = res.json()
print("NZ-US 10Y spread (bps):", sp["spread_bps"])
JavaScript
const params = new URLSearchParams({ country: "NZ", 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(j => console.log(`Spread: ${j.spread_bps} bps`));
PHP
<?php
$q = http_build_query(["country" => "NZ", "benchmark" => "US", "maturity" => "10Y"]);
$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/spread?$q", false, $ctx);
Full New Zealand yield curve
Pull the country curve in one call. Optionally specify a historical date (Y-m-d); otherwise, the latest available business day is returned. The inverted field indicates whether the short end is above the long end.
cURL
JSON response
Field notes:
- curve: map of maturity to yield in percent.
- date: Y-m-d for the curve snapshot.
- inverted: boolean flag indicating whether the curve is inverted.
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()
ten_y = curve["curve"]["10Y"]
two_y = curve["curve"]["2Y"]
print("2s10s (bps):", (ten_y - two_y) * 100)
JavaScript
fetch("https://bonds-api.com/api/v1/curve?country=NZ", { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
const s2s10 = (j.curve["10Y"] - j.curve["2Y"]) * 100;
console.log("2s10s:", s2s10.toFixed(1), "bps");
});
PHP
<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$resp = file_get_contents("https://bonds-api.com/api/v1/curve?country=NZ", false, $ctx);
echo $resp;
Intraday NZ yield snapshots
Use intraday snapshots for session-level monitoring and microstructure analysis. Each snapshot includes a yield, its fetch timestamp (UTC), and a source tag.
cURL
JSON response
Field notes:
- snapshots[].yield: percentage, intra-session value.
- snapshots[].fetched_at: ISO 8601 timestamp in UTC.
- date: trading day; meta.timezone clarifies the timestamp zone.
Python
import requests
resp = requests.get(
"https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"country": "NZ", "maturity": "10Y", "date": "2026-10-31"},
)
snap = resp.json()["snapshots"]
# Compute intraday high-low in bps
yields = [s["yield"] for s in snap]
hi_lo_bps = (max(yields) - min(yields)) * 100
print("Intraday range (bps):", round(hi_lo_bps, 1))
JavaScript
const p = new URLSearchParams({ country: "NZ", maturity: "10Y", date: "2026-10-31" });
fetch("https://bonds-api.com/api/v1/intraday?" + p, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log("Snapshots:", j.count, "Timezone:", j.meta.timezone));
PHP
<?php
$q = http_build_query(["country" => "NZ", "maturity" => "10Y", "date" => "2026-10-31"]);
$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?$q", false, $ctx);
Fluctuation over a period (change, min, max for NZ)
Summarize how a yield moved over a period, including start, end, absolute change, and observed min/max in that window. Useful for performance and risk summaries.
cURL
JSON response
Field notes:
- start_yield/end_yield/min/max: percentages.
- change: absolute difference in percentage points (end minus start).
Python
import requests
res = requests.get(
"https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"countries": "NZ", "maturity": "10Y", "start": "2025-10-31", "end": "2026-10-31"},
)
fx = res.json()["data"]["NZ"]
print("Change (bps):", fx["change"] * 100, "Min:", fx["min"], "Max:", fx["max"])
JavaScript
const q = new URLSearchParams({ countries: "NZ", maturity: "10Y", start: "2025-10-31", end: "2026-10-31" });
fetch("https://bonds-api.com/api/v1/fluctuation?" + q, { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => console.log(j.data.NZ));
PHP
<?php
$q = http_build_query(["countries" => "NZ", "maturity" => "10Y", "start" => "2025-10-31", "end" => "2026-10-31"]);
$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?$q", false, $ctx);
Build and use the New Zealand yield curve
To assemble a curve snapshot, the /curve endpoint is the simplest option. If you prefer to control maturities explicitly, call /latest with multiple maturities. For modeling, you can fit a spline or Nelson-Siegel-Svensson curve to the maturity/yield points returned.
- Short-end maturities (1M–6M) inform monetary policy expectations and liquidity conditions.
- Intermediate (2Y–5Y) reflect medium-term policy paths and growth/inflation balance.
- Long-end (10Y–30Y) embed term premium and long-run macro expectations.
Common spreads derived from the NZ curve:
- 2s10s: curve["10Y"] - curve["2Y"], often reported in bps.
- 5s30s: curve["30Y"] - curve["5Y"], used to gauge long-end steepness.
When aggregating across endpoints, keep units consistent (percent vs bps) and align on dates. If you mix intraday with end-of-day, tag each point with its timestamp to avoid misinterpretation.
Operational details: business days, holidays, updates, caching, errors
Business days: Daily endpoints return observations for trading days; weekends and NZ market holidays will not have new daily prints. The “latest” endpoints return the most recent available day with data. Intraday adds timestamped snapshots in UTC.
Update cadence: Intraday snapshots are timestamped; for end-of-day, plan a daily refresh after the data date closes. Cache daily reads by date and maturity and consider moderate in-memory caching for intraday to reduce repeated round-trips during a session.
Error handling: Common error shapes include success=false and an error message. Typical HTTP statuses:
- 401: Missing or invalid X-API-Key
- 403: Account quota exceeded
- 404: No data for requested country/maturity/date
- 422: Invalid parameter (e.g., bad date format)
- 429: Rate limit exceeded
- 500: Server error
Always check success before reading fields, validate date formats (Y-m-d), and clamp or retry on 429 with backoff. For interactive use, the MCP is a quick way to reproduce issues and inspect responses.
Use cases for developers, quants, and fintech teams
- Portfolio monitoring: Track NZ 10Y in real time via intraday and alert when spreads vs US exceed a threshold.
- Risk and scenario analysis: Pull historical time series to calibrate interest-rate shocks and compute VaR or stress scenarios.
- Macro dashboards: Combine the NZ curve and spreads to visualize curve shape, inversion flags, and weekly changes.
- Relative value: Use fluctuation stats to identify periods of elevated volatility; pair with spread endpoint for cross-market signals.
Start building with endpoints shown here and iterate into your stack. Reference materials and examples are available at bonds-api.com.
FAQ
How are yields and spreads expressed?
Yields are percentages (e.g., 4.52 means 4.52%). Spreads (spread_bps) are basis points (1 bps = 0.01%). When you compute custom spreads, multiply percentage-point differences by 100 to express them in bps.
Which time zone are timestamps using?
Daily fields use Y-m-d dates. Intraday snapshots include ISO 8601 timestamps and meta.timezone indicates UTC in the intraday response.
What happens on weekends and NZ market holidays?
Daily endpoints return the latest available business-day data. If you request a non-existent date/maturity combination, expect a 404 with an error message.
Can I fetch multiple maturities at once?
Yes. Use /latest with a comma-separated maturities list (e.g., 2Y,5Y,10Y) or call /curve to retrieve a country’s full curve for a given date.
How should I cache results?
Cache daily requests by country, maturity, and date. For intraday, apply short-lived caching (e.g., seconds to minutes) within a session. Always verify the response’s date/timestamp to avoid stale mixes.
Ready to integrate New Zealand yields, curves, and spreads into your tools? Generate your API key and start querying today: Register. For quick endpoint checks and live response exploration, open the MCP.