Feedback

ThisB2B service allows you to obtain locality information from us and retrieve the unique location identifier, which you will use to call subsequent B2B services.

Related Business Process

BIC001: Query Address or Location

Related Product

This service is available for all products.

 

The data elements and attributes that may be used by this service are described below.


Place Element

The following table describes the Place element

NAME CARDINAL INPUT/OUTPUT DESCRIPTION
Id Mandatory I/O

The primary key for address or location searches

The Place id is commonly referred to as:

  • The Supplier Location ID or
  • The Location Code (TLC)

CoreLogicAddress Elements

The following table describes the CoreLogicAddress elements.

NAME CARDINALITY INPUT/OUTPUT DESCRIPTION
streetNrFirst Optional I/O The lower portion of an address range in a street.
streetNrLast Optional I/O The upper portion of an address range in a street.
streetNrFirstSuffix Optional I/O Suffix used for an address, e.g. 'B' where the address 5B Smith Street.
unitType Optional I/O Type of unit, e.g. an apartment or a room.
unitAlphaNumeric Optional I/O An alphanumeric identifier for a unit type, e.g. an apartment number or a letter
floor Optional I/O Floor number in a multi-story building, e.g. 1, 2, 3.
levelType Optional I/O Type of level, e.g. ground.
locationDescriptor  Optional I/O Description or name that may be associated with an address
streetName Mandatory I/O Name of the street, with no extension, i.e. this does not include Street, Avenue, Lane, etc.
streetType Optional I/O Street type, e.g. Street, Avenue, Lane, etc
roadNameSuffix  Optional I/O Road/street name suffix, e.g. Central, East, Lower, etc.
suburb Optional I/O Name of the suburb or locality.
town Optional I/O Name of the town or city.
postcode Optional I/O Four-digit postal code.
RegionName Optional I/O Region name.
addressType Optional I/O Address type

BIF Address Elements

The following table describes the BIF Structured Address elements.

NAME CARDINALITY INPUT/OUTPUT DESCRIPTION
floor Optional I/O Floor number in multi-story buildings, e.g. 1, 2, 3, etc.
streetAlphaNumeric Optional I/O

Combination of a flat number, the first portion of street number, last portion of street number and street number suffix fields,e.g. 23, 1A/23, 1A/23-27, etc.

The search behaviour section describes how searches are performed against this element.

unitAlphaNumeric Optional I/O An alphanumeric identifier for a unit type, e.g. an apartment number or a letter.
streetName   I/O Name of the street, with no extension, i.e. this does not include Street, Avenue or Lane, etc.
streetSuffix Optional I/O Street type, e.g. Street, Avenue, Lane, etc.
suburb Optional I/O Name of the suburb or locality.
town Optional I/O Name of the town or city
postcode Optional I/O Four-digit postal code.
locationDescriptor Optional I/O Description or name that may be associated with an address.

Address - Address Part Elements

The Address Part elements are used to return additional address information for BIF Structured Address queries.

The following table describes the AddressPart elements.

NAME CARDINALITY INPUT/OUTPUT DESCRIPTION
type   0 Type of address information being returned
value   0 Value of the address information.
Address - Address Part - type

The following table describes the values provided by the type element.

VALUE DESCRIPTION
Building Building name.
Unit Type Type of unit, e.g. an apartment or a room.
Region Name Region name.
Level Type Type of level, e.g. ground.
Road Name Suffix Road/street name suffix, e.g. Central, East, Lower, etc.
Address Type Address type.
Address - Address Part - type - Unit Type
VALUES    
APARTMENT FRONT UNIT SHOP
BACH GARAGE SITE
BARN GRANNY FLAT SLEEPOUT
BASEMENT FLAT HOMESTEAD STUDIO
BOTTOM FLAT HOUSE SUITE
BOTTOM UNIT HUT TOP FLAT
CABIN KIOSK TOP UNIT
CARAVAN OFFICE TOWNHOUSE
COTTAGE PIER TOWNHOUSE
COWSHED REAR FLAT UNIT
CRIB REAR UNIT VILLA
FLAT ROOM WOOLSHED
FRONT FLAT SHED  
Address - Address Part - type - Region Name

The following table describes the values provided by the Region Name element.

VALUES    
AHIPARA HOKITIKA TAIRUA
ASHBURTON INVERCARGILL TAKAKA
AUCKLAND KAWERAU TARANAKI
AUCKLAND CENTRAL LEVIN TARANAKI REGION
AUCKLAND NORTH MANAWATU-WANGANUI TASMAN
AUCKLAND REGION MANAWATU-WANGANUI REGION TASMAN REGION
AUCKLAND SOUTH MANUKAU TASMANS
AUCKLAND WEST MARLBOROUGH TAUMARUNUI
BAY OF PLENTY MARLBOROUGH REGION TAURANGA
BAY OF PLENTY REGION MASTERTON TEMUKA
BLENHEIM NAPIER TURUA
BRIGHTON NELSON UPPER HUT
CANTERBURY  NELSON REGION WAIKATO
CANTERBURY REGION NELSON-MARLBOROUGH WAIKATO
CHATHAMS NEW PLYMOUTH WAIMAKARIRI
CHRISTCHURCH NGONGOTAHA WAIPA
DUNEDIN NORTHLAND WAIROA
FAR NORTH NORTHLAND REGION WANGANUI
GISBORNE OMOKOROA BEACH WELLINGTON
GISBORNE REGION OTAGO WELLINGTON REGION
GORE OTAGO REGION WEST COAST
GREYMOUTH PALMERSTON NORTH WEST COAST REGION
HAMILTON RAKAIA WESTERN BAY OF PLENTY
HASTINGS ROTORUA WHAKATANE
HAWKE'S BAY SOUTHLAND WHANGAMATA
HAWKE'S BAY REGION SOUTHLAND REGION WHANGAREI
Address - Address Part - type - Road Name Suffix

The following table describes the values provided by the Road Name Suffix element

VALUES  
CENTRAL NO 3
E NORTH
EAST NORTHEAST
EXTENSION RIGHT BRANCH
LOOP S
LOWER SOUTH
N UPPER
NO 1 W
NO 2 WEST
Address - Address Part - type - Address Type

The following table describes the values provided by the Address Type element.

VALUES
Primary
Greenfield
Pseudo

Address - Address Key Elements

The address key elements are used to search against TerraLink Unique Identifiers (TUI) or ICMS Unique Identifiers (PLSAM).

NAME CARDINALITY INPUT/OUTPUT DESCRIPTION
type  Optional I/O Used to select the address key type.
value Optional I/O

TUI or PLSAM identifier.

Note:

TUIidentifiers have zero to many relationships with the Place id.

PLSAM identifiers have a one to one relationship with the Place id.

Address - AddressKey - type

The following table describes the values provided by the type element.

VALUE DESCRIPTION
TUI

Indicates that the value being passed is a Terralink Unique Identifier.

This is available for searches using CoreLogic Address elements.

PLSAM

Indicates that the value being passed is an ICMS unique identifier.

This is available for searches using BIF Structured Address elements.

Note: for CoreLogic searches the AddressKey elements will always return the TUI values in the response.


Exact Match Elements

An exact match search can be used to avoid addresses with a common house_high, house_low, flat_low and house_low_suffix being returned. For example, you can search for a location with a house of 23 and the response will not include 23A, 23B, 23B, 1/23.

This function does not apply the wild card rules, it will only search against the information you provide and will not return a result unless there is a single exact match to your criteria.

We do not recommend using this type of searching, as it increases the risk of selecting an incorrect address or having incomplete information available when choosing a service delivery address.

The following table describes the exactMatch elements.

NAME CARDINALITY INPUT/OUTPUT DESCRIPTION
exactMatch Optional I/O

Allows you to select an exact match to the address details provided in the search criteria.

This is available for searches using CoreLogic Address elements or BIF Structured Address elements.

exactMatch values

The following table describes the values provided by the exactMatch element

VALUE DESCRIPTION
true Exact matching will be applied.
false Exact matching will not be applied.

Search Behaviours

Query place searches are not case sensitive and are executed by matching search criteria against our Address Location Manager database, using either:

The order:

1. Road Name

2. Suburb

3. City/Town***

4. Level Number

5. Location descriptor.

Or, one of the address identifiers:

Place id TUI ID PLSAM.

***The query will search query both City and TerritorialAuthority name, as they may have the same value or, in some cases, an address record will not have an associated town name.

Pattern Matching (streetAlphaNumeric)

Pattern matching is used to search against values entered in the BIF Structured Address streetAlphaNumeric field. The following tables describe how pattern matching works.

IFSTREETALPHANUMERIC THEN... CONTAINS... THEN
"/" and no "-" characters, e.g. 1A/23.

1. characters before the "/" are treated as a string and used as the flat number

2. contiguous numbers following the "/" are used as the first portion of the street number 

3. the "/" character is then discarded. Example: streetAlphaNumeric 1A/23 becomes: Flat number 1A and street number 23.

"/" and "-" characters, e.g. 1A/23-27.

1. characters before the "/" are treated as a string and used as the flat number

2. contiguous numbers between the "/" and before the "- " are used as the first portion of the street number

3. contiguous numbers following the "-" are used as the last portion of the streetnumber

4. the "/" and "-" characters are then discarded.

Example:

streetAlphaNumeric 1A/23-27 becomes: Flat number 1A, the first portion of the street number 23 and the last portion of the street number 27

"-" and no "/" characters, e.g. 23-27.

1. contiguous numbers before the "-" are used as the first portion of the streetnumber

2. contiguous numbers following the "-" are used as the last portion of the street number Version '151201114324', printed from https://customer.chorus.co.nz/web-services on March 28 2018.

3. the "-" character is then discarded.

Example:

streetAlphaNumeric 23-27 becomes The first portion of the street number 23 and the last portion of street number 27.

"/" and a letter anywhere after the "/" character, e.g. 1A/23A.

letters following the number after the "/" are used as the street number suffix.

Example:

streetAlphaNumeric 1A/23A becomes: Flat number 1A, the first portion of the street number 23 and street number suffixA.

a letter and no "/" character, e.g. 23B.

1. contiguous numbers are used as the first portion of the street number

2. letters following the numbers are used as the street number suffix.

Example:

streetAlphaNumeric 23B becomes: The first portion of the street number 23 and street number suffix B.

a number with no "/", "-" or characters, e.g. 23.

contiguous numbers are used as the first portion of the street number.

Example:

streetAlphaNumeric 23 becomes: The first portion of the street number 23.

Alternative Road and Alias Suburb Searches

We will always return our primary street/road name and suburb name, regardless of whether the primary or alternative names have been provided in the search.

This means that the address returned in the response may appear to be different from the one requested the search criteria.

Example:

The search criteria:

1 Smith, Ohawe.

Returns:

Place id: 102002584

1 Kingsford Smith Drive, Hawera.


The attached document demonstrates the 30 road and suburb search combinations, for which we return 1 Kingsford Smith Drive, Hawera.

Alternative Road and Alias Suburb Search Results [PDF, 65kB]

Exact Match Searches

The following table shows the elements used for exact match searches. The web service will perform a first level search if an exact match is not found it will perform a second level search.

CORELOGIC FIELD BIF STRUCTURED ADDRESSFIELD MATCH IS SUPPLIED CAN BE NULL NOTES
streetNrFirst streetAlphaNumeric - see Pattern Matching Yes (First level match) No Must be supplied.
streetNrLast streetAlphaNumeric - see Pattern Matching Yes (First level match) Yes Required if the address has a range, e.g. 23-31.
streetNrFirstSuffix streetAlphaNumeric - see Pattern Matching Yes (First level match) Yes Required if the address number has an alpha suffix, e.g. 23A.
unitAlphaNumeric unitAlphaNumeric Yes (First level match) Yes Required if an address has a subunit, e.g. Flat 2/23.
floor floor If supplied used in Secondary level Match Yes Required for multi-storey buildings.
locationDescriptor locationDescriptor If supplied used in Secondary level Match Yes

If a location descriptor exists in the database it will be returned with first level exact match results.

If it is included in the search criteria it will only be used for second-level searching.

streetName streetName Yes (First level match) No Must be supplied.
streetType streetSuffix Yes (First level match) Yes If a road has a type it must be supplied, road names that do not have a road type include SH 1, Broadway, etc.
roadNameSuffix   Yes (First level match) Yes If a road name has a suffix i.e. descriptor after the road name type then it must be supplied otherwise an incorrect match can occur.
suburb suburb Yes (First level match) No Must be supplied.
town town Yes (First level match) No Must be supplied.
postcode postcode Yes (First level match) No Must be supplied.

Query Place Request Detail

Service Name

QueryPlaceRequest

Service Inputs

The following criteria can be used when requesting this service

INPUT DESCRIPTION
Place id The primary key for address or location searches.

BIF Structured Address elements Exact match flag (Optional)

Textual Identifier compromised of a number of fields in a structured form, see BIF Structured Address Elements.
Core Logic Address elements Exact match flag (optional) Textual Identifier compromised of a number of fields in a structured form,  see CoreLogic Address Elements.
TUI Terralink Unique Identifier see AddressKey Elements.
PLSAM ID ICMS unique identifier for individual physical addresses see AddressKey Elements.

Message Handling Specifications

NAME QUERYPLACEREQUEST
MEP Synchronous call with Acknowledgement.
Inputs Query an address or a place
Outputs Synchronous Acknowledgement.
Non-repudiation Yes.
Description Initiates a transaction to query an address or place.

Query Place Response Details

Service Name

QueryPlaceResponse

Service Outputs

If valid search criteria was provided, the response will contain the Place id, any AddressKey details used in the request, and one of the following:

  • A list of addresses which match or closely match the search criteria.
  • Where the address has sub addresses, e.g. an MDU, the list will include the main and sub addresses.
  • An exact address match.
  • No matches (represented by an empty list being returned).

Multiple results will be limited to the first 200 closest matching records. They will be ordered using the following main steps:

1. Alphabetically by street name(ascending)

2. Numerically by:

  • House_low
  • House_high
NAME QUERYPLACERESPONSE
MEP Synchronous call with Acknowledgement.
Inputs Response to your query of an address or a place.
Outputs Synchronous Acknowledgement.
Non-repudiation Yes.
Description Query place request is processed or has an exception.