How do I get NZ Post deliverable addresses?

Question

How do I get NZ Post deliverable addresses?

Accepted Answer

It is possible to limit your search to postal addresses only, if your objective is to collect only addresses that NZ Post deliver to.

This is achieved by passing delivered:1 to the Address Autocomplete API or the widget constructor. This parameter is accessible from the JavaScript widget using the address_params option.

Here's an example of how to setup the widget to only return postal addresses:
https://jsfiddle.net/abletech/qLa6nq39/

This page has a description of all of the attributes that the Address Metadata API returns:
Address Metadata API Response

Explanation:

AddressFinder returns both a postal and physical address where both exist. A postal address means that the data comes from NZ Post, and NZ Post deliver to that address. However, there are many addresses that NZ Post do not deliver to (they are physical, but not postal addresses).

Example:

Below is an example where there is both a postal and physical address.

We return both addresses in the search results, but both search results point to the one address record below.

"mailtown" is the correct postal town/city. In this case the address is physically in Thornbury, but the NZ Post delivery is RD3 from Riverton (Mailtown).

Mailtown will be blank if the address searched for and select is not delivered to by NZ Post.

Key	Value
`pxid`	2-.B.37.1.2.4
`number`	19
`container_only`	false
`x`	168.0970854524
`y`	-46.2897189093679
`postcode`	9883
`rd_number`	3
`a`	19 Broderick Street, Thornbury 9883
`postal`	19 Broderick Street, RD 3, Riverton 9883
`mailtown`	Riverton
`ta`	Southland District
`street_type`	street
`city`	Thornbury
`suburb`	Thornbury
`region`	Southland Region
`street`	Broderick Street
`postal_line_1`	19 Broderick Street
`postal_line_2`	RD 3
`postal_line_3`	Riverton 9883
`meshblock`	3185100
`dpid`	2769290

See also FAQ: What’s the difference between ‘city’ and ‘mailtown’?

In summary, if you want to limit your search to postal addresses only, in order to make deliveries by NZ Post, then set the Address Autocomplete API parameter "delivered":1. From the javascript widget this parameter is accessible using the "address_params" option.