RBNZ Rate API - InterestRatesAPI Blog

You need the RBNZ Official Cash Rate (RBNZ_OCR) inside your software so you can quote current policy, compute loan spreads, price risk, and backtest strategies. By the end of this article you will be able to fetch the latest RBNZ_OCR, query its history and time series, derive fluctuations and OHLC aggregates, compare loan interest costs, and safely integrate all seven Interest Rates API endpoints into production systems.

RBNZ_OCR: what it is, how it’s expressed, and why it matters

RBNZ_OCR is the Reserve Bank of New Zealand’s Official Cash Rate — the central bank policy benchmark for NZD. It influences wholesale funding costs, floating mortgage rates, and broader financial conditions across New Zealand. In the Interest Rates API, RBNZ_OCR is a central bank symbol with monthly frequency.

Values are returned as numeric percentage rates (e.g., 5.33 represents 5.33%). When you receive data from endpoints like /latest or /historical, you will also see a date string (Y-m-d). For monthly series, the API uses the last day with data within that month for date-based endpoints; your application should treat that as the effective observation date for that month’s OCR setting.

Developers typically use RBNZ_OCR to:

Display current and historical policy rates on dashboards alongside interbank benchmarks.
Compute loan or deposit spreads over policy for pricing and profitability analytics.
Trigger risk model updates on policy changes and backtest macro strategies.
Support lending, treasury, and research workflows that require time-aligned, validated rates.

All examples below call the Interest Rates API at https://interestratesapi.com/api/v1/ and authenticate via the api_key query parameter. Every request is a GET request. Learn more at interestratesapi.com, and if you need an API key you can Get started with Interest Rates API or Register.

Working with authentication, dates, and caching

Authentication is simple: append ?api_key=YOUR_KEY to every URL (or include api_key in the query parameters if you are using a client library). Dates use the Y-m-d format. For monthly symbols, the API returns the last day with data in that month when you query a specific date.

For production performance:

Cache /latest for a short TTL (e.g., intraday) and invalidate when you detect a policy update.
Cache /historical and /timeseries responses longer since backfilled history is stable.
Use rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) to throttle clients.
Handle errors consistently: 401 (auth), 403 (no active plan), 404 (no data), 422 (validation), 429 (quota).

RBNZ decisions occur on business days, and the RBNZ_OCR series is monthly in this API. Align your cron jobs and cache TTLs to business calendars rather than weekends.

Endpoint 1: /symbols — discover available rate symbols

Use /symbols to discover which identifiers are available, or filter for central bank rates or base currencies. While the focus of this article is RBNZ_OCR, this endpoint helps you confirm symbol spelling and metadata before integrating.

cURL

curl -s "https://interestratesapi.com/api/v1/latest?api_key=YOUR_API_KEY&symbols=SOFR"

JSON response example

{
"success": true,
"date": "2026-09-29",
"base": "USD",
"rates": {
"SOFR": 3.88
},
"dates": {
"SOFR": "2026-09-29"
},
"currencies": {
"SOFR": "USD"
},
"base_filter_note": null
}

This example shows the response shape: a list of available symbols matching your filter. For RBNZ_OCR, query with base=NZD or category=central_bank and then filter client-side for "RBNZ_OCR".

Python (requests)

import requests

resp = requests.get(
'https://interestratesapi.com/api/v1/symbols',
params=dict(category='central_bank', base='NZD', api_key='YOUR_KEY')
)
symbols = resp.json()
# Filter for RBNZ_OCR
rbnz = [s for s in symbols.get('symbols', []) if s.get('symbol') == 'RBNZ_OCR']

JavaScript (fetch)

const res = await fetch(
'https://interestratesapi.com/api/v1/symbols?category=central_bank&base=NZD&api_key=YOUR_KEY'
);
const symbols = await res.json();
// Find RBNZ_OCR
const rbnz = (symbols.symbols || []).find(s => s.symbol === 'RBNZ_OCR');

PHP

<?php
$url = 'https://interestratesapi.com/api/v1/symbols?category=central_bank&base=NZD&api_key=YOUR_KEY';
$json = file_get_contents($url);
$data = json_decode($json, true);
$rbnz = null;
if (isset($data['symbols'])) {
foreach ($data['symbols'] as $s) {
if ($s['symbol'] === 'RBNZ_OCR') { $rbnz = $s; break; }
}
}
?>

Endpoint 2: /latest — latest value for RBNZ_OCR

The /latest endpoint returns the most recent observation for one or more symbols. You’ll use this for user-facing dashboards and to compute spreads or loan pricing adjustments.

cURL

JSON response example

Key fields:

rates: a symbol-to-value map of percentage levels (e.g., 5.33 means 5.33%).
dates: the observation date for each symbol; for monthly series, the last available date within the month.
currencies: ISO currency code associated with each rate series.

Official sample: /latest response shape

The following official sample demonstrates the same response structure (different symbol) and must be copied verbatim:

Python (requests)

import requests

response = requests.get(
'https://interestratesapi.com/api/v1/latest',
params=dict(symbols='RBNZ_OCR', api_key='YOUR_KEY')
)
data = response.json()
rbnz_value = data['rates']['RBNZ_OCR']
rbnz_date = data['dates']['RBNZ_OCR']

JavaScript (fetch)

const response = await fetch(
'https://interestratesapi.com/api/v1/latest?symbols=RBNZ_OCR&api_key=YOUR_KEY'
);
const data = await response.json();
const rbnzValue = data.rates['RBNZ_OCR'];
const rbnzDate = data.dates['RBNZ_OCR'];

PHP

<?php
$url = 'https://interestratesapi.com/api/v1/latest?symbols=RBNZ_OCR&api_key=YOUR_KEY';
$json = file_get_contents($url);
$data = json_decode($json, true);
$rbnz_value = $data['rates']['RBNZ_OCR'];
$rbnz_date = $data['dates']['RBNZ_OCR'];
?>

Endpoint 3: /historical — RBNZ_OCR on a specific date

Use /historical to align with statement dates, financial month-end processes, or to compute period-to-period changes properly. For monthly series, the API resolves to the last day with data in that month when you query a date within the month.

cURL

JSON response example

Field notes:

date: the date you requested; for monthly series, the value corresponds to the last in-month observation.
rates: map of symbol to level (percentage).
currencies: symbol to currency code.

Python (requests)

import requests

resp = requests.get(
'https://interestratesapi.com/api/v1/historical',
params=dict(date='2025-06-15', symbols='RBNZ_OCR', api_key='YOUR_KEY')
)
hist = resp.json()
value = hist['rates']['RBNZ_OCR']

JavaScript (fetch)

const res = await fetch(
'https://interestratesapi.com/api/v1/historical?date=2025-06-15&symbols=RBNZ_OCR&api_key=YOUR_KEY'
);
const hist = await res.json();
const value = hist.rates['RBNZ_OCR'];

PHP

<?php
$url = 'https://interestratesapi.com/api/v1/historical?date=2025-06-15&symbols=RBNZ_OCR&api_key=YOUR_KEY';
$data = json_decode(file_get_contents($url), true);
$value = $data['rates']['RBNZ_OCR'];
?>

Endpoint 4: /timeseries — daily-resolved RBNZ_OCR between two dates

/timeseries returns a date-keyed map for each symbol, enabling backtests, dashboards with trend charts, and time-based analytics. Even though RBNZ_OCR is monthly, the API represents it across business days so you can compute period-over-period changes without gaps.

cURL

JSON response example

Field notes:

rates[symbol][date]: the level (percentage) on each business day in the range.
frequencies: indicates the series resolution in the response (daily representation).
currencies: currency code per symbol.

Python (requests)

import requests

resp = requests.get(
'https://interestratesapi.com/api/v1/timeseries',
params=dict(start='2025-10-01', end='2026-10-01', symbols='RBNZ_OCR', api_key='YOUR_KEY')
)
series = resp.json()
rbnz_series = series['rates']['RBNZ_OCR'] # dict of date -> value

JavaScript (fetch)

const res = await fetch(
'https://interestratesapi.com/api/v1/timeseries?start=2025-10-01&end=2026-10-01&symbols=RBNZ_OCR&api_key=YOUR_KEY'
);
const series = await res.json();
const rbnzSeries = series.rates['RBNZ_OCR'];

PHP

<?php
$url = 'https://interestratesapi.com/api/v1/timeseries?start=2025-10-01&end=2026-10-01&symbols=RBNZ_OCR&api_key=YOUR_KEY';
$data = json_decode(file_get_contents($url), true);
$rbnz_series = $data['rates']['RBNZ_OCR']; // associative array date => value
?>

Endpoint 5: /fluctuation — changes, highs, and lows for RBNZ_OCR

/fluctuation computes change statistics for a range, including start/end values, absolute and percentage changes, and range high/low. This is useful to build audit trails, change alerts, and reporting tiles.

cURL

JSON response example

Field notes:

change and change_pct are computed from start_value and end_value. change_pct is null if start_value is 0.
high and low are the extremes observed in the range.

Python (requests)

import requests

resp = requests.get(
'https://interestratesapi.com/api/v1/fluctuation',
params=dict(start='2025-10-01', end='2026-10-01', symbols='RBNZ_OCR', api_key='YOUR_KEY')
)
fluc = resp.json()
stats = fluc['rates']['RBNZ_OCR']

JavaScript (fetch)

const res = await fetch(
'https://interestratesapi.com/api/v1/fluctuation?start=2025-10-01&end=2026-10-01&symbols=RBNZ_OCR&api_key=YOUR_KEY'
);
const fluc = await res.json();
const stats = fluc.rates['RBNZ_OCR'];

PHP

<?php
$url = 'https://interestratesapi.com/api/v1/fluctuation?start=2025-10-01&end=2026-10-01&symbols=RBNZ_OCR&api_key=YOUR_KEY';
$data = json_decode(file_get_contents($url), true);
$stats = $data['rates']['RBNZ_OCR'];
?>

Endpoint 6: /ohlc — monthly or weekly OHLC for RBNZ_OCR

/ohlc computes candlestick-like aggregates from the daily-resolved series. Use this to power charting widgets or to compute range-based analytics without querying all daily points. The OHLC values are computed on the fly from daily data.

cURL

JSON response example

Field notes:

period: the aggregation period (monthly by default; optionally weekly or quarterly).
open/high/low/close: computed from daily data within each period.
data_points: count of underlying daily points used for the aggregation.

Python (requests)

import requests

resp = requests.get(
'https://interestratesapi.com/api/v1/ohlc',
params=dict(symbols='RBNZ_OCR', period='monthly', start='2025-10-01', end='2026-10-01', api_key='YOUR_KEY')
)
ohlc = resp.json()
bars = ohlc['rates']['RBNZ_OCR']

JavaScript (fetch)

const res = await fetch(
'https://interestratesapi.com/api/v1/ohlc?symbols=RBNZ_OCR&period=monthly&start=2025-10-01&end=2026-10-01&api_key=YOUR_KEY'
);
const ohlc = await res.json();
const bars = ohlc.rates['RBNZ_OCR'];

PHP

<?php
$url = 'https://interestratesapi.com/api/v1/ohlc?symbols=RBNZ_OCR&period=monthly&start=2025-10-01&end=2026-10-01&api_key=YOUR_KEY';
$data = json_decode(file_get_contents($url), true);
$bars = $data['rates']['RBNZ_OCR'];
?>

Endpoint 7: /convert — compare total loan interest costs using RBNZ_OCR

/convert compares the simple interest cost of a notional loan at the latest rate of two symbols over a specified term. This is useful to visualize spread-driven cost differences — for example, pricing against a policy rate versus a refinancing benchmark.

cURL

JSON response example

Field notes:

from and to: each block includes the symbol, latest rate, date, and computed total_interest and total_payment for the specified term at simple interest.
difference: rate_spread (in percentage points) and interest_saved for the term and amount.

Python (requests)

import requests

resp = requests.get(
'https://interestratesapi.com/api/v1/convert',
params=dict(from='RBNZ_OCR', to='ECB_MRO', amount=100000, term_months=12, api_key='YOUR_KEY')
)
cmp = resp.json()
spread_bps = cmp['difference']['rate_spread'] * 100 # percentage points to basis points
interest_saved = cmp['difference']['interest_saved']

JavaScript (fetch)

const res = await fetch(
'https://interestratesapi.com/api/v1/convert?from=RBNZ_OCR&to=ECB_MRO&amount=100000&term_months=12&api_key=YOUR_KEY'
);
const cmp = await res.json();
const spread = cmp.difference.rate_spread;
const saved = cmp.difference.interest_saved;

PHP

<?php
$url = 'https://interestratesapi.com/api/v1/convert?from=RBNZ_OCR&to=ECB_MRO&amount=100000&term_months=12&api_key=YOUR_KEY';
$data = json_decode(file_get_contents($url), true);
$spread = $data['difference']['rate_spread'];
$saved = $data['difference']['interest_saved'];
?>

Practical implementation details for RBNZ_OCR

Units and effective dates

Units: All returned levels are percentages (e.g., 5.33 means 5.33%). If you compute interest in decimal form, divide by 100 first.
Effective dates: Use the dates map in /latest and the last in-month observation behavior in /historical for monthly series like RBNZ_OCR.

Business days and frequency

RBNZ_OCR is monthly in this API. The /timeseries response represents it daily so that periods carry forward within the month for alignment with business days.
Plan updates around business calendars; avoid assuming weekend updates.

Caching and invalidation

Cache /symbols (long TTL). It changes rarely.
Cache /latest (short TTL); invalidate on scheduled decision days or when your change detection logic sees a new date or value.
Cache /historical and /timeseries more aggressively. Backfilled history is stable.
Respect 429 responses and use X-RateLimit-* headers to back off and retry after X-RateLimit-Reset.

Error handling

401: Ensure api_key is present and valid.
403: The account lacks an active plan.
404: No data matched your filters or date range (check any details field for available ranges).
422: Fix validation issues (date formats must be Y-m-d; symbols from the documented list only).
429: Apply exponential backoff to your job queues and obey Retry-After if present.

Computing spreads and payments from RBNZ_OCR

Spread over policy: If L is a loan rate and P is RBNZ_OCR from /latest, the spread in percentage points is S = L − P. In basis points, multiply by 100.
Monthly payment (amortizing loan): With principal A, annual percentage rate r (from RBNZ_OCR or your priced rate), monthly rate m = r/12/100, and n months, the payment is: Payment = A × [m × (1 + m)^n] / [(1 + m)^n − 1]. Use your own priced rate for L; you can derive L = P + margin.
Total interest (simple, as in /convert): TotalInterest = A × (r/100) × (n/12).

Use cases you can ship quickly

Mortgage dashboard for NZ portfolios: pull /latest RBNZ_OCR, compute dynamic margins, and render month-over-month shifts from /fluctuation.
Treasury risk monitor: track /ohlc monthly ranges and trigger alerts on new highs/lows within a quarter.
Macro research notebook: pull /timeseries for a backtest window and merge with loan portfolio metrics for spread regressions.
Loan comparison widget: integrate /convert to show cost deltas versus an alternative policy or refinancing benchmark.

Explore more capabilities in the Interest Rates API MCP and the MCP reference, and register for an API key at Register for Interest Rates API.

All endpoints at a glance with RBNZ_OCR

/api/v1/symbols — Discover RBNZ_OCR and metadata.
/api/v1/latest — Get the current RBNZ_OCR and its effective date.
/api/v1/historical — Fetch the OCR level on a particular date (resolves to the last in-month observation).
/api/v1/timeseries — Daily-resolved OCR series for backtesting and charts.
/api/v1/fluctuation — Start/end, change, change_pct, high, and low for a range.
/api/v1/ohlc — Monthly/weekly/quarterly OHLC bars derived from daily data.
/api/v1/convert — Compare loan interest costs using OCR versus another benchmark.

FAQ

How often is RBNZ_OCR updated?
RBNZ_OCR is a monthly series in this API. Use the dates map in /latest and the last in-month observation rule in /historical to interpret the effective date.

What units does the API return?
Rates are numeric percentages. Divide by 100 to convert to decimal form before computing interest or amortization schedules.

How do I compute a spread over RBNZ_OCR?
Fetch /latest for RBNZ_OCR, get your priced loan rate L, and compute S = L − RBNZ_OCR in percentage points. Multiply S by 100 for basis points.

How should I cache these endpoints?
Cache /symbols and history endpoints longer. Cache /latest with a short TTL and invalidate on decision days or when you detect a newer dates entry for RBNZ_OCR.

What errors should I handle?
Expect 401/403 for auth/plan issues, 404 for missing data in a range, 422 for invalid parameters (e.g., bad date format), and 429 for quota. Use the provided headers to retry appropriately.

Build your RBNZ OCR integration now: read the docs at interestratesapi.com, explore the Interest Rates API MCP, and Register to get your API key. You can also Register for Interest Rates API or Get started with Interest Rates API and ship your RBNZ_OCR workflow into production.

RBNZ_OCR: what it is, how it’s expressed, and why it matters

Working with authentication, dates, and caching

Endpoint 1: /symbols — discover available rate symbols

cURL

JSON response example

Python (requests)

JavaScript (fetch)

PHP

Endpoint 2: /latest — latest value for RBNZ_OCR

cURL

JSON response example

Official sample: /latest response shape

Python (requests)

JavaScript (fetch)

PHP

Endpoint 3: /historical — RBNZ_OCR on a specific date

cURL

JSON response example

Python (requests)

JavaScript (fetch)

PHP

Endpoint 4: /timeseries — daily-resolved RBNZ_OCR between two dates

cURL

JSON response example

Python (requests)

JavaScript (fetch)

PHP

Endpoint 5: /fluctuation — changes, highs, and lows for RBNZ_OCR

cURL

JSON response example

Python (requests)

JavaScript (fetch)

PHP

Endpoint 6: /ohlc — monthly or weekly OHLC for RBNZ_OCR

cURL

JSON response example

Python (requests)

JavaScript (fetch)

PHP

Endpoint 7: /convert — compare total loan interest costs using RBNZ_OCR

cURL

JSON response example

Python (requests)

JavaScript (fetch)

PHP

Practical implementation details for RBNZ_OCR

Units and effective dates

Business days and frequency

Caching and invalidation

Error handling

Computing spreads and payments from RBNZ_OCR

Use cases you can ship quickly

All endpoints at a glance with RBNZ_OCR

FAQ

Ready to get started?

Related posts