API to Get New Zealand Bond Yields

API to Get New Zealand Bond Yields

Teams building trading tools, risk dashboards, or research notebooks often struggle to source reliable, developer-friendly New Zealand government bond yields. By the end of this article, you will be able to fetch current NZ yields, historical values, intraday snapshots, full yield curves, and benchmark spreads from a single REST API, and wire them into your code with robust handling for dates, business days, and caching.

What New Zealand government bond yields represent

New Zealand sovereign bonds (issued by the New Zealand Government) are risk-free benchmarks for NZD fixed income. Their yields reflect borrowing costs across the maturity spectrum, from short-term bills (1–6 months) to long-term bonds (10–30 years). Analysts use these yields to construct curves, price interest-rate derivatives, measure macro expectations, and manage duration and convexity risk.

Illustration: API to Get New Zealand Bond Yields

Unless otherwise noted, yields returned by the API are expressed in percent (for example, 4.52 means 4.52%). Dates are in YYYY-MM-DD. Timestamps in the metadata are in ISO 8601 with timezone offset, and intraday snapshots include times in UTC.

You can explore the API at https://bonds-api.com and review endpoint behavior with the MCP before integrating into production.

Quick sample: latest NZ 10Y yield (official sample)

The blocks below show an official sample call and response for the latest New Zealand 10-year yield. Copy exactly to validate your environment, then continue with the endpoint-specific guides that follow.

curl -s "https://bonds-api.com/api/v1/latest?countries=NZ&maturities=10Y&api_key=YOUR_API_KEY"
{
    "success": true,
    "date": "2026-11-13",
    "rates": {
        "NZ_10Y": 4.848
    },
    "dates": {
        "NZ_10Y": "2026-11-13"
    },
    "currencies": {
        "NZ_10Y": "NZD"
    },
    "meta": {
        "request_id": "b6331982-1018-499b-b15b-9c269cea60aa",
        "timestamp": "2026-11-15T00:04:05+00:00"
    }
}

How to read it:

  • rates.NZ_10Y: latest 10-year government bond yield in percent.
  • date and dates.NZ_10Y: last market date for the provided yield (YYYY-MM-DD).
  • currencies.NZ_10Y: base currency of the instrument (NZD).
  • meta.timestamp: the server-side time (UTC) the response was generated.

Authentication, base URL, and request method

All Bonds API endpoints are HTTP GET under the same base:

Base URL: https://bonds-api.com/api/v1/

Auth: Include your key in the X-API-Key header.

This article focuses on New Zealand (ISO2 code NZ). For end-to-end integration and to generate your API key, use the links below:

Endpoint guide for New Zealand yields

1) Latest: GET /api/v1/latest — current NZ yields

Use this to retrieve the most recent available yields. You can specify maturities or omit to get all available tenors for New Zealand.

cURL

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"}
)
data = resp.json()
# Example access:
# nz_2y = data["data"]["NZ"]["2Y"]["yield"]
# nz_10y = data["data"]["NZ"]["10Y"]["yield"]

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 nz2y = json.data.NZ["2Y"].yield;
// const nz10y = json.data.NZ["10Y"].yield;
console.log(json);
});

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=NZ&maturities=2Y,10Y";
$response = file_get_contents($url, false, $context);
$json = json_decode($response, true);
// $nz2y = $json["data"]["NZ"]["2Y"]["yield"];
// $nz10y = $json["data"]["NZ"]["10Y"]["yield"];

JSON response (example)

Fields:

  • yield: percentage yield (e.g., 4.52 means 4.52%).
  • date: market date for that observation (YYYY-MM-DD).
  • source: data provenance label.

2) Historical: GET /api/v1/historical — yield on a specific date

Query a single maturity on a given day, useful for backfills or date-stamped analytics.

cURL

Python

import requests

params = {"country": "NZ", "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)
j = r.json()
# y = j["yield"]; d = j["date"]; m = j["maturity"]

JavaScript

const p = new URL("https://bonds-api.com/api/v1/historical");
p.searchParams.set("country", "NZ");
p.searchParams.set("maturity", "10Y");
p.searchParams.set("date", "2025-06-15");

fetch(p.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
// const y = j.yield;
// const dt = j.date;
console.log(j);
});

PHP

<?php
$ctx = stream_context_create(["http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]]);
$u = "https://bonds-api.com/api/v1/historical?country=NZ&maturity=10Y&date=2025-06-15";
$res = file_get_contents($u, false, $ctx);
$j = json_decode($res, true);
// $y = $j["yield"]; $d = $j["date"];

JSON response (example)

Fields are self-descriptive. If the date is a non-trading day, the API may return no data (404) or the closest available business day depending on the endpoint; handle 404 errors when pinning to exact dates.

3) Time series: GET /api/v1/timeseries — daily NZ yields between two dates

Retrieve daily yields for a maturity over a range. Useful for charts, regressions, or backtesting.

cURL

Python

import requests

params = {
"country": "NZ",
"maturity": "10Y",
"start": "2025-11-15",
"end": "2026-11-15"
}
r = requests.get("https://bonds-api.com/api/v1/timeseries",
headers={"X-API-Key": "YOUR_API_KEY"},
params=params)
series = r.json()["series"]
# Each item: {"date": "YYYY-MM-DD", "yield": float}

JavaScript

const ts = new URL("https://bonds-api.com/api/v1/timeseries");
Object.entries({
country: "NZ",
maturity: "10Y",
start: "2025-11-15",
end: "2026-11-15"
}).forEach(([k, v]) => ts.searchParams.set(k, v));

fetch(ts.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
// j.series is an array of { date, yield }
console.log(j.series);
});

PHP

<?php
$ctx = stream_context_create(["http" => [
"method" => "GET",
"header" => "X-API-Key: YOUR_API_KEY\r\n"
]]);
$u = "https://bonds-api.com/api/v1/timeseries?country=NZ&maturity=10Y&start=2025-11-15&end=2026-11-15";
$res = file_get_contents($u, false, $ctx);
$j = json_decode($res, true);
// $series = $j["series"];

JSON response (example)

Each entry is a daily end-of-day yield in percent. Missing days (weekends/holidays) are omitted rather than repeated; your charting code should handle non-continuous dates.

4) Spread: GET /api/v1/spread — NZ vs benchmark (e.g., US 10Y)

Return the yield spread in basis points versus a benchmark country at a given maturity. Defaults to 10Y if maturity is omitted.

cURL

Python

import requests

args = {"country": "NZ", "benchmark": "US", "maturity": "10Y"}
r = requests.get("https://bonds-api.com/api/v1/spread",
headers={"X-API-Key": "YOUR_API_KEY"},
params=args)
j = r.json()
# spread_bps = j["spread_bps"]; nz = j["country_yield"]; us = j["benchmark_yield"]

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 => {
// j.spread_bps is in basis points
console.log(j);
});

PHP

<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$u = "https://bonds-api.com/api/v1/spread?country=NZ&benchmark=US&maturity=10Y";
$j = json_decode(file_get_contents($u, false, $ctx), true);
// $bps = $j["spread_bps"];

JSON response (example)

spread_bps is in basis points (1 bp = 0.01%). A positive value means NZ yields are higher than the benchmark at that maturity.

5) Curve: GET /api/v1/curve — full NZD sovereign yield curve

Retrieve a cross-section of NZ yields for major maturities at the latest available date or a specific date. This powers curve visualization and interpolation.

cURL

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()
# Use curve["curve"] mapping keyed by tenors ("1M","3M","6M","1Y","2Y","5Y","10Y","30Y")

JavaScript

const c = new URL("https://bonds-api.com/api/v1/curve");
c.searchParams.set("country", "NZ");

fetch(c.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
// j.curve is an object mapping tenor -> yield
console.log(j.curve);
});

PHP

<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$u = "https://bonds-api.com/api/v1/curve?country=NZ";
$j = json_decode(file_get_contents($u, false, $ctx), true);
// $tenors = $j["curve"];

JSON response (example)

Fields:

  • curve: tenor-to-yield mapping, yields in percent.
  • date: valuation date (latest available if omitted).
  • inverted: true if short-dated yields exceed long-dated yields (e.g., 2Y > 10Y).

6) Intraday: GET /api/v1/intraday — trading-day snapshots

Retrieve intraday snapshots for a given NZ maturity on a specified date. Use for live dashboards and alerting.

cURL

Python

import requests

q = {"country": "NZ", "maturity": "10Y", "date": "2026-11-15"}
r = requests.get("https://bonds-api.com/api/v1/intraday",
headers={"X-API-Key": "YOUR_API_KEY"},
params=q)
snapshots = r.json()["snapshots"]
# Each snapshot: {"yield": float, "fetched_at": "YYYY-MM-DDTHH:MM:SSZ", "source": "..."}

JavaScript

const intr = new URL("https://bonds-api.com/api/v1/intraday");
intr.searchParams.set("country", "NZ");
intr.searchParams.set("maturity", "10Y");
intr.searchParams.set("date", "2026-11-15");

fetch(intr.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
// j.meta.timezone is "UTC"; j.snapshots is an array
console.table(j.snapshots);
});

PHP

<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$u = "https://bonds-api.com/api/v1/intraday?country=NZ&maturity=10Y&date=2026-11-15";
$j = json_decode(file_get_contents($u, false, $ctx), true);
// $rows = $j["snapshots"];

JSON response (example)

fetched_at is the retrieval timestamp in UTC. Yields are in percent. Intraday density varies with market liquidity and data source cadence.

7) Fluctuation: GET /api/v1/fluctuation — change, min, and max over a period

Summarize period performance for one or more countries at a given maturity. Ideal for monitoring sheets and summary widgets.

cURL

Python

import requests

args = {
"countries": "NZ",
"maturity": "10Y",
"start": "2025-11-15",
"end": "2026-11-15"
}
r = requests.get("https://bonds-api.com/api/v1/fluctuation",
headers={"X-API-Key": "YOUR_API_KEY"},
params=args)
nz = r.json()["data"]["NZ"]
# start_yield, end_yield, change, min, max are all in percent

JavaScript

const fl = new URL("https://bonds-api.com/api/v1/fluctuation");
Object.entries({
countries: "NZ",
maturity: "10Y",
start: "2025-11-15",
end: "2026-11-15"
}).forEach(([k, v]) => fl.searchParams.set(k, v));

fetch(fl.toString(), { headers: { "X-API-Key": "YOUR_API_KEY" } })
.then(r => r.json())
.then(j => {
// j.data.NZ contains start_yield, end_yield, change, min, max
console.log(j.data.NZ);
});

PHP

<?php
$ctx = stream_context_create(["http" => ["method" => "GET", "header" => "X-API-Key: YOUR_API_KEY\r\n"]]);
$u = "https://bonds-api.com/api/v1/fluctuation?countries=NZ&maturity=10Y&start=2025-11-15&end=2026-11-15";
$j = json_decode(file_get_contents($u, false, $ctx), true);
// $nz = $j["data"]["NZ"];

JSON response (example)

All values are in percent. change equals end_yield minus start_yield. Use this endpoint for alerts (e.g., 1Y highs/lows) and performance summaries.

Building a New Zealand yield curve and reading maturities

There are two primary ways to build a NZ yield curve:

  • Use /curve for a ready-made, dated cross-section including bills and bonds.
  • Use /latest with multiple maturities (e.g., 1Y, 2Y, 5Y, 10Y, 30Y) when you want to mix and match or standardize across countries.

Available maturities commonly include money-market tenors (1M, 3M, 6M), near-term notes (1Y, 2Y, 5Y), and longer bonds (10Y, 30Y). The example below shows typical placements returned by the curve endpoint.

MaturityDescriptionUsage
1M, 3M, 6MT-billsCash curve, front-end expectations
1Y, 2YShort-dated notesPolicy path, near-term term-premia
5YIntermediate noteMacro expectations, belly of curve
10YBenchmark bondRisk-free rate for discounting, duration anchor
30YLong bondALM, long-duration hedging

Practical details: timings, business days, and caching

  • Business days and holidays: Daily endpoints (/latest, /historical, /timeseries, /curve) reflect trading calendars. Weekends and NZ public holidays will not have new observations; /timeseries simply omits non-business days. When pinning exact dates with /historical, handle 404 (no data for that date).
  • Update frequency:
    • Daily yields: typically once per business day (end-of-day or last published official print).
    • Intraday snapshots: variable cadence during the trading session; timestamps are in UTC.
  • Units: All yields are percentages. Spread values from /spread are in basis points (bps).
  • Timezone: All date fields use YYYY-MM-DD. Intraday fetched_at and meta.timestamp are ISO 8601 with UTC offset; meta.timezone returns "UTC" in intraday responses.
  • Caching:
    • Cache daily endpoints by country, date, and maturity. For example, cache /curve?country=NZ by its date field.
    • Short-cache intraday (e.g., 30–60 seconds) to avoid hammering endpoints while ensuring freshness.
    • Implement backoff and respect 429 responses (rate limit exceeded); retry with jitter.
  • Error handling: All errors share the shape {"success": false, "error": "..."} with standard HTTP codes:
    • 401 missing/invalid key, 403 quota exceeded, 404 no data for requested combo, 422 invalid parameter, 429 rate limit, 500 server error.

If you need to test responses and experiment with parameters, the MCP is a convenient way to run queries interactively. See bonds-api.com for more coverage information and countries.

Use cases for NZD fixed-income teams

  • Portfolio risk dashboards: pull /curve for duration and key-rate duration buckets; use /spread vs US to track cross-market valuation.
  • Quant research: download /timeseries for regressions on macro releases; combine with /fluctuation for event windows.
  • Trading UIs: display /intraday snapshots for NZ 10Y during the session; backfill day-end with /latest.
  • ALM and treasury: monitor long-end levels from /curve and threshold alerts with /fluctuation min/max.

Putting it together: example workflow

A common NZ workflow is:

  1. At market open, seed your dashboard with /latest for NZ across key tenors (2Y, 5Y, 10Y).
  2. During the day, poll /intraday on NZ 10Y to update charts. Cache for 30–60 seconds.
  3. End of day, store /curve for NZ to build dated curve history.
  4. Daily job: compute NZ–US 10Y spreads via /spread and summarize week-to-date with /fluctuation.
  5. Backtesting: load /timeseries for the maturities relevant to your strategy.

Field recap and reading responses

  • yield (percent): a numeric percentage (e.g., 4.52) not a decimal fraction.
  • date (YYYY-MM-DD): the market date of validity.
  • fetched_at (ISO 8601): UTC timestamp for intraday samples.
  • spread_bps (integer/float): basis points difference (1 bp = 0.01%).
  • inverted (boolean): curve inversion flag at the reporting date.
  • source/meta: provenance and server-side metadata including timezone and timestamp.

FAQ

Q: What happens on NZ public holidays?
A: Daily endpoints will not produce a new observation for those dates. /timeseries omits non-business days. For exact-date access with /historical, handle 404 when no quote exists for that day.

Q: Are yields in percent or decimals?
A: Yields are in percent units. For example, 4.52 means 4.52% (not 0.0452). Spread values from /spread are in basis points.

Q: Which timezone do timestamps use?
A: Dates are day-only (YYYY-MM-DD). Timestamps in meta and intraday fetched_at use ISO 8601 with UTC; intraday also returns meta.timezone = "UTC".

Q: Can I request multiple NZ maturities in a single call?
A: Yes. Use /latest with the maturities parameter (comma-separated), or request the entire cross-section via /curve.

Q: How should I cache results?
A: Cache daily endpoints by date and invalidate when a newer date appears. For /intraday, adopt a short TTL (for example 30–60 seconds) and implement exponential backoff on 429.

Ready to integrate New Zealand yields into your app? Generate your key and start calling endpoints in minutes: Register. You can also explore endpoints and payloads interactively in the MCP. For more details and countries, visit bonds-api.com.

Start building with bond data today

Get your API key and access sovereign bond yields across 60+ countries. 7-day free trial, no credit card required.