Our postcodes are unofficial and wrong for roughly 5 addresses in 100. The Postcode Correction API reports that an address has the wrong postcode, so it can be put right for everyone. You can also report one from the Postcodes tab of your console.

Only report what you or your user know first-hand — a person correcting their own address, or your staff from returned mail. Never copy postcodes from NZ Post products or its postcode finder. Sending one accepts our postcode correction terms.

Report a postcode

Request

POST https://api.getaddress.nz/postcode-correction/{id}?api-key={your-api-key}  

{id} is the address's id — the LINZ address_id, as an Autocomplete suggestion's id or Get returns it. One address per request.

Request Body

{
    "postcode": "{the correct four-digit postcode}",
    "source": "{user or customer}",
    "note": "{optional: how you know}"
}

Example

Reporting that 808A Selwyn Road, Rolleston (postcode source suburb (majority)) should have a different postcode.

Request

POST https://api.getaddress.nz/postcode-correction/2453669?api-key={your-api-key}  

Request Body

{
    "postcode": "{the correct postcode}",
    "source": "customer",
    "note": "returned mail"
}

Response (202 Accepted)

{
    "id": "{the report's id}",
    "address_id": "2453669",
    "postcode": "{the correct postcode}",
    "previous_postcode": "7614",
    "source": "customer",
    "status": "pending",
    "created": "{date and time reported}"
}

Responses

How reports are applied

• Your account has one report per address. A later report on the same address replaces your earlier one.
• Reports are applied at a weekly run, not straight away. Until then the address keeps its postcode and the report is pending.
• When one account has reported an address, its report is applied.
• When accounts disagree, a postcode that two or more accounts agree on wins; otherwise the reports wait for review.
• When two or more accounts' corrections on one road agree, the postcode spreads to the whole road.
• An applied correction shows in the address's postcode_source as corrected, or corrected (road) where it spread to the road.

List your reports

Request

GET https://api.getaddress.nz/postcode-corrections?api-key={your-api-key}&top=50  

Returns your account's reports, newest first, each in the shape above. top is 50 by default, at most 200. This takes your API key only, not a domain token.

{
    "corrections":
    [
        { … },
        …
    ]
}

From the autocomplete widget

The JavaScript Autocomplete widget can send reports for you. Set report_postcode_edits: true (it is off by default) and, when a visitor changes the postcode the widget filled in, the widget reports the new one. It needs the postcode field set in output_fields, reports at most once per address picked, and never interrupts the page if a report fails.

Review (staff only)

Reports that disagree wait for our reviewers. These routes take the admin key of a reviewer's subscription; for anyone else they answer 403.

GET https://api.getaddress.nz/postcode-corrections/review?api-key={your-admin-key}  

Lists addresses with reports waiting, disputed first: the address, its postcode now, and each reported postcode with the accounts behind it.

POST https://api.getaddress.nz/postcode-corrections/review/{id}?api-key={your-admin-key}  

{
    "action": "{accept or reject}",
    "postcode": "{for accept: the reported postcode that wins}"
}

accept rejects the address's other reports; the postcode is applied at the next weekly run. reject rejects them all and the address keeps its postcode; one already applied goes back at the next weekly run.

POST https://api.getaddress.nz/postcode-corrections/review/accounts/{account}/pause?api-key={your-admin-key}  

Pauses an account whose reports look copied: every report it has made is rejected, and new ones get 403. Optional body: { "reason": "…" }. A postcode already applied goes back to its usual one at the next weekly run.

POST https://api.getaddress.nz/postcode-corrections/review/accounts/{account}/resume?api-key={your-admin-key}  

Resumes a paused account: its new reports are taken again. Its past reports stay rejected. 404 when the account is not paused. The review list's paused_accounts names them.

Neighbours disagree

Each week we also check every address written that week against its 10 nearest addresses. One whose postcode differs from most of theirs is listed for review and is lower confidence until a reviewer decides. Nothing is changed automatically.

GET https://api.getaddress.nz/postcode-corrections/review/neighbours?api-key={your-admin-key}  

Lists them, clearest first: the address, its postcode, the postcode most of its neighbours have, and how many of them.

POST https://api.getaddress.nz/postcode-corrections/review/neighbours/{id}?api-key={your-admin-key}  

{
    "action": "{accept or dismiss}",
    "postcode": "{for accept: the postcode it should have}"
}

accept saves the postcode as a correction in your name, applied at the next weekly run. dismiss keeps the postcode it has, and the same finding is not raised again.