Address Lookup Using Link Table

This section explains how the HRA address lookup process utilizes the link table to return consolidated address records across multiple sources.

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

   • 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

   • 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.

Batch Link Table Build

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 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

{
  "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

{
  "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)

{
  "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)

{
  "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

{
  "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)

{
  "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

{
  "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

{
    "option": {
          "source": "LINKTABLE"         
    },
    "payload": {
          "id": "NZAD:1294125;CNAR:3fbcd6ffa59beb342b4018f361b3744b657d87a8"
    }
}

Response 1: POST- Retrieve Address by concatenated id

{
  "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

{
    "option": {
        "source":"NZAD"     
 
    },
    "payload": {
          "id": "3856348"
    }
} 

Response 2: POST- Retrieve Address by single-source id

{
  "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

{
  "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

{
    "option": {
        "source":"NZAD"     
 
    },
    "payload": {
          "dpid": "3856348"
    }
} 

Response 4: POST- Retrieve Address by single-source dpid

{
  "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"
    }
  ]
}