Address Objects

AddressAu Australian Address.
AddressNz New Zealand Address.
AddressList Address container.
AddressRestRequest Request wrapper for address REST methods.
AddressRestResponse Response wrapper for address REST methods.
FeatureOption Options applied for each request.

AddressAu

The AddressAu object is used when sending and receiving data from the address lookup API methods using Australian Sources of Truth (SoTs).

eid

Type: String The encrypted ID (e.g. 'fGBUVVdCntAu6wgNVcv0ePuSac7kAbUP').

fullAddress

Type: String The concatenated address (e.g. 'SE 202 220 George St, Sydney, NSW 2000').

country

Type: String Not currently implemented.

state

Type: String The abbreviated State component of the address (e.g. 'NSW').

postcode

Type: String The Postcode component of the address (e.g. '2000').

locality

Type: String The Locality component of the address (e.g. 'NORTH SYDNEY').

street

Type: String The Street component of the address (e.g. 'GEORGE STREET').

postal

Type: String The Postal address (e.g. 'PO BOX 123').

postalNumber

Type: String The Postal Number component of the Postal address (e.g. '123').

postalType

Type: String The Postal Type component of the Postal address (e.g. 'PO BOX').

streetNumber

Type: String The Street Number component of the address (e.g. '45A').

streetName

Type: String The Street Name component of the address (e.g. 'GEORGE').

streetType

Type: String The Street Type component of the address (e.g. 'STREET').

streetSuffix

Type: String The Street Suffix component of the address (e.g. 'E').

buildingName

Type: String The Building Name component of the address (e.g. 'ANZAC HOUSE').

subdwelling

Type: String The Subdwelling component of the address (e.g. 'SE 202'). This includes subdwelling, floor, block and lot information.

flatUnitNumber

Type: String The Flat Unit Number component of the address (e.g. '7A').

flatUnitType

Type: String The Flat Unit Type component of the address (e.g. 'U').

floorLevelNumber

Type: String The Floor Level Number component of the address (e.g. '2').

floorLevelType

Type: String The Floor Level Type component of the address (e.g. 'FL').

lotNumber

Type: String The Lot Number component of the address (e.g. '1').

attributes

Type: Map A map of name/value pairs representing additional information from the Address in the Source of Truth (e.g. '{"Longitude": "12.34", "Latitude": "12.34" }).

For example, sample attributes returned from "AUPAF" are shown below: {"Barcode":"1301012101021000002110322210012201313","Bsp":"015","DPID":"71230073"}

Sample attributes returned from "GNAF" are shown below: {"GNAFConfidence":"0","ParcelID":"1//DP75111","GNAFPointPID":"GANSW718616256", "MeshblockId":"10743811000","Latitude":"-33.86307089", "GNAFPID":"GANSW718616256","Longitude":"151.20781474", "GNAFReliability":"2","GNAFLocalityPID":"NSW3749", "GNAFGroupPID":"NSW2845405","GeocodeLevel":"7"}

Sample attributes are shown below, if "GNAF Plus" is active: {"GNAFConfidence": "0","ParcelID": "CANB/BRAD/7/9/","GNAFPointPID": "GAACT718021569", "MeshblockId": "80003983000","Latitude": "-35.26134209", "GNAFPID": "GAACT718021569","Longitude": "149.13239137", "GNAFReliability": "2","GNAFLocalityPID": "ACT106", "GNAFGroupPID": "ACT346","GeocodeLevel": "7", "GNAFPIDPosition": "DOORSTOP","area_sqkm": "0.0468", "state_name": "AUSTRALIAN CAPITAL TERRITORY","state_code": "8", "lga_name": "UNINCORPORATED ACT","lga_code": "89399", "gcc_sa_name": "AUSTRALIAN CAPITAL TERRITORY","gcc_sa_code": "8ACTE", "ced_name": "FENNER","ced_code": "802", "sed_name": "KURRAJONG","sed_code": "80003", "sa1_code_7d": "8105118","sa1_code_main": "80105105118", "sa2_name": "BRADDON","sa2_code_main": "801051051","sa2_code_5d": "81051", "sa3_name": "NORTH CANBERRA","sa3_code": "80105", "sa4_name": "AUSTRALIAN CAPITAL TERRITORY","sa4_code": "801"}

JSON Representation


    {
        "eid": "fGBUVVdCntAu6wgNVcv0ePuSac7kAbUP",
        "exception": null,
        "fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
        "country": null,
        "state": "NSW",
        "postcode": "2000",
        "locality": "SYDNEY",
        "street": "GEORGE ST",
        "postal": "",
        "postalNumber": "",
        "postalType": "",
        "streetNumber": "220",
        "streetName": "GEORGE",
        "streetType": "ST",
        "streetSuffix": "",
        "buildingName": "",
        "subdwelling": "L 2 SE 202",
        "flatUnitNumber": "202",
        "flatUnitType": "SE",
        "floorLevelNumber": "2",
        "floorLevelType": "L",
        "lotNumber": "",
        "attributes": {
            "Barcode": "1301012101021000002110322210012201313",
            "Bsp": "015",
            "DPID": "12345678"
        },
        "id": "12345678"
    }

AddressNz

The AddressNz object is used when sending and receiving data from the address lookup API methods using New Zealand Sources of Truth (SoTs).

eid

Type: String The encrypted ID (e.g. 'O4zqtEf98jsqhJwoNG+0S/DCFUGzuGGH').

fullAddress

Type: String The concatenated address (e.g. '20 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011').

country

Type: String Not currently implemented

postcode

Type: String The Postcode component of the address (e.g. '6011').

townCity

Type: String The Town/City component of the address (e.g. 'WELLINGTON').

suburb

Type: String The Suburb component of the address (e.g. 'WELLINGTON CENTRAL').

street

Type: String The Street component of the address (e.g. 'PANAMA STREET').

postal

Type: String The Postal address (e.g. 'PO BOX 123').

postalNumber

Type: String The Postal Number component of the Postal address (e.g. '123').

postalType

Type: String The Postal Type component of the Postal address (e.g. 'PO BOX').

streetNumber

Type: String The Street Number component of the address (e.g. '45A').

streetName

Type: String The Street Name component of the address (e.g. 'PANAMA').

streetType

Type: String The Street Type component of the address (e.g. 'STREET').

streetSuffix

Type: String The Street Suffix component of the address (e.g. 'E').

buildingName

Type: String The Building Name component of the address (e.g. 'ALBERT PLAZA').

subdwelling

Type: String The Subdwelling component of the address (e.g. 'SE 202'). This includes subdwelling, floor, block and lot information.

flatUnitNumber

Type: String The Flat Unit Number component of the address (e.g. '7A').

flatUnitType

Type: String The Flat Unit Type component of the address (e.g. 'U').

floorLevelNumber

Type: String The Floor Level Number component of the address (e.g. '2').

floorLevelType

Type: String The Floor Level Type component of the address (e.g. 'FL').

lotNumber

Type: String The Lot Number component of the address (e.g. '1').

attributes

Type: Map A map of name/value pairs representing additional information from the Address in the Source of Truth (e.g. '[ "Longitude": "12.34", "Latitude": "12.34" ]).

For example, sample attributes returned from "NZPAF" are shown below: {"ParcelId":"3996917","XCoordinate":"2658827", "MeshblockId":"2127500","YCoordinate":"5989553", "Latitude":"-41.287171091075614","Longitude":"174.7770385563209"}

JSON Representation


    {
        "eid": "DmQYwqF0wjGOgn2XZYMJbvLPHFLYXJEu",
        "exception": null,
        "id": "123456",
        "fullAddress": "25 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011",
        "country": null,
        "postcode": "6011",
        "townCity": "WELLINGTON",
        "suburb": "WELLINGTON CENTRAL",
        "street": "PANAMA STREET",
        "street2": null,
        "postal": "",
        "postalNumber": "",
        "postalType": "",
        "streetNumber": "25",
        "streetName": "PANAMA",
        "streetType": "STREET",
        "streetSuffix": "",
        "buildingName": "",
        "subdwelling": "",
        "flatUnitNumber": "",
        "flatUnitType": "",
        "floorLevelNumber": "",
        "floorLevelType": "",
        "lotNumber": "",
        "rdNumber": null,
        "attributes": {
            "Latitude": "-41.284123",
            "Longitude": "174.776194",
            "MeshblockId": "2125700",
            "ParcelId": "4032109",
            "XCoordinate": "2658764",
            "XNztm": "1748740.49107",
            "YCoordinate": "5989893",
            "YNztm": "5428180.430423"
        }
    }

AddressList

An array or list of Address (AddressAu or AddressNz) structures.

JSON Representation


    [
	    {
	        "eid": "DmQYwqF0wjGOgn2XZYMJbvLPHFLYXJEu",
	        "exception": null,
	        "id": "123456",
	        "fullAddress": "25 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011",
	        "country": null,
	        "postcode": "6011",
	        "townCity": "WELLINGTON",
	        "suburb": "WELLINGTON CENTRAL",
	        "street": "PANAMA STREET",
	        "street2": null,
	        "postal": "",
	        "postalNumber": "",
	        "postalType": "",
	        "streetNumber": "25",
	        "streetName": "PANAMA",
	        "streetType": "STREET",
	        "streetSuffix": "",
	        "buildingName": "",
	        "subdwelling": "",
	        "flatUnitNumber": "",
	        "flatUnitType": "",
	        "floorLevelNumber": "",
	        "floorLevelType": "",
	        "lotNumber": "",
	        "rdNumber": null,
	        "attributes": {
	            "Latitude": "-41.284123",
	            "Longitude": "174.776194",
	            "MeshblockId": "2125700",
	            "ParcelId": "4032109",
	            "XCoordinate": "2658764",
	            "XNztm": "1748740.49107",
	            "YCoordinate": "5989893",
	            "YNztm": "5428180.430423"
	        }
	    },
	    {
	        "eid": "fGBUVVdCntAu6wgNVcv0ePuSac7kAbUP",
	        "exception": null,
	        "fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
	        "country": null,
	        "state": "NSW",
	        "postcode": "2000",
	        "locality": "SYDNEY",
	        "street": "GEORGE ST",
	        "postal": "",
	        "postalNumber": "",
	        "postalType": "",
	        "streetNumber": "220",
	        "streetName": "GEORGE",
	        "streetType": "ST",
	        "streetSuffix": "",
	        "buildingName": "",
	        "subdwelling": "L 2 SE 202",
	        "flatUnitNumber": "202",
	        "flatUnitType": "SE",
	        "floorLevelNumber": "2",
	        "floorLevelType": "L",
	        "lotNumber": "",
	        "attributes": {
	            "Barcode": "1301012101021000002110322210012201313",
	            "Bsp": "015",
	            "DPID": "12345678"
	        },
	        "id": "12345678"
	    },
	    ...
    ]

AddressRestRequest

An AddressRestRequest object is used when invoking the Harmony RightAddress address lookup REST service methods.

payload

Type: AddressList The list of Address structures being passed to the REST service method.

sourceOfTruth

Type: String The Source of Truth (SoT) to use during the REST service method invocation (i.e. 'AUPAF', 'GNAF', 'NZPAF' or 'NZAD').

featureOptions

Type: FeatureOption An Object containing the values for the feature options available for Address lookups.

JSON Representation


    {
        "payload": [ { "locality": "SYDNEY" } ],
        "sourceOfTruth": "GNAF",
        "featureOptions": { "positionFilter": "postal" }
    }

AddressRestResponse

An AddressRestResponse object is returned from the Harmony RightAddress address lookup REST service method invocations.

payload

Type: AddressList The list of Address structures being returned from the REST service method.

status

Type: String The status of the request (i.e. 'SUCCESS' or 'ERROR').

messages

Type: String[] Any error messages generated during the REST service method invocation (e.g. '[ "Access is denied" ]')

JSON Representation


    {
        "status": "SUCCESS",
        "messages": [],
        "payload": [
            {
                "fullAddress": "SYDNEY NSW 2000",
                "country": null,
                "state": "NSW",
                "postcode": "2000",
                "locality": "SYDNEY",
                "street": "",
                "postal": "",
                "postalNumber": "",
                "postalType": "",
                "streetNumber": "",
                "streetName": "",
                "streetType": "",
                "streetSuffix": "",
                "buildingName": "",
                "subdwelling": "",
                "flatUnitNumber": "",
                "flatUnitType": "",
                "floorLevelNumber": "",
                "floorLevelType": "",
                "lotNumber": ""
            },
            {
                "fullAddress": "SYDNEY OLYMPIC PARK NSW 2127",
                "country": null,
                "state": "NSW",
                "postcode": "2127",
                "locality": "SYDNEY OLYMPIC PARK",
                "street": "",
                "postal": "",
                "postalNumber": "",
                "postalType": "",
                "streetNumber": "",
                "streetName": "",
                "streetType": "",
                "streetSuffix": "",
                "buildingName": "",
                "subdwelling": "",
                "flatUnitNumber": "",
                "flatUnitType": "",
                "floorLevelNumber": "",
                "floorLevelType": "",
                "lotNumber": ""
            }
        ]
    }

FeatureOption

A FeatureOption object is used to supply option values when invoking the Harmony RightAddress address lookup REST service methods.

The displayGnafLot option is only applicable to the GNAF Source of Truth.

The positionFilter option has two types of filters: point filters (when a specific address is retrieved) and locality filters (where a locality-level address is retrieved).

Point filters are used for the following methods:

The option values available for point filters are:

  • POSTAL - filters only postal addresses (only available for the address method)
  • ROOFTOP - filters only addresses that contain one or more subdwelling addresses (e.g. unit blocks) - the subdwelling addresses are not included
  • DOORSTOP - filters subdwelling addresses within 'ROOFTOP' addresses (e.g. units within a unit block) - the 'ROOFTOP' addresses are not included
  • SINGLE - filters addresses that represent a single address with no subdwellings (e.g. houses)

Locality filters are used for the following methods:

The option values available for locality filters are:

  • PHYSICAL - filters localities that do not contain any addresses with a 'postal' type
  • POSTAL - filters localities that only contain addresses with a 'postal' type
  • BOTH - filters localities that contain at least one 'postal' address and one 'non-postal' address

The addressTypeFilter option is to filter the result based on the type of delivery point in NZPAF and NZAD. It is used for address method for NZPAF and NZAD Source of Truth.

The option values available for Address Type filters are:

  • URBAN - filters only Urban Delivery Addresses
  • BOX - filters only PO Box Addresses
  • BAG - filters only Private Bag Addresses
  • RURAL - filters only Rural Delivery Addresses
  • COUNTER - filters only Counter Delivery Addresses - PostShops, etc
  • CMB URBAN - filters only Community MailBox Urban Addresses
  • CMB RURAL - filters only Community MailBox Rural Addresses

There is an option to exclude Address Types by using "-" followed by the Address Type value to be excluded. For example { "addressTypeFilter": "-urban, -rural" } to exclude "URBAN" and "RURAL" addresses from the result.

displayGnafLot

Type: ("0"|"1") Flag which determines if the lot information is displayed in addresses retrieved from the GNAF Source of Truth. If the flag is set to "1", the lot information will be returned. Otherwise, the lot information will not be returned.

displayTrueLocality

Type: ("0"|"1") Flag which determines whether to use the true locality or the synonym locality in the lookup result. If the flag is set to "1", the true locality will be returned. Otherwise, the synonym locality will be returned.

positionFilter

Type: Array The array of filters to be applied to the lookup result - for AU locale only.

addressTypeFilter

Type: Array The array of filters to be applied to the lookup result - for NZ locale only.

singleLineHitNumber

Type: Integer The maximum number of results returned from the lookup. Note, modifying this value may impact the performance of the lookup.

caseType

Type: ("LOW"|"UP"|"TITLE") The case type for the returned addresses (single line and components). If "TITLE" is used, the returned address will be in "title" case except the Australian state abbreviation. For example: "220 George St, Sydney, NSW"

exposeAttributes

Type: Integer (0-7) Flag which determines which attributes to expose for the lookups.
  • If it is "1"(001), it will expose all the default original attributes.
  • If it is "2"(010), it will expose GNAFPlus attributes.
  • If it is "4"(100), it will expose extra AUPAF permission and delivery schedule attributes.
  • The value can be added up for different combinations of attributes exposure. e.g. if it is "3" (001+010=011(3)), it will expose all the default original attributes + GNAFPlus attributes.
  • This option can be used for Address Methods and Cleanse Methods
  • exposePhantom

    Type: ("0"|"1") Flag which determines whether to expose phantom addresses for AUPAF address lookup. If the flag is set to "1", it will expose phantom address. Otherwise it will not.

    baseSource

    Type: ("GNAF"|"AUPAF") Flag is used in together with SourceOfTruth as AUSOTS. It determines which data source is used as the base for the search result. Additional information from the other source (if available) is added to the addresses from base result. Some addresses may not be found from the base result given the top number but they may be found from the other source. In this case, these addresses are appended to the result list with additional information from the base source (if available).

    strictFieldValidation

    Type: ("0"|"1") This option is only effective when the request payload has values for field state, locality, or postcode in addition to fullAddress. The default value is "1" which means it strictly limits the results in the response to the requested values for field such as state, locality or postcode. When this option is set to "0", it prioritizes the reseults with requested values in the response but it still includes other search results.

    standardizeSource

    Type: ("AUPAF"|"GNAF"|"NZPAF") The source used to standardize result fields such as Street Type, Flat Unit Type, Floor Level Type, Street Suffix Type and Postal Type.

    splitNzFloorLevel

    Type: ("0"|"1") If the flag is set to "1", the floor information will be splitted into "floorLevelType" and "floorLevelNumber". The flag is only available when using with "NZPAF", and will be ignored when using with other sources. The default value is "0".

    groupAddresses

    Type: ("0"|"1") A flag to control wheter addresses are grouped together or not for "AUPAF". If the flag is set to "1", the service will try to collapse sub-dwelling addresses within the same primary address into a group to reduce clutter. This option is only used for address method with AUPAF at the moment. The default value is "0". The new Javascript client (since version 1.7.0) supports this feature.

    radius

    Type: Integer Distance(m) from the origin to search. It is used by reverseGeocode API and the default value is 100(m). The new Javascript client (since version 1.7.0) supports this feature.

    JSON Representation

    
        {
            "displayGnafLot": 1,
            "singleLineHitNumber": 30,
            "displayTrueLocality": 1,
            "positionFilter": "postal,doorstop,rooftop,single",
            "addressTypeFilter": "urban,box,bag,rural,counter,cmb urban,cmb rural",
            "caseType":"TITLE",
            "exposeAttributes":"1",
            "exposePhantom":"0",
            "baseSource":"AUPAF",
            "standardizeSource":"GNAF",
            "splitNzFloorLevel": 1
        }