# Deprecated JS Library v2.0.1

{% hint style="warning" %}
This method has been deprecated. Please use current version for new implementations.
{% endhint %}

## 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 ](https://developer.mastersoftgroup.com/harmony/client/js/v1/index.html)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](http://common.mastersoftgroup.com/scripts/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 ](#harmony-rightaddress-javascript-client-api)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](https://developer.mastersoftgroup.com/harmony/api/).

**It is recommended to use the current Javascript Client Address lookup methods.** However [the previous version of JavaScript Client Address lookup methods](https://developer.mastersoftgroup.com/harmony/client/js/v1/api.html) 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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)

| Name                                                                                                                                 | Description                                                                                                                                                | Since |
| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| [Harmony.v2.find](https://developer.mastersoftgroup.com/harmony/client/js/api.html#v2Find)                                           | Finds a list of international addresses based on the input address and country information                                                                 | 1.8.0 |
| [Harmony.v2.retrieve](https://developer.mastersoftgroup.com/harmony/client/js/api.html#v2Retrieve)                                   | Retrieves and provides additional data for an international address.                                                                                       | 1.8.0 |
| [Harmony.reverseGeocode](https://developer.mastersoftgroup.com/harmony/client/js/api.html#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](https://developer.mastersoftgroup.com/harmony/client/js/api.html#init)                                                | Initialises the client.                                                                                                                                    | 1.0.0 |
| [Harmony.useEnv](https://developer.mastersoftgroup.com/harmony/client/js/api.html#useEnv)                                            | Specify the environment to use.                                                                                                                            | 1.2.0 |
| [Harmony.useProtocol](https://developer.mastersoftgroup.com/harmony/client/js/api.html#useProtocol)                                  | Specify the connection protocol to use.                                                                                                                    | 1.3.0 |
| [Harmony.useFeatureOptions](https://developer.mastersoftgroup.com/harmony/client/js/api.html#useFeatureOptions)                      | Specify the feature options value to use.                                                                                                                  | 1.4.0 |
| [Harmony.Parse.address](https://developer.mastersoftgroup.com/harmony/client/js/api.html#parseAddress)                               | Parses a free-form address string.                                                                                                                         | 1.1.0 |
| [Harmony.International.reverseGeocode](https://developer.mastersoftgroup.com/harmony/client/js/api.html#internationalReverseGeocode) | International reverseGeocode lookup based on the input latitude and longitude.                                                                             | 1.8.0 |
| [Harmony.International.getGeocode](https://developer.mastersoftgroup.com/harmony/client/js/api.html#internationalGetGeocode)         | Retrieves and provides geocode information for international addresses.                                                                                    | 1.8.0 |
| [Harmony.Validate.email](https://developer.mastersoftgroup.com/harmony/client/js/api.html#validateEmail)                             | Validates an email address.                                                                                                                                | 1.2.0 |
| [Harmony.Validate.phone](https://developer.mastersoftgroup.com/harmony/client/js/api.html#validatePhone)                             | Validates a mobile phone number.                                                                                                                           | 1.2.0 |
| [Harmony.Company.abn](https://developer.mastersoftgroup.com/harmony/client/js/api.html#abn)                                          | Look up ABN.                                                                                                                                               | 1.6.0 |

### Harmony.v2.find(address, sourceOfTruth, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#v2find" id="v2find"></a>

Invokes the [find](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraFind) 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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#v2retrieve" id="v2retrieve"></a>

Invokes the [retrieve](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraRetrieve) 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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#reversegeocode" id="reversegeocode"></a>

Invokes the [combined reverseGeo](https://developer.mastersoftgroup.com/harmony/api/method/reverse-geocode.html#combined) 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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#init" id="init"></a>

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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#useenv" id="useenv"></a>

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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#useprotocol" id="useprotocol"></a>

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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#usefeatureoptions" id="usefeatureoptions"></a>

Specifies the [FeatureOptions](https://developer.mastersoftgroup.com/harmony/api/object/address.html#FeatureOption) 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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#parseaddress" id="parseaddress"></a>

Invokes the [address](https://developer.mastersoftgroup.com/harmony/api/method/parse.html#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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#internationalreversegeocode" id="internationalreversegeocode"></a>

Invokes the [international reverseGeo](https://developer.mastersoftgroup.com/harmony/api/method/reverse-geocode.html#international) 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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#internationalgetgeocode" id="internationalgetgeocode"></a>

Invokes the [internationalGeocode](https://developer.mastersoftgroup.com/harmony/api/method/address.html#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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#validateemail" id="validateemail"></a>

Invokes the [email](https://developer.mastersoftgroup.com/harmony/api/method/validate.html#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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#validatephone" id="validatephone"></a>

Invokes the [phone](https://developer.mastersoftgroup.com/harmony/api/method/validate.html#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\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top) <a href="#abn" id="abn"></a>

Invokes the [Company Lookup/Validate](https://developer.mastersoftgroup.com/harmony/api/method/validate.html#auCompanyLookup) service. The following are the explanations of the parameters used. Please refer to [CompanyRestRequest](https://developer.mastersoftgroup.com/harmony/api/object/validate.html#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
                ...

            }
    );
    
```


---

# 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/loqate-harmony-api/integrations/deprecated-integrations/deprecated-js-library-v2.0.1.md?ask=<question>
```

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.