Deprecated JS Library v2.0.1

This method has been deprecated. Please use current version for new implementations.

JavaScript client

JavaScript client is a JavaScript library that can be included on a web page, allowing website users to connect directly to the Harmony API services without any server-side processing requirements. For versions earlier than 1.8.0 please refer to the previous version of Harmony RightAddress JavaScript Client for code snippet.

For the best experience, we recommend you to use the latest versions of your favourite browsers.

• As of version 1.3.0, the Harmony RightAddress JavaScript client can be configured to use either Cross Origin Resource Sharing (CORS) or JSON with Padding (JSONP). CORS is preferable for modern browsers.

• Please note that IE 11 will no longer be supported by Microsoft after August 17th, 2021.

Code snippet

UsernamePasswordAddress Id

Copy and paste the following code snippet into your web page.

<link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/themes/smoothness/jquery-ui.css">
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js" type="text/javascript"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js" type="text/javascript"></script>
<script src="https://common.mastersoftgroup.com/scripts/harmony-2.0.1.min.js" type="text/javascript"></script>

<script>
$(function() {
    // Use the Production environment
    Harmony.useEnv(Harmony.ENV_PRODUCTION);

    Harmony.init(USERNAME, PASSWORD, Harmony.AUSTRALIA);

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

    ADDRESS_ID.autocomplete({
        // minimum number of entered characters before trying to search
        minLength:3,
        // miliseconds to wait before trying to search
        delay:500,

        source: function(request, response) {
            // call find method to get a list of candidate.
            Harmony.v2.find({ fullAddress : request.term, country: "au" }, 
                Harmony.AUPAF,
                function(data) {

                var array = [];
                if(data.status == Harmony.SUCCESS) {
                    array = $.map(data.payload, function(p) {
                        return {
                            label: p.fullAddress,
                            id: p.id
                        };
                    });
                    response(array);
                }
            });
        },
        focus: function(event, ui) {
            // prevent autocomplete from updating the textbox
            event.preventDefault();
            // manually update the textbox
            $(this).val(ui.item.label);
        },
        select: function(event, ui) {
            // prevent autocomplete from updating the textbox
            event.preventDefault();
            // call retrieve method to get additional information of the address
            Harmony.v2.retrieve({id: ui.item.id}, function(responseData) {
                $(this).val(ui.item.label);
                console.log(JSON.stringify(responseData));
            });
        }
    });
});
</script>

	

Pre-requisites

Before you can use the Harmony RightAddress client, you must make sure you have:

• An active Harmony RightAddress account

• A Harmony RightAddress username and password for your domain

• A proficiency in JavaScript

Getting the client

The versions of the JavaScript client can be downloaded using the following link:

• harmony-2.0.1.min.js
• For any earlier versions of client please contact us.

Initialising 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 initialisation, 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 service requests

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

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

    <script type="text/javascript">

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

        Harmony.v2.find({ fullAddress:"1 abc street" , country: "ca"}, null,
                function(response) {
                    var outputText = "";

                    // Check if the request was successful.
                    if (response == Harmony.SUCCESS) {

                        // Fill the output text with the single-line address results.
                        for (var i = 0; i < response.payload.length; i++) {
                            outputText += response.payload[i].fullAddress + "\n";
                        }

                    } else {

                        // Fill the output text with the error message(s).
                        for (var i = 0; i < response.messages.length; i++) {
                            outputText += response.messages[i] + "\n";
                        }

                    }

                    // Put the output text in the textarea (with id 'output')
                    document.getElementById("output").value = outputText;
                }
        );

    </script>

See the JavaScript client API v2.0.1 documentation for details on invoking the other Harmony API service methods.

JavaScript client API v2.0.1

The client library acts as a JavaScript wrapper for the Harmony RightAddress Services. The objects used by the library are JavaScript representations of those found in the Harmony RightAddress service API.

It is recommended to use the current Javascript Client Address lookup methods. However the previous version of JavaScript Client Address lookup methods is still available.

Constants

Name	Type	Description
Harmony.ENV_PREVIEW	Environment	The PREVIEW environment
Harmony.ADDRESS	Field	The single-line Address field
Harmony.ATTRIBUTES	Field	The Attributes field
Harmony.BUILDING_NAME	Field	The Building Name field
Harmony.CITY	Field	The City field
Harmony.DISTRICT	Field	The District field
Harmony.EID	Field	The Encrypted ID field
Harmony.FULL_ADDRESS	Field	The Full Address field
Harmony.ID	Field	The ID field
Harmony.LOCALITY	Field	The Locality field
Harmony.POSTAL	Field	The Postal field
Harmony.POSTCODE	Field	The Postcode field
Harmony.POSTCODE_LOCALITY	Field	The Postcode and Locality combined field
Harmony.PROVINCE	Field	The Province field
Harmony.SOURCE_OF_TRUTH	Field	The Source of Truth field
Harmony.STATE	Field	The State field
Harmony.STATE_TOWN_CITY	Field	The State and Town/City combined field
Harmony.STREET	Field	The Street field
Harmony.STREET_ADDRESS	Field	The Street Address field
Harmony.STREET_NUMBER	Field	The Street Number field
Harmony.SUBDWELLING	Field	The Subdwelling field
Harmony.SUBURB	Field	The Suburb field
Harmony.TOWN_CITY	Field	The Town/City field
Harmony.AUSTRALIA	Locale	The Australian locale
Harmony.NEW_ZEALAND	Locale	The New Zealand locale
Harmony.INTERNATIONAL	Locale	The international locale except Australian and New Zealand
Harmony.CORS	Protocol	Cross-Origin Resource Sharing (CORS) protocol
Harmony.JSONP	Protocol	JSON with Padding (JSONP) protocol
Harmony.AUPAF	Source of Truth	The Australian Postal Address Source of Truth
Harmony.AUSOTS	Source of Truth	The combined Australian Source of Truth
Harmony.GNAF	Source of Truth	The Australian Geo-coded Address Source of Truth
Harmony.NZPAF	Source of Truth	The New Zealand Postal Address Source of Truth
Harmony.NZAD	Source of Truth	It is a snapshot of addresses (at the time of the extract) that contains all addresses in New Zealand Post's National Postal Address Database (NPAD)
Harmony.ERROR	Status	The error status
Harmony.SUCCESS	Status	The success status

Methods[Back to top]

Name	Description	Since
Harmony.v2.find	Finds a list of international addresses based on the input address and country information	1.8.0
Harmony.v2.retrieve	Retrieves and provides additional data for an international address.	1.8.0
Harmony.reverseGeocode	Reverse geocode lookup for international addresses based on the input latitude and longitude. It has more options for Australia and New Zealand addresses.	1.8.0
Harmony.init	Initialises the client.	1.0.0
Harmony.useEnv	Specify the environment to use.	1.2.0
Harmony.useProtocol	Specify the connection protocol to use.	1.3.0
Harmony.useFeatureOptions	Specify the feature options value to use.	1.4.0
Harmony.Parse.address	Parses a free-form address string.	1.1.0
Harmony.International.reverseGeocode	International reverseGeocode lookup based on the input latitude and longitude.	1.8.0
Harmony.International.getGeocode	Retrieves and provides geocode information for international addresses.	1.8.0
Harmony.Validate.email	Validates an email address.	1.2.0
Harmony.Validate.phone	Validates a mobile phone number.	1.2.0
Harmony.Company.abn	Look up ABN.	1.6.0

Harmony.v2.find(address, sourceOfTruth, callback)[Back to top]

Invokes the find service.

address

Type: AddressThe input Address object.

sourceOfTruth

Type: StringThe Source of Truth to use for overriding default SOT for Australia or New Zealand address lookup. It is Optional.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example performs a single-line address search for '1 abc street' in Canada:

	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]);
					...
				}
				
			}
		}
	);
	

Harmony.v2.retrieve(address, callback)[Back to top]

Invokes the retrieve service.

address

Type: AddressThe input Address object.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example identifies the input address with id of the address from the above find API.

	Harmony.v2.retrieve({ id: "xx|xx|xxx"},
		function(response) {
			if (response.status == Harmony.SUCCESS) {
			
				// Do something with the response payload.
				var result = response.payload[0];
				...
			} else {
			
				// Show any error messages.
				for (var i = 0; i < response.messages.length; i++) {
					alert(response.messages[i]);
					...
				}
				
			}
		}
	);
	

Harmony.reverseGeocode(address, sourceOfTruth, callback)[Back to top]

Invokes the combined reverseGeo service to get addresses with input latitude and longitude

address

Type: AddressThe input Address object.

sourceOfTruth

Type: StringIt is optional for Australia and New Zealand. If value is specified it will only reverse geocode lookup for this country only.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example performs a combined reverseGeocode lookup:

	Harmony.reverseGeocode({"latitude": "xxx", "longitude": "xxx"}, 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]);
					...
				}
				
			}
		}
	);
	

Harmony.init(username, password, locale)[Back to top]

Initialises the client.

username

Type: StringThe username used to connect to Harmony RightAddress.

password

Type: StringThe password used to connect to Harmony RightAddress.

locale

Type: StringThe locale used when connecting to Harmony RightAddress.

The following example initialises the Harmony client with the credentials 'bob'/'password' and the Australian locale:

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

Harmony.useEnv(environment)[Back to top]

Specifies the non-production service environment to be used for the requests. The default environment is Production.

environment

Type: StringThe non-production service environment to use.

The following example configures the Harmony client to use the PREVIEW environment:

    Harmony.useEnv(Harmony.ENV_PREVIEW);
    

Harmony.useProtocol(protocol)[Back to top]

Specifies the protocol to be used for the service requests. The default protocol is Cross-Origin Resource Sharing (CORS).

protocol

Type: StringThe protocol to use.

The following example configures the Harmony client to use the JSONP protocol over GET requests:

    Harmony.useProtocol(Harmony.JSONP);
    

Harmony.useFeatureOptions(featureOptions)[Back to top]

Specifies the FeatureOptions value when invoking the address lookup REST service methods.

featureOptions

Type: String or FeatureOptionThe option values when invoking the address lookup REST service methods. Only need to specify it if you want a different value from the default value.

The following example configures feature options for address lookup service methods:(Only need to specify the option value if want a different value from system default)

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

Harmony.Parse.address(address, callback)[Back to top]

Invokes the address parse service.

address

Type: String or AddressThe input address String or the input Address object. The Address object input only available for harmony.min.js since version 1.6.0.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example parses the input address '220 george street, sydney 2000' as a String:

    Harmony.Parse.address("220 george street, sydney 2000", 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

The following example parses the input address '220 george street, sydney 2000' in an Address object (only available for harmony.min.js since version 1.6.0):

    Harmony.Parse.address({ fullAddress: "220 george street, sydney 2000" }, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.International.reverseGeocode(address, callback)[Back to top]

Invokes the international reverseGeo service to get addresses with input latitude and longitude

address

Type: AddressThe input Address object.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example performs the international reverseGeocode lookup:

	Harmony.reverseGeocode({"latitude": "xxx", "longitude": "xxx"},
		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]);
					...
				}
				
			}
		}
	);
	

Harmony.International.getGeocode(address, callback)[Back to top]

Invokes the internationalGeocode service.

address

Type: AddressThe input Address object.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example get geocode information for an Australia Address:

	Harmony.International.getGeocode({"fullAddress":"28 station st E,Harris park nsw 2150",  "country":"Australia"},
		function(response) {
			if (response.status == Harmony.SUCCESS) {
				// Do something with the response payload.
				var resultGeocode = response.payload[0];
				...
				
			} else {
			
				// Show any error messages.
				for (var i = 0; i < response.messages.length; i++) {
					alert(response.messages[i]);
					...
				}
				
			}
		}
	);
	

Harmony.Validate.email(emailAddress, sourceOfTruth, callback)[Back to top]

Invokes the email validate service.

emailAddress

Type: String or EmailAddressThe input email address as a String or the input EmailAddress object. The EmailAddress object input only available for harmony.min.js since version 1.6.0.

sourceOfTruth

Type: StringThe Source of Truth to use for the validation - optional. The default Source of Truth is VE_ALL.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example performs a validation on the email address '[e-mail]' as a String in VE_ALL Source of Truth:

    Harmony.Validate.email("[e-mail]", "VE_ALL",
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

The following example performs a validation on the email address '[e-mail]' in an EmailAddress object in VE_ALL Source of Truth (only available for harmony.min.js since version 1.6.0.):

    Harmony.Validate.email( {address: "[e-mail]" }, "VE_ALL",
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.Validate.phone(phone, callback)[Back to top]

Invokes the phone validate service.

phone

Type: PhoneThe input phone object containing a number and country code.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example performs a validation on the mobile phone number '0412341234' for Australia:

    Harmony.Validate.phone({ fullPhone: "0412341234", country: "AU" }, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.Company.abn(company, apiName, optionalConfig, guid, callback)[Back to top]

Invokes the Company Lookup/Validate service. The following are the explanations of the parameters used. Please refer to CompanyRestRequest for more details.

company

Type: StringThe input company name for lookup/validation

apiName

Type: StringThe name of the API used for lookup, for example "SearchByABNv201408", "SearchByASICv201408", and etc.

optionalConfig

Type: StringThe optional configuration

guid

Type: StringYou only need to specify this value if you want to use your own guid, otherwise, use null or empty string as the value.

callback

Type: FunctionThe function that will be invoked when the service response is received.

The following example performs a lookup on the company name 'mastersoft':

    Harmony.Company.abn("mastersoft", "", "", "", 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );