Calculate.co.nz Discovery API

openapi: 3.2.0
info:
  title: Calculate.co.nz Discovery 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: Discovery
  description: Find the right page across all 2,377 calculators, 407 guides and 49 datasets. Only a handful of calculators have their own endpoint; everything else is reachable here as a URL.
paths:
  /v1/find-calculator:
    post:
      tags:
      - Discovery
      summary: Find the right calculator, guide or dataset
      description: 'Search every Calculate.co.nz calculator, guide and dataset by topic.


        Start here when there is no dedicated endpoint for what you need, which is

        almost always: six calculators have their own endpoint and the site has

        2,377. Ask in plain language, the way someone would say it out loud, rather

        than in keywords. "how much tax do I pay on my salary" works better than

        "tax", because the ranking reads the whole phrase.


        NZ-specific pages outrank generic ones on the same topic. Filter with

        `types` when you only want, say, guides. `score` is comparable within one

        response, not between different queries.


        The index is fetched from the website and cached, so the first call after a

        restart is slower. `GET /v1/index-status` shows whether it is loaded.'
      operationId: find_calculator_v1_find_calculator_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindCalculatorRequest'
        required: true
      responses:
        '200':
          description: Best matches, highest score first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindCalculatorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
components:
  schemas:
    FindCalculatorHit:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Page title.
        url:
          type: string
          title: Url
          description: Full URL on calculate.co.nz.
        type:
          type: string
          title: Type
          description: One of calculator, tool, guide or dataset.
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
          description: Section of the site the page sits in.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: One line on what the page does.
        score:
          type: number
          title: Score
          description: Relevance, higher is better. Comparable within one response only, not across different queries.
      type: object
      required:
      - url
      - type
      - score
      title: FindCalculatorHit
    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
    FindCalculatorResponse:
      properties:
        query:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
          description: The query as searched.
        count:
          type: integer
          title: Count
          description: Number of results returned, at most `limit`.
          default: 0
        results:
          items:
            $ref: '#/components/schemas/FindCalculatorHit'
          type: array
          title: Results
          description: Matches, best first.
          default: []
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Where the page index was loaded from.
        index_pages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Index Pages
          description: Pages in the index at the time of the search.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Set only when the index could not be loaded. Results will be empty.
      type: object
      title: FindCalculatorResponse
    FindCalculatorRequest:
      properties:
        query:
          type: string
          maxLength: 200
          minLength: 1
          title: Query
          description: What to work out, in plain language.
        limit:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Limit
          description: Number of results, 1 to 20.
          default: 5
        types:
          anyOf:
          - items:
              type: string
              enum:
              - calculator
              - tool
              - guide
              - dataset
            type: array
          - type: 'null'
          title: Types
          description: Restrict to these page types. Omit for all types.
      type: object
      required:
      - query
      title: FindCalculatorRequest
      example:
        limit: 5
        query: how much tax do I pay on my salary
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  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