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.
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 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 |
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. |
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. |
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. |
| 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 |
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 |
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 |
The following table describes the values provided by the Address Type element.
| VALUES |
|---|
| Primary |
| Greenfield |
| Pseudo |
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. |
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.
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. |
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. |
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 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. |
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]
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. |
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. |
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:
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:
| 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. |