/* Click the button above to see a real API response here */
{
"success": true
}
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 |
---|---|---|---|
name | String | The name of the point of interest | Whangarei Hospital |
pxid | String | Unique point of interest identifier. | 3-.1.1d.2.42.1T.2 |
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 |
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 |
unit_identifier | String | Identifies a specific sub dwelling. Can be alpha, number or a combination. | 1 |
unit_type | String | Describes the category of a sub-dwelling. | flat |
floor | String | The level number and level type in a multi-story building. | Level 19 |
street | String | Holds the full name of the street. Note: The street attribute also includes the Street Type. | State Highway 1 |
street_type | String | The type of street. | avenue |
building_name | String | Holds the building or property name. | Miban Building |
suburb | String | The suburb or locality of the address as assigned by Land Information New Zealand. | Warkworth |
post_suburb | String | Name of the suburb when supplied by NZ Post. | Manukau |
city | String | The city, town or locality name as assigned by Land Information New Zealand. | Warkworth |
mailtown | String | Name of the town/city when supplied by NZ Post. | Warkworth |
ta | String | The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. | Auckland |
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 |
rd_number | String | The rural delivery number assigned by NZ Post to a rural address. | 4 |
postcode | String | Holds the four digit postcode. | 0983 |
meshblock | String | The meshblock identifier for the requested census dataset (see census parameter). If not specified, the Census parameter will default to 2018. | 146004 |
address_pxid | String | Address identifier for the address of this point of interest. | 2-.F.11.8.G.4 |
aims_address_id | Integer | The unique identifier from Land Information New Zealand (LINZ). | 103524 |
dpid | String | A unique reference number assigned to each delivery address by NZ Post. | 2668726 |
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 |
x | String | Longitude coordinate (in WGS84 format). | 174.643199 |
y | String | Latitude coordinate (in WGS84 format). | -36.426956 |
success | Boolean | Indicates if the request was successful or not. | true |
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 | 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 | Key not provided | 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 | Domain not registered with AddressFinder | 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 domains that are allowed to use your account. Login to the AddressFinder Portal and add the domain of this website to your account. |
1004 | Secret not provided | 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 | Direct API calls are not permitted on your current plan. | Returned if you try to call the API and you are on either a Free or Agile plan. These plan types provide access to the JavaScript Widget and plugins only. | Upgrade to a Business plan. Visit the AddressFinder Portal to change plan. |
1006 | Invalid credentials | Returned when the supplied key and/or secret value are incorrect. This will normally happen when you make a copy ’n paste error. | Compare the key and secret included in your API call with the values listed on the AddressFinder Portal credentials 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 | The AddressFinder plugin has exceeded the number of allowed lookups, and is now suspended | Returned when your account (free plans only) has hit its 100% usage limit for the billing period. | Visit the AddressFinder Portal and switch to a Paid plan. Alternatively wait until the end of the month when suspended accounts are automatically reactivated. |
1010 | Account not authorised to use this API | Returned when you make an API call that you are not permitted to use | Contact AddressFinder support to request access to this API. |
1011 | The record you are trying to load does not exist | 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 transient and may change after each database update. |
1012 | Account not authorised to use this API | Returned when you make an API call that you are not permitted to use | Contact AddressFinder support to request access to this API. |
1013 | This API has been discontinued | This API has been discontinued | Contact AddressFinder support to discuss alternatives. |
1014 | Account Disabled | Your account has been disabled by AddressFinder support. | Contact AddressFinder support to discuss reactivating your account. |
1015 | Domain parameter must not be included in a web request | You have included a domain parameter in your browser based API call. The domain parameter is for direct API calls only. | Remove the domain parameter from your web request. |
1016 | This domain has been blocked | These credentials are not permitted to be used on this domain. | Contact AddressFinder support to discuss removing the block. |
1017 | This service is not enabled on your current plan | You have attempted to use an AddressFinder service that is not enabled on your current plan. | Visit the AddressFinder Portal to change plan. |
1018 | Your IP address has been blocked for these credentials | This service has been configured to only allow access from defined IP addresses. | Visit the AddressFinder Portal and add your IP address to the IP Allow List. |
1019 | HTTP Referer or Origin header record must be present when making a browser initiated request | You have attempted to use the AddressFinder widget from a browser that does not include the referrer or orgin headers along with each request. | Confirm that this request was sent from a valid web server (not the local filesystem), and that you do not have browser plugins interfering with the request. |
1020 | Your AddressFinder trial has ended | Returned when the trial term has ended. | Log into the AddressFinder Portal and upgrade your account to a suitable plan. |
1021 | Your AddressFinder trial has exceeded its allowed lookups. | Returned when you have exceeded the number of lookups permitted on the trial plan. | Log into the AddressFinder Portal and upgrade your account to a suitable plan. |