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:

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

NameTypeDescription

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]

NameDescriptionSince

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 'bob@example.org' as a String in VE_ALL Source of Truth:

    Harmony.Validate.email("bob@example.org", "VE_ALL",
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );

The following example performs a validation on the email address 'bob@example.org' 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: "bob@example.org" }, "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
                ...

            }
    );
PreviousHarmony RightAddress cURL exampleNextDeprecated JQuery Library v1.8.1

Last updated