---
title: "Find the right calculator, guide or dataset"
method: POST
path: "/v1/find-calculator"
tags: ["Discovery"]
---

# Find the right calculator, guide or dataset

`POST /v1/find-calculator`

## Request

- Base URL: `https://api.calculate.co.nz`
- URL: `https://api.calculate.co.nz/v1/find-calculator`
- Auth: API key in header `X-API-Key`

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.

## Request body

- FindCalculatorRequest
  - `query` string, required: What to work out, in plain language.
  - `limit` integer: Number of results, 1 to 20.
  - `types` string[], nullable: Restrict to these page types. Omit for all types.

## Response `200`

Best matches, highest score first.

- FindCalculatorResponse
  - `query` string, nullable: The query as searched.
  - `count` integer: Number of results returned, at most `limit`.
  - `results` FindCalculatorHit[]: Matches, best first.
    - `title` string, nullable: Page title.
    - `url` string, required: Full URL on calculate.co.nz.
    - `type` string, required: One of calculator, tool, guide or dataset.
    - `category` string, nullable: Section of the site the page sits in.
    - `description` string, nullable: One line on what the page does.
    - `score` number, required: Relevance, higher is better. Comparable within one response only, not across different queries.
  - `source` string, nullable: Where the page index was loaded from.
  - `index_pages` integer, nullable: Pages in the index at the time of the search.
  - `error` string, nullable: Set only when the index could not be loaded. Results will be empty.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/calculate/apis/calculate-co-nz-api.md) · [All operations](https://skmtc.dev/calculate/apis/calculate-co-nz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calculate/apis/calculate-co-nz-api/revisions/aa59a8e76614?raw)