Javascript Library v2.1.0

Javascript library to to use Loqate Harmony solutions from client side

Getting Started

Prerequisites

1. Harmony API Account.

2. We strongly recommend Allowlisting your domain when implementing this method.

Quick Start

Looking to quickly add Harmony to your project? Harmony JS library can be deployed on a web page, allowing users to connect directly to the Harmony API services without any server-side processing requirements. Its recommended to Allowlist your domain.

Use our content delivery by copying and pasting into your html

<link rel="stylesheet" type="text/css" href="https://common.mastersoftgroup.com/scripts/harmony-2.1.0.min.css">
<script src="https://common.mastersoftgroup.com/scripts/harmony-2.1.0.min.js" type="text/javascript"></script>

Using a package manager or need to download the source files? Download the files located in content delivery.

Initializing the client

Before making service requests, the client must be initialised. This is done by invoking the init method on the global Harmony object:

    Harmony.init({String} username, {String} password, {String} locale);

This method must be called before any other methods are invoked on the Harmony object.

    <script type="text/javascript">

        Harmony.init("webUser", "password", Harmony.AUSTRALIA);

    </script>

Setting the environment and protocol

During initialization, the client environment is set to Production and the protocol is set to CORS. To use the Production environment or the JSONP protocol, the useEnv and useProtocol methods can be used.

    <script type="text/javascript">

        // Use the Production environment
        Harmony.useEnv(Harmony.ENV_PRODUCTION);

        // Use the JSONP protocol
        Harmony.useProtocol(Harmony.JSONP);

    </script>

Invoking Address services

Once the client has been initialized, any methods available to the supplied user can be invoked. These methods are invoked using the global Harmony object.

Address Find (Autocomplete)

The following example invokes the find method with the single-line address '1 abc street' in Canada. The callback method then output the addresses in a textarea with the id 'output':

Harmony.v2.find({ fullAddress: "1 abc street", country: "CA"}, null,
		function(response) {
			if (response.status == Harmony.SUCCESS) {
			
				// Do something with the response payload.
				for (var i = 0; i < response.payload.length; i++) {
					var address = response.payload[i];
					...
				}
				
			} else {
			
				// Show any error messages.
				for (var i = 0; i < response.messages.length; i++) {
					alert(response.messages[i]);
					...
				}
				
			}
		}
	);

Find FeatureOptions

Only use FeatureOptions when you want to change the system defaults.

The following example configures feature options for address lookup service methods.

    Harmony.useFeatureOptions({singleLineHitNumber:'10', displayGnafLot: 1, 
    		exposeAttributes:'1', exposePhantom:'0'});

Extending Library for Autocomplete

The client library acts as an extension of Javascript Library for Address Find (Autocomplete).

Please refer to the Code snippet section to copy and paste to your web page.

Methods

Name	Description	Since
HarmonyJS.addField	Adds a new field specifying the field name (e.g. Harmony.POSTCODE, Harmony.LOCALITY, etc) or the attribute name (e.g. "attributes.Line1", "attributes.Latitude", etc), and the input element.	2.0.0
HarmonyJS.addressLookup	Single-line address lookup on the supplied input element.	2.0.0

HarmonyJS.addField(field, element, index)

Adds a new field specifying the field name (e.g. Harmony.POSTCODE, Harmony.LOCALITY, etc) or the attribute name (e.g. "attributes.Line1", "attributes.Latitude", etc), and the input element.

field

Type: String

The name of the field (e.g. Harmony.POSTCODE) or attribute (e.g. "attributes.Line1") to be added.

element

Type: Object

The input element to be assigned to the field (e.g. document.getElementById("postcodeField")).

index

Type: Integer

The optional index if there are multiple sets of lookups on the same page (e.g. one for residential addresses and the other one for postal addresses). Currently only available for addressLookup.

The following example assigns the Harmony.LOCALITY field to the input element with localityField ID and the "attributes.Latitude" attribute to the input element with latitudeField ID:

    // Perform the assignment using standard JavaScript on single address lookup.
    HarmonyJS.addField(Harmony.LOCALITY, document.getElementById("localityField"));
    HarmonyJS.addField("attributes.Latitude", document.getElementById("latitudeField"));
    
    // Perform the assignment using standard JavaScript on the second set address lookup.
    HarmonyJS.addField(Harmony.LOCALITY, document.getElementById("localityField"), 1);
    HarmonyJS.addField("attributes.Latitude", document.getElementById("latitudeField"), 1);
    

HarmonyJS.addressLookup(element, countryElement, sourceOfTruth, opts, index)

Creates single-line address lookup with the current Address lookup APIs on the supplied input and country elements. It returns the response from find service and the callback is available via onSelect option.

For retrieve service, the response is available via ui.onRetrieveItem and the callback is available via onRetrieve option. For internationalGeocode service, if getIntlGeocode options is enabled, the response is available via ui.onIntlGeocodeItem and the callback is available via onIntlGeocode option.

element

Type: Object

The input address element to create the lookup for (e.g. document.getElementById("address")).

countryElement

Type: String or Object

The Country used for the lookup. It can be String (e.g. Harmony.AUSTRALIA for Australia) or Object in input or select Country element (e.g. document.getElementById("country")).

sourceOfTruth

Type: String or Object

The Source of Truth to override the default Australia and New Zealand SOTs. It is optional. It can be String (e.g. Harmony.AUPAF for Australia) or Object in input or select Source of Truth element (e.g. document.getElementById("sourceOfTruth")).

opts

Type: Object

Optional parameter to be passed into the auto-complete component (e.g. getIntlGeocode true/false to enable international geocode call for the selected address, default is false. And callback functions e.g. onRetrieve and onIntlGeocode in below sample).

index

Type: Integer

Optional index to indicate which set of fields to populate if there are multiple lookups on the same page.

Example

The following example creates a single-line address lookup (use AUPAF for Australian addresses) on the input element with ID singleLineAddress and country and customized opts:

    let opts = {
        // min 3 chars to trigger the lookup
        minLength: 3,
        //autocomplete function will only be called once within the specified time frame (ms)
        delay: 500,
        // enable Harmony.International.getGeocode for non-AU/NZ countries when address selected.
        getIntlGeocode: true,
        //Override onSelect function if applicable. It is Optional
        onSelect: function (ui) {
            console.log('address selected: ' + JSON.stringify(ui));
        },
        //Override onIntlGeocode function if applicable. It is Optional
		//e.g. get ui.onIntlGeocodeItem object for address payload after onIntlGeocode call.
        onIntlGeocode: function (ui) {
            console.log('geocode address selected: ' + JSON.stringify(ui.onIntlGeocodeItem));
        },
        //Override onRetrieve function if applicable. It is Optional
		//e.g. get ui.onRetrieveItem object for address payload after onRetrieve call.
        onRetrieve: function (ui) {
            console.log('onRetrieve address selected: ' + JSON.stringify(ui.onRetrieveItem));
        }
    };

    let input = document.getElementById("addressField");
    let country = document.getElementById("countryField");
    Harmony.useFeatureOptions({ "exposeAttributes": 0, "groupAddresses": 1 });
    HarmonyJS.addressLookup(input, country, null, opts);

Code snippet

Loqate Harmony API provides a self-service console where a customer can quickly generate a ready to use code snippet. You can find more information here about sign up or login.

The following is an example of how the generated code looks. Please note, the actual user and credential will be different for different customers.

<select id="country">
    <option value="au">Australia</option>
    <option value="nz">New Zealand</option>
    <option value="gb">United Kingdom</option>
    <option value="us">United States</option>
    <option value="ca">Canada</option>
</select>

<input type="text" id="address" size="40" placeholder="Type in address here" />
<div id="error"></div>
<br />

<!-- You also can use a "current" version (e.g: harmony-current.min.js) instead of a specific version -->
<script src="https://common.mastersoftgroup.com/scripts/harmony-2.1.0.min.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="https://common.mastersoftgroup.com/scripts/harmony-2.1.0.min.css">

<script>
    var input = document.getElementById("address");
    var country = document.getElementById("country");
    // Use the production environment
    Harmony.useEnv(Harmony.ENV_PRODUCTION);

    // Init the client with the api user name and credential
    Harmony.init("<my-api-user>", "<my-credential>", Harmony.AUSTRALIA);
    //exposeattributes
    Harmony.useFeatureOptions({"exposeAttributes":1, "groupAddresses":1});
         
    var opt = {
      // min 3 chars to trigger the lookup
      minLength:3, 
      // enable getGeocode for non ANZ countries when address selected.
      getIntlGeocode:true,
      
      // override onSelect function if applicable (optional)
      onSelect: function(event, ui) {
         //console.log('address selected: ' + JSON.stringify(ui));
      },
	  
      // override onGeocode function if applicable (optional)
      onIntlGeocode: function(event, ui) {
        // console.log('geocode address selected: ' + JSON.stringify(ui.onIntlGeocodeItem));
      },
	  
      // override onRetrieve function if applicable (optional)
      onRetrieve: function(event, ui) {
        // console.log('onRetrieve geocode address selected: ' + JSON.stringify(ui.onRetrieveItem));
      }
    };
   
    // Configure the address lookup. 
    var al = HarmonyJS.addressLookup(input, country, null, opt);

</script>