Harmony RightAddress JavaScript client API

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

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)

Invokes the find service.

address

Type: Address The input Address object.

sourceOfTruth

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

callback

Type: Function The 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)

Invokes the retrieve service.

address

Type: Address The input Address object.

callback

Type: Function The 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)

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

address

Type: Address The input Address object.

sourceOfTruth

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

callback

Type: Function The 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)

Initialises the client.

username

Type: String The username used to connect to Harmony RightAddress.

password

Type: String The password used to connect to Harmony RightAddress.

locale

Type: String The 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)

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

environment

Type: String The 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)

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

protocol

Type: String The 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)

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

featureOptions

Type: String or FeatureOption The 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)

Invokes the address parse service.

address

Type: String or Address The 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: Function The 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)

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

address

Type: Address The input Address object.

callback

Type: Function The 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)

Invokes the internationalGeocode service.

address

Type: Address The input Address object.

callback

Type: Function The 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)

Invokes the email validate service.

emailAddress

Type: String or EmailAddress The 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: String The Source of Truth to use for the validation - optional. The default Source of Truth is VE_ALL.

callback

Type: Function The 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)

Invokes the phone validate service.

phone

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

callback

Type: Function The 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)

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

company

Type: String The input company name for lookup/validation

apiName

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

optionalConfig

Type: String The optional configuration

guid

Type: String You 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: Function The 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
                ...

            }
    );