Address Objects
We have three different types of objects suited to primary business regions being Australia, New Zealand and International (rest of world).
Address Objects
Objects that are part of every response object | |
Australian Address. | |
New Zealand Address. | |
An Australian address for validation. | |
A New Zealand address for validation. | |
International Address. | |
International Address with | |
Address container. | |
Request wrapper for address REST methods. | |
Response wrapper for address REST methods. | |
Options applied for each request. |
Universal Response Objects
We have three different types of objects suited to primary business regions being Australia, New Zealand and International (rest of world). However, if you need to integrate your global business need a set of universal objects.
We've created universal response components to enable consistent information no matter which address object best suits your business need.
When integrating to a platform we recommend using the universal response objects for consistency and scale.
See Address Field Mappings Guide for recommendations.
AddressAu
The AddressAu object is used when sending and receiving data from the address lookup API methods. For receiving data validated using Australian Sources of Truth (SoTs), see ValidatedAddressAu object.
_type
Type: String
The Address type object for the returned response (e.g. 'AddressAu').
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
AddressNz
The AddressNz object is used when sending and receiving data from the address lookup API methods. For receiving data validated using New Zealand Sources of Truth (SoTs), see ValidatedAddressNz object.
_type
Type: String
The Address type object for the returned response (e.g. 'AddressNz').
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
ValidatedAddressAu <<extends>> AddressAu
The ValidatedAddressAu object is used when sending and receiving data from the address identify API methods using Australian Sources of Truth (SoTs).
_type
Type: String
The Address type object for the returned response (e.g. 'ValidatedAddressAu').
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').
id
Type: String
The DPID or GNAFPID of the address (e.g. '89524889').
exception
Type: String
The exception thrown from the backend.
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
ValidatedAddressNz <<extends>> AddressNz
The ValidatedAddressNz object is used when sending and receiving data from the address identify API methods using New Zealand Sources of Truth (SoTs).
_type
Type: String
The Address type object for the returned response (e.g. 'ValidatedAddressNz').
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').
id
Type: String
The DPID or CNAR ID of the address (e.g. '2775942').
exception
Type: String
The exception thrown from the backend.
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
AddressIntl
The AddressIntl object is used when receiving data from retrieve API method for non-Australia and New Zealand addresses. It is also used when sending and receiving data from the previous version of International address lookup find and retrieve API methods.
_type
Type: String
The Address type object for the returned response (e.g. 'AddressIntl').
fullAddress
Type: String
The full address (e.g. '805 Veterans Blvd Ste 305, REDWOOD CITY CA 94063-1737, UNITED STATES').
country
Type: String
The country component of the address (e.g. 'United States').
Province
Type: String
The Province component of the address (e.g. 'CA').
postcode
Type: String
The Postcode component of the address (e.g. '94063-1737').
City
Type: String
The City component of the address (e.g. 'REDWOOD CITY').
street
Type: String
The Street component of the address (e.g. 'Veterans Blvd').
street2
Type: String
The Street line 2 of the address.
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').
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. 'Lowr LEVEL'). This includes subdwelling, floor and block information.
District
Type: String
The District component of the address (e.g. 'Younus Colony').
attributes
Type: Map
A map of name/value pairs representing additional information of the Address. (e.g. {"DomesticId": "Z216947437", "Line1": "805 Veterans Blvd Ste 305"}).
For example: {"CountryIso2":"US","CountryIso3":"USA","DomesticId":"Z216947437","DataLevel":"Range","ProvinceName":"California", "Type":"Residential","Language":"ENG","LanguageAlternatives":"ENG","AdminAreaCode":"081", "ProvinceCode":"CA","CountryIsoNumber":"840","Line1":"805 Veterans Blvd Ste 305","AdminAreaName":"San Mateo"}
JSON Representation
AddressIntlV2 <<extends>> AddressIntl
The AddressIntlV2 object is an AddressIntl with only non-null attributes are returned. It is used for receiving data from find API method, for all countries including Australia and New Zealand.
_type
Type: String
The Address type object for the returned response (e.g. 'AddressIntlV2').
fullAddress
Type: String
The full address (e.g. 'Unit 1-2, Bond Street Industrial Estate Mancunian Way Manchester, M12 6HW').
id
Type: String
The Address Id or a non-Address Id for further lookup (e.g. for United Kingdom, 'GB|RM|A|14405045' for Address Type and 'GB|RM|ENG|MANCHESTER---WAY-MANCUNIAN-ESTATE-BOND_STREET_INDUSTRIAL' for Street Type), for Australia with GNAF Source of Truth 'AU|GNAF|GANSW717802735' for Address Type.
attributes
Type: Map
A map of name and value pairs representing additional information of the Address, e.g.
{"Type": "Address"}for Address Type{"Type": "Street", "subdwellings": "Manchester, M12 6HW - 2 Addresses"}for non-Address Type for non-Australia/New Zealand{"Type": "Floor", "subdwellings": "4 Addresses"}for non-Address Type for Australia/New Zealand
JSON Representation
For Australia addresses with GNAF Source of Truth:
For United Kingdom addresses:
AddressList
An array or list of Address (AddressAu or AddressNz) structures.
JSON Representation
AddressRestRequest
An AddressRestRequest object is used when invoking the 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
AddressRestResponse
An AddressRestResponse object is returned from the 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
FeatureOption
A FeatureOption object is used to supply option values when invoking the address lookup REST service methods.
displayGnafLot
Type: ("0"|"1") Flag which determines if the lot information is displayed in addresses retrieved from 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. Only applicable for GNAF Source of Truth.
suppressLot
Type: ("0"|"1") Flag which suppresses Lot information when a street# is available in the address. If Street# is not in address then Lot information is displayed. This is used in conjunction with displayGnafLot = 1 and suppressLot = 1 to create this behavior.
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.
moreSources
Type: Array. The array of strings that expands datasets (source of truth) applied to the lookup result.
moreSources enables additional datasets to be searched and results shown to the end user
Address Find only.
positionFilter
Type: Array The array of filters to be applied to the lookup result - for AU locale only.
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 find method and address v1 (deprecated) 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
addressTypeFilter
Type: Array The array of filters to be applied to the lookup result - for NZ locale only.
The addressTypeFilter option is to filter the result based on the type of delivery point in NZPAF and NZAD. It is used for find and address v1 (deprecated) 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.
This filter can also be used with AUPOST data set to filter out different data assets like post shops, red street posting box, parcel lockers etc.
The option values available for Address Type filters using AUPOST:
UPL - filters only Parcel Locker addresses
LPO - filters only Licensed Post Office addresses
CPA - filters only Community Postal Agent addresses
RP - filters only Postshop addresses
RA- filters only Retail anexxe addresses
RSPB - filters only Red Street Posting Box addresses.
CSPB - filters only Combined Street Posting Box addresses.
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.
"1" (001) - exposes all the default original attributes.
"2" (010) - exposes GNAFPlus attributes.
"4" (100) - exposes 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 retrieve method, address v1 (deprecated), and Address 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 whether addresses are grouped together or not for "AUPAF" and "GNAF" Source of Truth. 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 used for find method and address v1 (deprecated) method. The default value is "0".The new Javascript client (since version 1.7.0) supports this feature.
radius
Type: Integer Distance in meter from the origin to search. It is used by reverseGeocode API and the default value is 50 meters.The new Javascript client (since version 1.7.0) supports this feature.
prioritizedSort
Type: ("0"|"1") Flag which determines whether to sort the locality information based on popularity of addresses for the locality search API. If the flag is set to "1", the locality search result will be sorted by popularity. By default, the value is "1".
exposeChanges
Type: ("0"|"1") Flag which determines whether to include PDP change item in CLEANSE API response. If the flag is set to "1", PDP changed items will be exposed. By default, it will not be exposed.
JSON Representation
Last updated