Rates API collects the interest rates of New Zealand financial institutions directly from institution websites on a four-hour schedule. It serves the latest successfully collected rates and a daily snapshot history. The scheduler targets minute 17 every four hours (UTC), but GitHub may delay or skip runs; the schedule is not a freshness guarantee. You don't need an API key, and every response is JSON. AI agents can use the data through an MCP endpoint, the OpenAPI document, or llms.txt.
[!NOTE] The data can be wrong. Check rates with the financial institution before you make a decision.
Usage
# Newest mortgage rates from all institutions
curl https://www.ratesapi.nz/api/v1/mortgage-rates
# Fixed 12-month rates only
curl "https://www.ratesapi.nz/api/v1/mortgage-rates?termInMonths=12"
# One institution
curl https://www.ratesapi.nz/api/v1/mortgage-rates/institution:anz
# Snapshots in a date range
curl "https://www.ratesapi.nz/api/v1/mortgage-rates/time-series?startDate=2026-04-01&endDate=2026-04-30&institutionId=institution:anz"
Endpoints
The API stores at most one snapshot per dataset per UTC day, and only on days when the data changed. Each time-series response has an availableDates field that lists the dates with data.
Every error is JSON with code, error (a stable code), message, hint, and documentationUrl, including for API paths that don't exist. The landing page answers Accept: text/markdown with Markdown (and Vary: Accept) on every page, including its 404s.
Read the documentation for IDs, date filters, errors, and the MCP protocol details.
Direct-source migration
The collectors request only institution websites, their public feeds and current linked disclosures. The reviewed public-rate catalogue has 112 adapters and no unresolved coverage entries. Verified institutions can update even when another source fails, including within the same category. Failed or unreconciled institutions keep their stored records; stored institutions are removed from current rates only when the register records a reviewed exclusion. The run reports failures after publishing successful updates. See the coverage register and live audit for scope, exclusions, freshness rules and verification.
Run bun run --filter api sources:audit for a read-only live report. Browser sources require cd apps/api && bunx playwright install chromium; bun run sources:browser runs the bank access audit. Optional Browser Use Cloud configuration and the GitHub Actions workflow are documented in the register below. See the institution register and migration status for verified adapters, blocked sources, aliases, and the remaining work. Existing historical snapshots keep their original provenance.
How it works
GitHub Actions also run CI, deploy on every push to main, and check the production API every 15 minutes. A failed check opens an issue.
Development
You need Bun and Node.js 24 for the rate collectors. A Cloudflare account is only needed for remote D1 access or deployment.
git clone https://github.com/simonbetton/ratesapi.nz.git
cd ratesapi.nz
bun i
bun run dev
bun run dev starts all three apps. The API creates a local D1 database and seeds it with a small sample dataset.
To run one app, use bun run --filter <app> dev.
The source audit is read-only. To collect verified institution updates into your local database, run the scrapers:
bun run --filter api scrape:local
[!WARNING]
bun run --filter api dev:remoteconnects to the production D1 database. The API endpoints only read data, but don't run any script that writes while you use this connection.
Checks
bun run check # Oxlint, Oxfmt, type checks, and Bun tests
bun run build # Builds each app the same way CI does
Run bun run check before you open a pull request.
Deployment
bun run deploy
This deploys the API Worker (ratesapi-nz), the docs Worker (ratesapi-nz-docs), and the landing page Worker (ratesapi-nz-web). For D1 setup, route configuration, and the GitHub Actions secrets, read the deployment guide.
Contributing
Issues and pull requests are welcome. When you change an endpoint, update its route, schema, OpenAPI description, and contract test together. Write the docs pages and OpenAPI descriptions in ASD-STE100 Simplified Technical English. The open source guide covers the repository layout.
License
MIT. See LICENSE.
