Calculate.co.nz Reference data API

openapi: 3.2.0
info:
  title: Calculate.co.nz Reference data 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: Reference data
  description: 'Current, dated, sourced New Zealand statutory rates: tax brackets, ACC, student loan, KiwiSaver, benefits. Maintained on a review calendar tied to when each figure actually changes, and consumed by the calculators above, so a wrong rate breaks a page rather than sitting unnoticed in a feed.'
paths:
  /v1/rates:
    get:
      tags:
      - Reference data
      summary: Current New Zealand statutory rates, dated and sourced
      description: 'Every New Zealand statutory rate this site maintains, with its provenance.


        Tax brackets, the ACC earner levy and its cap, student loan rate and

        threshold, KiwiSaver settings, benefit rates and more. Each carries the date

        it took effect, where it was read from, and when it was last checked against

        the issuing body.


        **`verified_on` can be null, and that is deliberate.** A figure recorded but

        not yet checked against its issuing body says so rather than looking the

        same as one that was. Hiding the difference would make the whole dataset

        worth less.


        Filter with `q` over the id and label, or with `review_cycle` to get

        everything that changes at the same time. `review_cycle=annual-1-april`

        returns the figures that move on 1 April, which is the query a payroll or

        compliance team actually has.


        These are the same figures the calculators on calculate.co.nz consume, and

        an automated harness drives those live pages 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, which is not a claim most rate data can make.'
      operationId: rates_v1_rates_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Q
      - name: review_cycle
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Review Cycle
      responses:
        '200':
          description: The rates, each with its effective date, source and review cycle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/rates/{rate_id}:
    get:
      tags:
      - Reference data
      summary: One rate by id
      description: 'A single rate by its stable id, for example `acc-earner-levy`.


        Ids do not change when a value does, so they are safe to store and to key

        on. Call `GET /v1/rates` to see them all.'
      operationId: rate_by_id_v1_rates__rate_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: rate_id
        in: path
        required: true
        schema:
          type: string
          title: Rate Id
      responses:
        '200':
          description: The rate, its effective date, source and review cycle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RateRecord:
      properties:
        id:
          type: string
          title: Id
          description: Stable identifier. Safe to store and to key on.
        label:
          type: string
          title: Label
          description: What the figure is, in words.
        value:
          type: string
          title: Value
          description: The current value, as published. A string so 1.75 and 0.0175 are never confused by a float.
        effective_from:
          anyOf:
          - type: string
          - type: 'null'
          title: Effective From
          description: ISO date the value took effect, where the source states one.
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Where it was read from. A URL for anything verified against an issuing body.
        verified_on:
          anyOf:
          - type: string
          - type: 'null'
          title: Verified On
          description: ISO date this figure was last checked against the issuing body. NULL means recorded but not yet verified, and is deliberately visible rather than hidden.
        review_cycle:
          type: string
          title: Review Cycle
          description: 'When it next changes: annual-1-april, budget-may, periodic, or on-legislative-change. This is the field to filter on if you want to know what to re-check and when.'
        previous_values:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Previous Values
          description: Prior values, most recent first. Undated for now.
        history_note:
          anyOf:
          - type: string
          - type: 'null'
          title: History Note
          description: The limits of previous_values.
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
          description: Anything a consumer needs to know about this figure.
      type: object
      required:
      - id
      - label
      - value
      - review_cycle
      title: RateRecord
    RatesResponse:
      properties:
        dataset:
          type: string
          title: Dataset
          description: Name of the dataset.
        publisher:
          type: string
          title: Publisher
          description: Who maintains it.
        count:
          type: integer
          title: Count
          description: Rates returned by this request.
        total:
          type: integer
          title: Total
          description: Rates in the dataset overall.
        verified_count:
          type: integer
          title: Verified Count
          description: How many carry a verification date.
        register_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Register Updated
          description: When the register was last touched.
        correctness_note:
          type: string
          title: Correctness Note
          description: How these figures are checked.
        rates:
          items:
            $ref: '#/components/schemas/RateRecord'
          type: array
          title: Rates
          description: The rates themselves.
      type: object
      required:
      - dataset
      - publisher
      - count
      - total
      - verified_count
      - correctness_note
      - rates
      title: RatesResponse
  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