# Javascript Library v2.1.0

## Getting Started

### Prerequisites

1. Harmony API Account.
2. We strongly recommend [Allowlisting your domain](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains.md) 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](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains.md).

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.

```javascript
    <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.

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

```javascript
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](#jsaddfield)           | 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](#jsaddresslookup) | Single-line address lookup on the supplied `input` element.                                                                                                                                           | 2.0.0 |

### HarmonyJS.addField(field, element, index) <a href="#jsaddfield" id="jsaddfield"></a>

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:

```javascript
    // 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) <a href="#jsaddresslookup" id="jsaddresslookup"></a>

Creates single-line address lookup with [the current Address lookup APIs ](/loqate-harmony-api/api-specification/address/address-validation-and-lookup.md)on the supplied `input` and `country` elements. It returns the response from [find](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraFind) service and the callback is available via `onSelect` option.

For [retrieve ](/loqate-harmony-api/api-specification/address/address-validation-and-lookup.md#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`:

```javascript
    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 <a href="#jscodesnippet" id="jscodesnippet"></a>

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](/loqate-harmony-api/guides/sign-up-login.md).

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

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


---

# 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/client-libraries/javascript-library-v2.1.0.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.