The Address Metadata API is used to collect the metadata associated with an address selected from the Address Autocomplete API or Bounding Box API.
Build the request URL
Use the form below to build your request URL from the parameters. A URL string will be generated from these parameters and sent to the API in order to provide insight into how the API works and the responses it returns.
* Parameters marked with an asterisk are mandatory for this API call.
Request URL
/* Click the button above to see a real API response here */
{
"success": true
}
Response Specification
The API response will contain all the addresses and associated IDs (pxid) in the format requested in the API request.
| Field Name | Type | Description | Example |
|---|---|---|---|
a * | String | Canonical address as supplied by Land Information New Zealand or NZ Post. | Unit 2, 1703A State Highway 1, Warkworth 0983 |
postal | String | Associated postal address when supplied by NZ Post. Field will be omitted if this address is not delivered to by NZ Post. FAQ: postal address vs 'a' address. | Unit 2, 1703A State Highway 1, RD 3, Warkworth 0983 |
building_name | String | Holds the building or property name. | Miban Building |
unit_type | String | Describes the category of a sub-dwelling. | Flat |
unit_identifier | String | Identifies a specific sub dwelling. Can be alpha, number or a combination. | 1 |
floor | String | The level number and level type in a multi-story building. | Level 19 |
number | String | The street number of the address. Also populated with the box number for PO Box type addresses. | 1703 |
alpha | String | Holds the alpha component of a street number. In the address 1B High Street, B is the alpha. | B |
street | String | Holds the full name of the street. Note: The street attribute also includes the Street Type. | State Highway 1 |
street_name | String | Holds the name of the street. | Queen |
street_type | String | The type of street. | Avenue |
suburb | String | The suburb or locality of the address as assigned by Land Information New Zealand. | Warkworth |
city * | String | The city, town or locality name as assigned by Land Information New Zealand. | Warkworth |
box_type | String | The type of PO Box/CMB/Private Bag/Counter Delivery. | PO Box |
lobby_name | String | The name of the NZ Post outlet or Agency outlet where the PO Box, Private Bag or Counter Delivery is located. | Fendalton |
rd_number | String | The rural delivery number assigned by NZ Post to a rural address. | 4 |
post_suburb | String | Name of the suburb when supplied by NZ Post. | Manukau |
mailtown | String | Name of the town/city when supplied by NZ Post. | Warkworth |
postcode * | String | Holds the four digit postcode. | 0983 |
rural * | Boolean | An indicator to help determine if this address is located in a rural setting. Note: Different courier companies have different rural/urban boundaries so this determination should be confirmed by your delivery agent. | true |
pxid * | String | Unique address identifier. | 3-.1.1d.2.42.1T.2 |
dpid | String | A unique reference number assigned to each delivery address by NZ Post. | 2668726 |
aims_address_id | String | The unique identifier from Land Information New Zealand (LINZ). | 1518959 |
aims_road_section_id | String | The unique road section identifier from Land Information New Zealand (LINZ). | 323309 |
x * | String | Longitude coordinate (in WGS84 format). | 174.643199 |
y * | String | Latitude coordinate (in WGS84 format). | -36.426956 |
meshblock * | String | The meshblock identifier for the requested census dataset (see census parameter). If not specified, the meshblock returned is from the 2013 census. The default data source will change to the 2018 census 3 months after the 2018 census results are released. | 146004 |
sa1_id | String | Statistical area 1 (2018 census only) | 7000001 |
sa2_id | String | Statistical area 2 ID (2018 census only) | 100200 |
sa2 | String | Statistical area 2 name (2018 census only) | Rangaunu Harbour |
ur_id | String | Urban rural ID (2018 census only) | 1002 |
ur | String | Urban rural name (2018 census only) | Kaimaumau |
iur_id | String | Urban rural indicator ID (2018 census only) | 21 |
iur | String | Urban rural indicator name (2018 census only) | Rural settlement |
cb_id | String | Community Board ID (2018 census only) | 00101 |
cb | String | Community Board name (2018 census only) | Te Hiku Community |
con_id | String | Constituency ID (2018 census only) | 0101 |
con | String | Constituency name (2018 census only) | Te Hiku Constituency |
maoricon_id | String | Maori Constituency ID (2018 census only) | 0402 |
maoricon | String | Maori Constituency name (2018 census only) | Okurei Maori Constituency |
region_id | String | Region ID (2018 census only) | 04 |
region * | String | The Regional Authority in which this address exists. Note: Regional Authorities are the top tier of local government in New Zealand. | Auckland Region |
ta_id | String | Territorial Authority ID (2018 census only) | 060 |
ta * | String | The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. | Auckland |
tasub_id | String | Territorial Authority Subdivision ID (2018 census only) | 06019 |
tasub | String | Territorial Authority Subdivision name (2018 census only) | Akaroa Subdivision |
ward_id | String | Ward ID (2018 census only) | 06016 |
ward | String | Ward name (2018 census only) | Banks Peninsula Ward |
landwater_id | String | Land/Water ID (2018 census only) | 22 |
landwater | String | Land/Water description (2018 census only) | Inlet |
address_line_1 * | String | First line of the non-suburb/city/postcode portion of the address | Unit 2 |
address_line_2 | String | Second line of the non-suburb/city/postcode portion of the address. | 1703A State Highway 1 |
success * | Boolean | Indicates if the request was successful or not. | true |
* Attributes marked with an asterisk will always be present in a successful API response.
Errors
Below are the possible errors that can be returned by the API.
| Code | Error | Cause | Resolution |
|---|---|---|---|
1000 | Validation error | Returned when one of the supplied parameters is missing or incorrect. The response will contain a message attribute which explains the cause of the validation error. An example JSON response is shown below for a request which failed to include the q parameter. { | Check that the supplied parameters contain valid values, and that the mandatory parameters have been included. |
1001 | Account key not found | Returned when the key included in your API call cannot be found in our database. This will normally happen when you make a copy ’n paste error. | Compare the key included in your API call with the key listed in the AddressFinder Portal overview page. Also confirm there are no additional spaces or characters in your API call. |
1002 | Account key is missing | Returned when you fail to send through your key with each request. The key is a mandatory parameter. | Check that you are using the correct parameter name key. |
1003 | Invalid domain | Returned when you embed AddressFinder on a website that differs from the domain that you specified in the AddressFinder Portal. | The AddressFinder Portal records the whitelist of allowed domains for your account. Login to the AddressFinder Portal and add the domain of this website to your account. |
1004 | Account secret missing | Returned when you fail to send through your secret with an API call. Can also occur when using the widget and the HTTP Referer header is not included. | Include the secret listed in the AddressFinder Portal overview page in your API call. When using the widget, you must load the page from a web server (e.g. localhost) and not a file:// scheme. |
1005 | API calls require a Paid plan. | Returned if you try to call the API and you are on a Free plan. Free accounts are expected to use the JavaScript Widget only. | Consider upgrading to a Pro plan. Visit the AddressFinder Portal to change plan. A Developer plan is available for customers in development. Contact us to request the necessary plan change |
1006 | Invalid secret value | Returned when the supplied secret value does not match the value stored in our database. This will normally happen when you make a copy ’n paste error. | Compare the secret included in your API call with the secret listed in the AddressFinder Portal overview page. Also confirm there are no additional spaces or characters in your API call. |
1008 | Secret should not be supplied | This is a safety check to ensure that the secret parameter has not been included when making requests from your web browser. You should never include the secret on any web page. | The secret should be used for server-to-server API calls only. |
1009 | Account has been suspended | Returned when your account (Free plans only) has hit its 100% usage limit for the billing period. | Visit the AddressFinder Portal and upgrade your account to a Paid plan. Alternatively wait until the end of the month when suspended accounts are automatically reactivated. |
1011 | Record not found | Returned when the supplied address identifier cannot be found. This can happen when a stale identifier is included in the API call. | Do not save address identifiers in your database, as they are transisent and may change after each database update. |
1014 | Account Disabled | Your account has been disabled by AddressFinder support. | Contact AddressFinder support to reactivate your account. |
1015 | Cannot include domain parameter in a web request | You have included a domain parameter in your browser based API call. | Remove the domain parameter from your API call. |
1017 | This activity is not permitted on your current plan | You have attempted to use an AddressFinder service that is not valid for current plan. | Consider upgrading to a Pro plan. Visit the AddressFinder Portal to change plan. Alternatively Contact us to discuss plan options. |