# Address Lookup Using Link Table
The lookup first attempts to match against the pre-built link table, if no match is found, performs an **online linkage** to dynamically resolve and store new links.
The address lookup process involves two main API calls:
1. [similar-addresses](#similar-addresses)
* Accepts an input address and searches across multiple sources.
* Uses the **link table** to group and consolidate matching candidates.
* Returns a list of **consolidated address candidates**, each with a unique **linked ID**.
2. [address-by-id](#address-by-id)
* Takes a **linked ID** (from the previous step) and returns the full, resolved address record.
* Ensures consistent retrieval of unified address data across systems.
## Prerequisites:
Before using the link table in address lookup, you must first generate the link table using the **Batch Link Table Build Tool.**
{% content-ref url="/pages/6of5vcqvjlVkDRc1BHEM" %}
[Batch Link Table Build](/harmony-suite/user-guides/version-3.2.0/address-link-table-integration-guide/batch-link-table-build.md)
{% endcontent-ref %}
After the link table has been created, you will need to obtain the `access.dat.key` file from **Loqate Support**.
Once you have both the link table and the key, place the link table in the default directory located at `$HARMONY_HOME/ROAD/LINK_TABLE`. If you have overridden the default location, make sure to update the `harmony.hello.linktable.location` property in the [`hello.properties`](#configuration-properties) file, which is located under `$HARMONY_HOME/config`. By default, this property points to `$HARMONY_HOME/ROAD/LINK_TABLE`.
### **Configuration Properties**
These properties can be set in the `hello.properties` file located at:\
`$HARMONY_HOME/config/hello.properties`
| Property | Description | Default Value |
| -------------------------------------------- | ------------------------------------------------------- | ------------------------------- |
| `harmony.hello.linktable.location` | Link table directory path | `$HARMONY_HOME/ROAD/LINK_TABLE` |
| `harmony.hello.linktable.update.linktable` | Enable writing to link table if online linkage is found | `true` |
| `harmony.hello.linktable.online.linkage` | Enable online linkage | `true` |
| `harmony.hello.linktable.transitive.linkage` | Enable transitive lookup (e.g., A→B, B→C → A→C) | `true` |
| `harmony.hello.linktable.update.interval` | Interval for link table updates | `5 minutes` |
### **Standardization Terms**
A new configuration file has been added at: `$HARMONY_HOME/config/sub/link_table.properties`\
This file lists interchangeable terms used to standardize address lines across sources.
## similar-addresses
When multiple sources are used in a search and a `linkTableName` is provided (this refers to the folder name of your link table under the `LINK_TABLE` directory), the system groups results by `sourceName` , then attempts to identify and consolidate related records based on link table entries. If linked records are found, they are merged into a single result with a combined ID and marked as coming from the `LINKTABLE` source.
**Behavior Changes in This Version**
* Previously, `sourceName` was only populated when the source was `CUSTOM`.
* Now, if `sourceName` is empty, it will default to the value of `source` (e.g., `NZPAF`, `CNAR`, `NZAD`).
**Linking Logic**
1. **Group Results by Source**: Results are grouped based on `sourceName`.
2. **Link Table Matching**: For each group, the system checks the link table for matching link pairs.
* If matches are found, it combines all linked IDs and source names into a single `id` field.
* The `addressLine` is taken from the base record, and the `source` is set to `LINKTABLE`.
* Example ID:
```
NZAD:210910;NZPAF:210910;CUSTOM/CNAR:9591956
```
3. **Fallback Matching**: If no direct link is found, the system attempts to match address lines across groups.
* If successful, it creates a new link and writes it to the link table for future use.
### Resource
The port number is configurable, with the default ports being:
* Tomcat: 8080
POST http://localhost:8080/HRAWeb/hra/rest/au/address/similar-addresses
**Usage Notes**
The following options have been introduced to enhance the flexibility and control of address consolidation using the link table:
| Option | Type | Description | Default |
|---|
linkTableName | string | Required when consolidating records from multiple sources using a link table. The value should match the folder name of your link table (i.e., the hello index folder name under LINK_TABLE). | N/A |
linkTableTypeFilters | list of strings | Filters the types of linkages used from the link table. To include specific link types, list them directly (e.g., ["EXACT", "MPP"]). To exclude, prefix with - (e.g., ["-TBC"]). Applicable types: EXACT, MPP, STREET_RANGE, TBC. | [] (empty list) |
transliteration | integer (0 or 1) | Enables transliteration of accented characters to ASCII equivalents in single-line HRA address searches. 0 = disabled, 1 = enabled (e.g., Ā → A, ē → e). | 0 |
| | | |
### Sample Request and Response
Request 1: POST- Lookup for addresses from CUSTOM/TUI, NZAD and CNAR with transliteration on
{
"option": {
"source": "CUSTOM",
"moreSources": ["NZAD","CNAR"],
"sourceNames": ["TUI"],
"linkTableName":"LINK_TABLE_NZ",
"transliteration":1
},
"payload": {
"fullAddress": "78A Kēnsington street,Putaruru"
}
}
Response 1: POST- Lookup for addresses from CUSTOM/TUI, NZAD and CNAR with transliteration on
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "78A KENSINGTON STREET, PUTARURU 3411",
"id": "NZAD:1294125;CNAR:3fbcd6ffa59beb342b4018f361b3744b657d87a8",
"attributes": {
"source": "LINKTABLE",
"sourceName": "LINKTABLE"
}
},
{
"fullAddress": "78 KENSINGTON STREET, PUTARURU 3411",
"id": "NZAD:1292913",
"attributes": {
"source": "NZAD",
"sourceName": "NZAD"
}
},
{
"fullAddress": "78C KENSINGTON STREET, PUTARURU 3411",
"id": "NZAD:1294126;CNAR:6ff018246bfbc212c7fa954f2da6a0548340707e",
"attributes": {
"source": "LINKTABLE",
"sourceName": "LINKTABLE"
}
},
{
"fullAddress": "78B KENSINGTON STREET, PUTARURU 3411",
"id": "NZAD:1294145;CNAR:9dbbef7e1739d25015c224c93f89fd29419322ae",
"attributes": {
"source": "LINKTABLE",
"sourceName": "LINKTABLE"
}
}
]
}
```
Request 2: POST- Lookup for addresses with All link types
```json
{
"option": {
"source": "CUSTOM",
"moreSources": ["NZAD", "CNAR"],
"sourceNames": ["TUI"],
"linkTableName": "LINK_TABLE_NZ"
},
"payload": {
"fullAddress": "UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011"
}
}
```
Response 2: POST- Lookup for addresses with All link types
195 VICTORIA STREET, TE ARO, WELLINGTON 6011 (CNAR:9670085cdd8ec2232794ba1820289f66e31ee420) is also linked with UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011 by link type as MPP (matched to primary point)
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "NZAD:3856348;CUSTOM/TUI:3856348;CNAR:9670085cdd8ec2232794ba1820289f66e31ee420",
"attributes": {
"source": "LINKTABLE",
"sourceName": "LINKTABLE"
}
},
{
"fullAddress": "FLOOR 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "NZAD:3233277",
"attributes": {
"source": "NZAD",
"sourceName": "NZAD"
}
},
{
"fullAddress": "FLOOR 2 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:1b418b2580c5dcd072720429ab7ce2fb5c699785",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
},
{
"fullAddress": "FLOOR 3 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:bceee6c8394ff0e9d2b62a8044ba46e7011c9095",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
},
{
"fullAddress": "FLOOR 4 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:bad448b66de2c964584e2edb02fc15cdb5b3c0eb",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
}
]
}
```
Request 3: POST- Lookup for addresses with linkTableTypeFilters Option (INCLUDE)
```json
{
"option": {
"source": "CUSTOM",
"moreSources": ["NZAD", "CNAR"],
"sourceNames": ["TUI"],
"linkTableName": "LINK_TABLE_NZ",
"linkTableTypeFilters": ["EXACT"]
},
"payload": {
"fullAddress": "UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011"
}
}
```
Response 3: POST- Lookup for addresses with linkTableTypeFilters Option (INCLUDE)
Include only the link type as EXACT, 195 VICTORIA STREET, TE ARO, WELLINGTON 6011 (CNAR:9670085cdd8ec2232794ba1820289f66e31ee420) is not linked with UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "NZAD:3856348;CUSTOM/TUI:3856348",
"attributes": {
"source": "LINKTABLE",
"sourceName": "LINKTABLE"
}
},
{
"fullAddress": "FLOOR 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "NZAD:3233277",
"attributes": {
"source": "NZAD",
"sourceName": "NZAD"
}
},
{
"fullAddress": "195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:9670085cdd8ec2232794ba1820289f66e31ee420",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
},
{
"fullAddress": "FLOOR 2 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:1b418b2580c5dcd072720429ab7ce2fb5c699785",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
},
{
"fullAddress": "FLOOR 3 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:bceee6c8394ff0e9d2b62a8044ba46e7011c9095",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
},
{
"fullAddress": "FLOOR 4 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:bad448b66de2c964584e2edb02fc15cdb5b3c0eb",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
}
]
}
```
Request 4: POST- Lookup for addresses with linkTableTypeFilters Option (EXCLUDE)
```json
{
"option": {
"source": "CUSTOM",
"moreSources": ["NZAD", "CNAR"],
"sourceNames": ["TUI"],
"linkTableName": "LINK_TABLE_NZ",
"linkTableTypeFilters": ["-MPP"]
},
"payload": {
"fullAddress": "UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011"
}
}
```
Response 4: POST- Lookup for addresses with linkTableTypeFilters Option (EXCLUDE)
Exclude link type of "MPP", 195 VICTORIA STREET, TE ARO, WELLINGTON 6011 (CNAR:9670085cdd8ec2232794ba1820289f66e31ee420) is not linked with UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "NZAD:3856348;CUSTOM/TUI:3856348",
"attributes": {
"source": "LINKTABLE",
"sourceName": "LINKTABLE"
}
},
{
"fullAddress": "FLOOR 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "NZAD:3233277",
"attributes": {
"source": "NZAD",
"sourceName": "NZAD"
}
},
{
"fullAddress": "195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:9670085cdd8ec2232794ba1820289f66e31ee420",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
},
{
"fullAddress": "FLOOR 2 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:1b418b2580c5dcd072720429ab7ce2fb5c699785",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
},
{
"fullAddress": "FLOOR 3 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:bceee6c8394ff0e9d2b62a8044ba46e7011c9095",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
},
{
"fullAddress": "FLOOR 4 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"id": "CNAR:bad448b66de2c964584e2edb02fc15cdb5b3c0eb",
"attributes": {
"source": "CNAR",
"sourceName": "CNAR"
}
}
]
}
```
## address-by-id
The `address-by-id` API retrieves full address details using an ID. This ID can be either a **single-source ID** or a **consolidated ID** in the format of `source:id`. Consolidated IDs may include one or more source-ID pairs, depending on how the data was linked or structured.
**Usage Notes**
* When using a **concatenated ID** (e.g., `"NZAD:1294125"` or `"NZAD:1294125;CNAR:abc123"`), the `source` in the `option` field must be set to `"LINKTABLE"`. This tells the system to interpret the ID as a linked or structured identifier, even if it only contains one source.
* For **single-source IDs**, set the `source` to the corresponding source name (e.g., `"CNAR"`, `"NZPAF"`). In the request `payload`, you can provide the identifier in one of two ways: using the `id` field (which accepts either a standard `id` or a `hash_id`), or using the `dpid` field if applicable. The API will use the provided identifier to retrieve the corresponding address record from the specified source.
### Resource
The port number is configurable, with the default ports being:
* Tomcat: 8080
POST http://localhost:8080/HRAWeb/hra/rest/au/address/address-by-id
### Sample Request and Response
Request 1: POST- Retrieve Address by concatenated id
```json
{
"option": {
"source": "LINKTABLE"
},
"payload": {
"id": "NZAD:1294125;CNAR:3fbcd6ffa59beb342b4018f361b3744b657d87a8"
}
}
```
Response 1: POST- Retrieve Address by concatenated id
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "78A KENSINGTON STREET, PUTARURU 3411",
"addressLine1": "78A KENSINGTON STREET",
"addressLine2": "PUTARURU 3411",
"dpid": "1294125",
"postcode": "3411",
"streetName": "KENSINGTON",
"streetType": "STREET",
"houseNumber1": "78",
"houseNumberSuffix1": "A",
"townCityName": "PUTARURU",
"xCoordinate": "1843736.23652993",
"yCoordinate": "5785241.73874033",
"parcelId": "6549996",
"latitude": "-38.047771486053115",
"longitude": "175.7776626311639",
"attributes": {
"addr_full": "78A KENSINGTON STREET",
"address_line1": "78A KENSINGTON STREET",
"address_line2": "PUTARURU 3411",
"address_type": "URBAN",
"area_unit": "535600",
"cnar_id": "10506711",
"complete_address": "78A KENSINGTON STREET PUTĀRURU PUTĀRURU 3411",
"delivered_to": "Y",
"deprivation_index": "9",
"hash_id": "3fbcd6ffa59beb342b4018f361b3744b657d87a8",
"l_x_nzmg": "2753922.25",
"l_x_nztm": "1843738.625",
"l_x_webmerc": "19567483.466819502",
"l_x_wgs84": "175.7776947",
"l_y_nzmg": "6346816.0",
"l_y_nztm": "5785238.5",
"l_y_webmerc": "-4586180.29202652",
"l_y_wgs84": "-38.04779816",
"linked_address_lines": "NZAD:78A KENSINGTON STREET, PUTARURU 3411;CNAR:78A KENSINGTON STREET, PUTĀRURU 3411",
"linked_id": "NZAD:1294125;CNAR:3fbcd6ffa59beb342b4018f361b3744b657d87a8",
"meshblock_id_2013": "1130300",
"quintile": "4",
"regional_council": "WAIKATO REGION",
"regional_council_id": "3",
"regional_council_name": "WAIKATO REGION",
"road_id": "100009548",
"sa1_2018": "7013089",
"sa2_2018": "186000",
"source": "NZAD",
"sourceName": "NZAD",
"street_number_full": "78A",
"ta": "SOUTH WAIKATO DISTRICT",
"ta_id": "19",
"ta_name": "SOUTH WAIKATO DISTRICT",
"x_nzmg": "2753922.0",
"x_nztm": "1843738.0",
"x_webmerc": "19567483.466819502",
"y_nzmg": "6346815.0",
"y_nztm": "5785237.0",
"y_webmerc": "-4586181.370593036"
},
"meshblockId": "1130300"
}
]
}
```
Request 2: POST- Retrieve Address by single-source id
```json
{
"option": {
"source":"NZAD"
},
"payload": {
"id": "3856348"
}
}
```
Response 2: POST- Retrieve Address by single-source id
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"addressLine1": "UNIT 1",
"addressLine2": "195 VICTORIA STREET",
"addressLine3": "TE ARO",
"addressLine4": "WELLINGTON 6011",
"dpid": "3856348",
"localityName": "TE ARO",
"postcode": "6011",
"streetName": "VICTORIA",
"streetType": "STREET",
"houseNumber1": "195",
"flatUnitType": "UNIT",
"flatUnitNumber": "1",
"townCityName": "WELLINGTON",
"xCoordinate": "1748517.51537024",
"yCoordinate": "5427173.08380447",
"parcelId": "4043292",
"latitude": "-41.29323326575049",
"longitude": "174.7737787211607",
"attributes": {
"address_line1": "1/195 VICTORIA STREET",
"address_line2": "TE ARO",
"address_line3": "WELLINGTON 6011",
"address_type": "URBAN",
"delivered_to": "N",
"regional_council_id": "9",
"regional_council_name": "WELLINGTON REGION",
"source": "NZAD",
"sourceName": "NZAD",
"ta_id": "47",
"ta_name": "WELLINGTON CITY"
},
"meshblockId": "2131700"
}
]
}
```
Request 3: POST- Retrieve Address by custom-source id
{
"option": {
"source":"CUSTOM",
"sourceNames":["TUI"]
},
"payload": {
"id": "3856346"
}
}
Response 3: POST- Retrieve Address by custom-source id
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "66 HOCKEN LANE, TWIZEL 7999",
"addressLine1": "66 HOCKEN LANE",
"addressLine2": "TWIZEL 7999",
"postcode": "7999",
"state": "TWIZEL",
"streetName": "HOCKEN",
"streetType": "LANE",
"houseNumber1": "66",
"latitude": "-38.66666666",
"longitude": "175.6666666",
"id": "3856346",
"attributes": {
"TUI": "1003432764",
"city": "TWIZEL",
"record_type": "address",
"source": "CUSTOM",
"sourceName": "CUSTOM/TUI"
}
}
]
}
```
Request 4: POST- Retrieve Address by single-source dpid
```json
{
"option": {
"source":"NZAD"
},
"payload": {
"dpid": "3856348"
}
}
```
Response 4: POST- Retrieve Address by single-source dpid
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "UNIT 1 195 VICTORIA STREET, TE ARO, WELLINGTON 6011",
"addressLine1": "UNIT 1",
"addressLine2": "195 VICTORIA STREET",
"addressLine3": "TE ARO",
"addressLine4": "WELLINGTON 6011",
"dpid": "3856348",
"localityName": "TE ARO",
"postcode": "6011",
"streetName": "VICTORIA",
"streetType": "STREET",
"houseNumber1": "195",
"flatUnitType": "UNIT",
"flatUnitNumber": "1",
"townCityName": "WELLINGTON",
"xCoordinate": "1748517.51537024",
"yCoordinate": "5427173.08380447",
"parcelId": "4043292",
"latitude": "-41.29323326575049",
"longitude": "174.7737787211607",
"attributes": {
"address_line1": "1/195 VICTORIA STREET",
"address_line2": "TE ARO",
"address_line3": "WELLINGTON 6011",
"address_type": "URBAN",
"delivered_to": "N",
"regional_council_id": "9",
"regional_council_name": "WELLINGTON REGION",
"source": "NZAD",
"sourceName": "NZAD",
"ta_id": "47",
"ta_name": "WELLINGTON CITY"
},
"meshblockId": "2131700"
}
]
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.mastersoftgroup.com/harmony-suite/user-guides/version-3.2.0/address-link-table-integration-guide/address-lookup-using-link-table.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.