✨ https://www.ratesapi.nz ✨
A free JSON API for New Zealand mortgage, personal loan, car loan, and credit card rates, with collection scheduled every four hours.
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.
# 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"| Category | List | By ID | Time series |
|---|---|---|---|
| Mortgages | /api/v1/mortgage-rates |
/api/v1/mortgage-rates/{institutionId} |
/api/v1/mortgage-rates/time-series |
| Personal loans | /api/v1/personal-loan-rates |
/api/v1/personal-loan-rates/{institutionId} |
/api/v1/personal-loan-rates/time-series |
| Car loans | /api/v1/car-loan-rates |
/api/v1/car-loan-rates/{institutionId} |
/api/v1/car-loan-rates/time-series |
| Credit cards | /api/v1/credit-card-rates |
/api/v1/credit-card-rates/{issuerId} |
/api/v1/credit-card-rates/time-series |
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.
| Path | Purpose |
|---|---|
/api/v1/health |
Health check, with the last change and last complete successful collection of each dataset |
/openapi |
Interactive API reference (Scalar) |
/openapi.json |
OpenAPI document for SDK and tool generators (also at /openapi/json) |
POST /api/v1/mcp |
Model Context Protocol endpoint with read-only tools for each category |
/llms.txt |
Plain-text index of the documentation pages, with when-to-use guidance for agents |
/about, /contact, /privacy |
Who runs Rates API, how to reach the project, and the privacy notice |
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.
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.
| Component | Path | Runs on |
|---|---|---|
| API | apps/api |
Cloudflare Workers (Elysia) serving /api/* and /openapi* |
| Docs | apps/docs |
Cloudflare Workers (Next.js + Fumadocs via OpenNext), serving /docs* |
| Landing page | apps/web |
Cloudflare Workers (TanStack Start), serving everything else on www.ratesapi.nz and redirecting the apex to www |
| Database | apps/api/schema.sql |
Cloudflare D1, holding the newest datasets and snapshots |
| Scrapers | apps/api/bin |
GitHub Actions, checks scheduled every four hours (Cheerio) |
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.
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 devbun run dev starts all three apps. The API creates a local D1 database and seeds it with a small sample dataset.
| App | URL |
|---|---|
api |
http://localhost:8787 |
docs |
http://localhost:3000/docs |
web |
http://127.0.0.1:3002 |
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.
bun run check # Oxlint, Oxfmt, type checks, and Bun tests
bun run build # Builds each app the same way CI doesRun bun run check before you open a pull request.
bun run deployThis 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.
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.
MIT. See LICENSE.