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.

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.address Lookup addresses using a single-line input address. 1.0.0
Harmony.buildingName Lookup building names. 1.0.0
Harmony.init Initialises the client. 1.0.0
Harmony.locality Lookup localities. 1.0.0
Harmony.postal Lookup postal addresses. 1.0.0
Harmony.postcode Lookup postcode/locality combinations. 1.0.0
Harmony.street Lookup streets. 1.0.0
Harmony.streetNumber Lookup street numbers. 1.0.0
Harmony.subdwelling Lookup subdwellings. 1.0.0
Harmony.suburb Lookup suburbs. 1.0.0
Harmony.townCity Lookup towns and cities. 1.0.0
Harmony.transaction Indicate a transaction has been completed. 1.1.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.Types.floorLevel Lists the floor-level type data. 1.0.0
Harmony.Types.postal Lists the postal type data. 1.0.0
Harmony.Types.street Lists the street type data. 1.0.0
Harmony.Types.streetSuffix Lists the floor-level type data. 1.0.0
Harmony.Types.unitFlat Lists the floor-level type data. 1.0.0
Harmony.Extensions.identify Retrieves and provides additional data for an address. 1.1.0
Harmony.International.address Lookup international addresses using a single-line input address. 1.6.5
Harmony.International.identify Retrieves and provides additional data for an international address. 1.6.5
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.address(address, sourceOfTruth, callback)

Invokes the address service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

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 the AUPAF Source of Truth:


    Harmony.address({ fullAddress: "1 abc street" }, Harmony.AUPAF, 
            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.buildingName(address, sourceOfTruth, callback)

Invokes the buildingName service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for building names beginning with 'anz':


    Harmony.buildingName({ buildingName: "anz" }, Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

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.locality(address, sourceOfTruth, callback)

Invokes the locality service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for localities beginning with 'syd':


    Harmony.locality({ locality: "syd" }, Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.postal(address, sourceOfTruth, callback)

Invokes the postal service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for postal addresses in the 'Sydney' locality (postcode '2001') beginning with 'gpo box 1':


    Harmony.postal({ postcode: "2001", locality: "sydney", postal: "gpo box 1" }, 
            Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.postcode(address, sourceOfTruth, callback)

Invokes the postcode service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for locality/postcode combinations for the postcode '2000':


    Harmony.postcode({ postcode: "2000" }, Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.street(address, sourceOfTruth, callback)

Invokes the street service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for streets in the locality 'sydney' (with postcode '2000') beginning with 'geor':


    Harmony.street({ postcode: "2000", locality: "sydney", street: "geor" }, 
            Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.streetNumber(address, sourceOfTruth, callback)

Invokes the streetNumber service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for street numbers in the locality 'sydney' (with postcode '2000') on the street 'george st' beginning with '22':


    Harmony.streetNumber(
            { 
                postcode: "2000", 
                locality: "sydney", 
                street: "george st", 
                streetNumber: "22" 
            }, 
            Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.subdwelling(address, sourceOfTruth, callback)

Invokes the subdwelling service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for subdwellings in the locality 'sydney' (with postcode '2000') at number '220 on the street 'george st' beginning with '202':


    Harmony.subdwelling(
            { 
                postcode: "2000", 
                locality: "sydney", 
                street: "george st", 
                streetNumber: "220",
                subdwelling: "202" 
            }, 
            Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.suburb(address, sourceOfTruth, callback)

Invokes the suburb service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for suburbs beginning with 'wellin':


    Harmony.suburb({ suburb: "wellin" }, Harmony.NZPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.townCity(address, sourceOfTruth, callback)

Invokes the townCity service.

address

Type: Address The input Address object.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example performs a search for towns and cities beginning with 'wellin':


    Harmony.townCity({ townCity: "wellin" }, Harmony.NZPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.transaction()

Invokes the transaction service.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example invokes transaction with no callback:


    Harmony.transaction(Harmony.AUPAF);
    

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.Types.floorLevel(sourceOfTruth, callback)

Invokes the floorLevel types service.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example retrieves the floor level types:


    Harmony.Types.floorLevel(Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.Types.postal(sourceOfTruth, callback)

Invokes the postal types service.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example retrieves the postal types:


    Harmony.Types.postal(Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.Types.street(sourceOfTruth, callback)

Invokes the street types service.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example retrieves the street types:


    Harmony.Types.street(Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.Types.streetSuffix(sourceOfTruth, callback)

Invokes the streetSuffix types service.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example retrieves the street suffix types:


    Harmony.Types.streetSuffix(Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.Types.unitFlat(sourceOfTruth, callback)

Invokes the unitFlat types service.

sourceOfTruth

Type: String The Source of Truth to use for the lookup.

callback

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

The following example retrieves the unit/flat types:


    Harmony.Types.unitFlat(Harmony.AUPAF, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.Extensions.identify(address, callback)

Invokes the identify extension 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 EID 'wAcKtCUXx5glttrgaxxY1l6S5LEZrjIE':


    Harmony.Extensions.identify({ eid: "wAcKtCUXx5glttrgaxxY1l6S5LEZrjIE" }, 
            function(response) {
                
                // Perform any action with the response
                ...

            }
    );
    

Harmony.International.address(address, callback)

Invokes the international address lookup 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 performs a single-line address search for '1 abc street' in Canada:


    Harmony.International.address({ fullAddress: "1 abc street", country: "CA"}, 
            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.identify(address, callback)

Invokes the international address 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 'CA|CP|A|494524':


    Harmony.International.identify({ id: "CA|CP|A|494524"}, 
            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.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
                ...

            }
    );