Overview
Rates API is an AI-ready JSON API for current and historical New Zealand lending rates.
Rates API provides current and historical lending rates from New Zealand financial institutions through stable JSON endpoints, OpenAPI metadata, a Model Context Protocol endpoint, and an llms.txt documentation feed.
Use it to power comparison tools, affordability calculators, market dashboards, research workflows, and AI agents without scraping lender websites yourself.
The API is free to use, does not require authentication, and is updated hourly when the scheduled data collection workflow runs successfully.
Start Here
| Goal | Go to |
|---|---|
| Make your first request | Quickstart |
| Connect an AI agent or assistant | AI Integration |
| Understand identifiers, date filters, and errors | Core Concepts |
| Browse endpoints by product type | API Reference |
| Try requests in the browser | OpenAPI |
| Run or deploy the project yourself | Open Source |
Quick Example
curl https://ratesapi.nz/api/v1/mortgage-ratesThe response groups products by institution and includes stable identifiers that can be reused in detail and time-series requests.
AI-Ready by Design
Rates API is designed to be easy for AI products to discover, call, and reason about.
| Capability | Why it matters for AI systems |
|---|---|
| Model Context Protocol | POST /api/v1/mcp exposes rate lookup tools for agents that support MCP. |
| OpenAPI | /openapi/json gives agent builders and SDK generators a machine-readable contract. |
llms.txt | /llms.txt gives assistants a compact, plain-text index of the documentation. |
| Stable JSON | Predictable response and error shapes make tool results easier to validate. |
| Stable identifiers | Institution, issuer, and product IDs can be reused across prompts, tools, and workflows. |
| No API key | Agents can test public market data without a secrets-management setup. |
Data Coverage
| Category | List Endpoint | Get By ID | Time Series |
|---|---|---|---|
| Mortgage Rates | GET /api/v1/mortgage-rates | GET /api/v1/mortgage-rates/{institutionId} | GET /api/v1/mortgage-rates/time-series |
| Personal Loan Rates | GET /api/v1/personal-loan-rates | GET /api/v1/personal-loan-rates/{institutionId} | GET /api/v1/personal-loan-rates/time-series |
| Car Loan Rates | GET /api/v1/car-loan-rates | GET /api/v1/car-loan-rates/{institutionId} | GET /api/v1/car-loan-rates/time-series |
| Credit Card Rates | GET /api/v1/credit-card-rates | GET /api/v1/credit-card-rates/{issuerId} | GET /api/v1/credit-card-rates/time-series |
Common Use Cases
- Product comparison experiences across mortgages, personal loans, car loans, and credit cards
- Affordability calculators that need current lending rates
- Market monitoring dashboards for New Zealand lending products
- Historical analysis and charts using daily time-series snapshots
- Research projects that need consistent lender and product identifiers
- AI assistants that answer rate questions with live, source-backed data
- Agent workflows that compare lenders, detect rate changes, or enrich customer journeys
Operational Notes
- Base URL:
https://ratesapi.nz - Local API URL:
http://localhost:8787 - Auth: no API key required
- Format: JSON
- Documentation: Scalar OpenAPI UI at
/openapi - OpenAPI JSON:
/openapi/json - MCP endpoint:
POST /api/v1/mcp - LLM documentation feed:
/llms.txt - Source: github.com/simonbetton/ratesapi.nz