AddressFinder | Developer Documentation

Address Validation Non-Interactive API

The non-interactive api allows calls to be made to the addressfinder service where a full address is given (with or without a name). The addressfinder attempts to match this unstructured address data to a valid NZ postal geocoded and structured address.

REST API: The default access to the addressfinder service is via our REST API. The documentation and examples below define how the API operates.

SOAP API: The addressfinder service can also be accessed using the SOAP API. This API is available to enterprise customers on an as-needed basis. Contact Able Technology for further details on this service.

Request

The request is a simple HTTP GET request with the query string parameter (q) set to the unstructured address string

URL structure

http://api.addressfinder.co.nz/address/match?q=[query]&key=[api-key]

Parmeters

• q The unstructured url encoded address/address name string. Required
• with_name If your search string includes an optional name field. If the address may contain a name set this to true. This gives us a hint for what we are parsing. Optional
• match_type The types of addresses to match. One of postal_address_match, dwelling_match or combined_address_match (the default).
• key Your license key for the service. Contact us for one of these. Required

Example

http://api.addressfinder.co.nz/address/match?q=Bob%20Ian%20Smith%2011/240%20The%20Terrace%20Wellington&with_name=true&key=EXAMPLE_KEY_XYZ

Response

The response is a JSON structure that can be used directly in javascript or converted by a json decoder library freely available in modern programming languages.

Client applications should check the statuscode field of the response to determine the address parsing success/fail status. The possible values are:

• validmatch Exactly one match was obtained to a valid NZ postal address. A full address structure and name field are available.
• partialmatch Multiple matches were available. The name field and the first address will be returned. We can not give you an address without further information
• nomatch We could not accurately validate the input to a valid NZ postal address
• invalidmatch Valid match rejected as high possibility that address matched is incorrect - can be treated as a nomatch

Example

Output - validmatch

{
  "statuscode": "validmatch",
  "name": "Bob Ian Smith",
  "postal": "Flat 11, 240 The Terrace, Wellington Central, Wellington 6011",
  "postcode": "6011",
  "street": "The Terrace",
  "units": "false",
  "number": "1",
  "region": "Wellington Region",
  "pxid": ".F.1Z.u.X.12",
  "city": "Wellington",
  "y": "-41.2790160514851",
  "x": "174.775751850054",
  "suburb": "Wellington Central",
  "meshblock": "",
  "dpid": "",
  "z": 15
}

Output - partialmatch

{
  "statuscode": "partialmatch",
  "name": "Bob Ian Smith"
}

Output - nomatch

{
  "statuscode": "nomatch"
}

Server-to-Server calls

Please set the HTTP_REFERER to the domain that you will be calling from.

Try it out