Documentation

Two endpoints, one header. There is no SDK to install.

Authentication

Send your key in the X-API-Key header on every request. Keys are created in your dashboard.

curl -H "X-API-Key: nzak_live_…" "https://addressfinder.straker.co.nz/api/address/suggestions?q=queen+st"

Call this from your server, not from browser JavaScript. A key shipped to the browser is readable by anyone who opens developer tools, and their usage lands on your quota.

GET /api/address/suggestions

Type-ahead search. Call it on each keystroke once the customer has typed three characters.

Parameter	Required	Description
`q`	yes	What the customer has typed. 3–200 characters.
`limit`	no	How many suggestions to return. 1–25, default 8.
`country`	no	Only `nz` is supported. Anything else is a 400.

[
  { "id": "2146877", "address": "12 Wainui Road, Judea, Tauranga" },
  { "id": "2146878", "address": "12 Wainui Road Extension, Judea, Tauranga" }
]

GET /api/address/metadata

The full record for an id returned by a suggestion.

{
  "address":   "12 Wainui Road, Judea, Tauranga",
  "suburb":    "Judea",
  "city":      "Tauranga",
  "postcode":  "",
  "state":     null,
  "region":    "Tauranga City",
  "latitude":  -37.70,
  "longitude": 176.15
}

postcode is always empty and state always null. The LINZ layer carries neither; the fields exist so a consumer written against AddressFinder's shape can switch over by changing a base URL.

Errors

Status	Meaning	What to do
`400`	Bad parameter — `q` too short, unsupported country.	Fix the request.
`401`	Key missing, wrong, or revoked.	Check the header and the dashboard.
`402`	The key is fine; the plan has lapsed.	Renew at /billing.
`403`	Account suspended.	Email support@straker.co.nz.
`404`	No address with that id.	Re-run the suggestion.
`429`	Monthly quota used up.	Wait for the 1st, or move up a plan.
`503`	The address index is being rebuilt.	Retry shortly.

A distinct 402 rather than a blanket 401 is deliberate: an unpaid invoice and a broken key need completely different fixes, and one status code for both sends you hunting through your key handling for a billing problem.

Response headers

Header	Value
`X-Quota-Limit`	Your plan's monthly allowance.
`X-Quota-Remaining`	What is left of it. Worth alerting on.
`X-Data-Attribution`	The LINZ credit you are required to display.
`X-Data-Source`	Link to the LINZ layer the index was built from.

Attribution is not optional

The data is licensed CC BY 4.0, which requires the source to be credited wherever the addresses appear. Show “Sourced from LINZ. CC BY 4.0.” alongside your address field or in your page footer. It is served on every response so nobody has to hardcode it.

Machine-readable spec

OpenAPI at /openapi.json, with an interactive browser at /docs. Service health, dataset row count and build date at /health, no key required.