Calculate.co.nz Service API

openapi: 3.2.0
info:
  title: Calculate.co.nz Service API
  description: 'Free access to New Zealand tax, KiwiSaver, mortgage and property calculations.

    No sign-up needed to start.


    **Anonymous calls are limited to 120 an hour per IP.** That is far more than

    a person or an assistant session will ever use, and less than a product needs.

    If you are building something, request a free key and send it as `X-API-Key`:

    it raises the limit to 5000 an hour and means we can tell you before anything

    changes. Keys are issued by hand, usually same day. Ask at contact@calculate.co.nz


    Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and

    `X-RateLimit-Reset`. Over the limit returns `429` with `Retry-After`.


    **Every calculation is a port of the page of the same name on

    calculate.co.nz.** The website is the source of

    truth: rates come from `paye-data.php`, the same file the site''s own calculators

    read, and the test suite fails if the two ever disagree. Rates are reviewed

    twice monthly against IRD, RBNZ and Stats NZ.


    **Fourteen calculators have their own endpoint.** For anything else, call

    `POST /v1/find-calculator` with a plain-language question and it will return the

    right page from the whole site.


    **`GET /v1/rates` publishes the underlying New Zealand reference data**: tax

    brackets, the ACC earner levy and its cap, student loan thresholds, KiwiSaver

    settings and benefit rates. Each figure carries the date it took effect, where

    it was read from, and when it was last checked against the issuing body, with

    `verified_on` left null rather than guessed where that check has not been done.

    Filter by `review_cycle=annual-1-april` to get everything that moves on 1 April.


    These are the same figures the calculators consume, and an automated harness

    drives the live pages on the website in a browser and compares their answers to

    this API. A wrong rate breaks a visible page rather than sitting unnoticed in a

    data feed.


    **Every response carries a `disclaimer`, and it is not boilerplate to strip

    out.** These are estimates under stated assumptions, not financial, tax or legal

    advice. `POST /v1/paye` also returns an `assumptions` block naming the tax year

    and every rate used, so a stored result can be audited later against the rules

    that applied on the day.


    The same calculators are available to AI assistants over the Model Context

    Protocol at `https://mcp.calculate.co.nz/mcp`.


    Questions, or something wrong: contact@calculate.co.nz'
  termsOfService: https://www.calculate.co.nz/terms.php
  contact:
    name: Calculate.co.nz
    url: https://www.calculate.co.nz/contact.php
    email: contact@calculate.co.nz
  version: 1.16.0
servers:
- url: https://api.calculate.co.nz
  description: Production
tags:
- name: Service
  description: Liveness and the state of the search index.
paths:
  /:
    get:
      tags:
      - Service
      summary: Index of every endpoint
      description: 'Everything this API offers, in one response.


        The root used to return 404, so anyone who typed the bare hostname was told

        the API did not exist. This lists the endpoints, points at the human

        documentation, and names the MCP endpoint for assistants.'
      operationId: root__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /health:
    get:
      tags:
      - Service
      summary: Liveness check
      description: 'Confirm the service is up and see which NZ tax year it is calculating for.


        Deliberately cheap and dependency-free: it does not touch the page index, so

        it stays truthful about this service rather than about the website.'
      operationId: health_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /v1/index-status:
    get:
      tags:
      - Service
      summary: State of the search index
      description: 'Whether the page index behind /v1/find-calculator is loaded and how old.


        Separate from /health on purpose: the index is a soft dependency, and the

        API is healthy without it. Folding it into /health would let a website

        outage look like an API outage.'
      operationId: index_health_v1_index_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Optional. Identifies your calls and raises your hourly limit from 120 to 5000 requests. Request one from contact@calculate.co.nz
      in: header
      name: X-API-Key