GetSimilar

API Documentation

Introduction

GetSimilar uses text search to find addresses based on our proprietary matching algorithm that incorporates advanced searching and filtering capabilities. The API provides the capability to custom-build your own auto-complete functionality for desktop, web, and mobile applications.

Addresser GetSimilar is based on data from both Australian Government-published Geocoded National Address File (GNAF) and Australia Postal Address File. The data set is also augmented with additional local government attributes from the Australia Bureau of Statistics.


Supported Plans:

Enterprise

Addresser GetSimilar

Based on our predictive search, returns an array of partial/full match complete address for the given components of the user input address.

GET 
https://api.addresser.com.au/getsimilar
Example Usage
https://api.addresser.com.au/getsimilar?gnaf=0&pdt=0&states=NSW&search_word=12 st

Request Headers

Field Type Description
x-api-key String

Your unique API key for authentication.

Parameter

Field Type Description
search_word String

Partial address searched for.
states optional String

Specific filter state codes to limit the search to specific states or territories. Comma-separated state codes should be used.

Usage

states=nsw,qld
states=nsw

https://api.addresser.com.au/getsimilar?gnaf=0&pdt=0&states=NSW&search_word=12 st

Australian Capital Territory - ACT
New South Wales - NSW
Northern Territory - NT
Queensland - QLD
South Australia - SA
Tasmania - TAS
Victoria - VIC
Westerna Australia - WA

pdt required Integer

Postal delivery types are included by default (i.e. pdt=0 and gnaf=0) in the GetSimilar search excluding GNAF, the pdt filter should be used to either include only physical dwellings or exclusively include Postal Delivery Types. Usage scenarios below:

Scenario 1 - Include GNAF, exclude Post Delivery Types
This scenario is catered to use cases where only physical dwellings are to be included in the GetSimilar. The pdt filter must be set to '0' and gnaf filter must be set to '1'.
Example Usage
https://api.addresser.com.au/getsimilar?gnaf=1&pdt=0&states=NSW&search_word=12 st

Scenario 2 - Include only Postal Delivery Types
This scenario is catered to use cases where only postal delivery types such as "PO BOX", "MAIL BAG" etc., are to be included in the GetSimilar, and do not include any physical dwellings. For this to work pdt filter must be set to '1' and gnaf filter must be set to '0'.
Example Usage
https://api.addresser.com.au/getsimilar?gnaf=0&pdt=1&states=NSW&search_word=12 st

NOTE: GNAF and POSTAL DELIVERY TYPES are mutually exclusive therefore both the filters cannot be set to '1'.
gnaf required Integer

gnaf=1 include GNAF in search and results.
gnaf=0 exclude GNAF from search and results.

limit optional Integer

Default to 10, range between 10 and 20.

Response

The success response from the API consists of Suggestions array (Suggestions[]) consisting of four elements – a single line formatted address, unique identifier pertaining to that specific dataset version and each suggestion accompanied by Sources array (Source[]) identifying the potential data sources used to produce the curated address and Metadata.

200 Success Response Structure


{
    "Suggestions": [
        {
            "FULL_ADDRESS": "12 STRATHALLAN TCE THRUMSTER NSW 2444",
            "FULL_ADDRESS_HIGHLIGHTED": "<strong>12</strong> <strong>STRATHALLAN</strong> TCE THRUMSTER NSW 2444",
            "_id": "Yud0i5MB_**********",
            "SOURCE": [
                "AU_PAF",
                "AU_GNAF",
                "LGA"
            ],
            "METADATA": {
                "AU_GNAF": {
                    "GNAF_ADDRESS_DETAIL_PID": "GANSW720*****",
                    "GNAF_BUILDING_NAME": "",
                    "GNAF_LOT_NUMBER_PREFIX": "",
                    "GNAF_LOT_NUMBER": "",
                    "GNAF_LOT_NUMBER_SUFFIX": "",
                    "GNAF_FLAT_TYPE": null,
                    "GNAF_FLAT_NUMBER_PREFIX": "",
                    "GNAF_FLAT_NUMBER": null,
                    "GNAF_FLAT_NUMBER_SUFFIX": "",
                    "GNAF_LEVEL_TYPE": null,
                    "GNAF_LEVEL_NUMBER_PREFIX": "",
                    "GNAF_LEVEL_NUMBER": null,
                    "GNAF_LEVEL_NUMBER_SUFFIX": "",
                    "GNAF_NUMBER_FIRST_PREFIX": "",
                    "GNAF_NUMBER_FIRST": 12,
                    "GNAF_NUMBER_FIRST_SUFFIX": "",
                    "GNAF_NUMBER_LAST_PREFIX": "",
                    "GNAF_NUMBER_LAST": null,
                    "GNAF_NUMBER_LAST_SUFFIX": "",
                    "GNAF_STREET_LOCALITY_PID": "NSW4126167",
                    "GNAF_STREET_NAME": "STRATHALLAN",
                    "GNAF_STREET_TYPE_ABBR": "TCE",
                    "GNAF_STREET_SUFFIX_CODE": null,
                    "GNAF_LOCALITY_NAME": "THRUMSTER",
                    "GNAF_STATE_ABBREVIATION": "NSW",
                    "GNAF_POSTCODE": "2444",
                    "GNAF_LATITUDE": -31.45766724,
                    "GNAF_LONGITUDE": 152.83322529,
                    "GNAF_GEOCODE_TYPE": "PROPERTY CENTROID",
                    "GNAF_LEGAL_PARCEL_ID": "111/1278998",
                    "GNAF_ADDRESS_MESH_BLOCK_2016_PID": "NSW1585188770",
                    "GNAF_MB_2016_PID": "MB1611205458900",
                    "GNAF_MB_MATCH_CODE_2016": "1",
                    "GNAF_MB_2016_CODE": "11205458900",
                    "GNAF_MBMC_2016_NAME": "PARCEL LEVEL MATCH",
                    "GNAF_ADDRESS_MESH_BLOCK_2021_PID": "NSW1585207387",
                    "GNAF_MB_2021_PID": "MB2111231920000",
                    "GNAF_MB_2021_CODE": "11231920000",
                    "GNAF_MBMC_2021_NAME": "PARCEL LEVEL MATCH",
                    "GNAF_FULL_ADDRESS": "12 STRATHALLAN TCE THRUMSTER NSW 2444",
                    "GNAF_ADDRESS_LINE_1": "12 STRATHALLAN TCE",
                    "GNAF_ADDRESS_LINE_2": "THRUMSTER NSW 2444",
                    "GNAF_ADDRESS_LINE_3": "AUSTRALIA",
                    "GNAF_ADDRESS_LINE_4": "",
                    "COUNTRY_CODE": "AU"
                },
                "AU_PAF": {
                    "DELIVY_POINT_GROUP_ID": 14831,
                    "DELIVY_POINT_ID": 83301977,
                    "BARCODE_4STATE": "1301012210100001302121321002021032213",
                    "THOROUGHFARE_NBR_1": "12",
                    "THOROUGHFARE_NBR_SFX_1": null,
                    "THOROUGHFARE_NBR_2": null,
                    "THOROUGHFARE_NBR_SFX_2": null,
                    "FLAT_UNIT_TYPE": null,
                    "FLAT_UNIT_NBR": null,
                    "FLOOR_LEVEL_TYPE": null,
                    "FLOOR_LEVEL_NBR": null,
                    "LOT_NBR": null,
                    "POSTAL_DELIVERY_NBR": null,
                    "POSTAL_DELIVERY_NBR_PFX": null,
                    "POSTAL_DELIVERY_NBR_SFX": null,
                    "PRIMARY_POINT_IND": "R",
                    "BLDG_PROP_NAME_1": null,
                    "BLDG_PROP_NAME_2": null,
                    "LOCALITY_ID": 21905,
                    "STREET_NAME": "STRATHALLAN",
                    "STREET_TYPE": "TCE",
                    "STREET_SFX": null,
                    "POSTAL_DELIVERY_TYPE": null,
                    "DELIVY_POINT_GROUP_DID": null,
                    "LOCALITY_NAME": "THRUMSTER",
                    "POSTCODE": "2444",
                    "STATE": "NSW",
                    "LOCALITY_DID": null,
                    "LOCALITY_NAME_SYNONYM": null,
                    "ST_ALT_STREET_NAME": null,
                    "ST_ALT_STREET_TYPE": null,
                    "ST_ALT_STREET_SFX": null,
                    "BORDERING_LOCALITY_NAME": "FERNBANK CREEK, LAKE INNES, PORT MACQUARIE, SANCROX",
                    "BORDERING_POSTCODE": "2444, 2446, 2444, 2446",
                    "FULL_ADDRESS": "12 STRATHALLAN TCE THRUMSTER NSW 2444",
                    "ADDRESS_LINE_1": "12 STRATHALLAN TCE",
                    "ADDRESS_LINE_2": "THRUMSTER NSW 2444",
                    "ADDRESS_LINE_3": "AUSTRALIA",
                    "ADDRESS_LINE_4": "",
                    "PAF_EXPIRY": "2025-04-30",
                    "COUNTRY_CODE": "AU"
                },
                "LGA": {
                    "LGA_MB_CODE_2021": "11231920000",
                    "LGA_STATE_CODE_2021": "1",
                    "LGA_STATE_NAME_2021": "NEW SOUTH WALES",
                    "LGA_AUS_CODE_2021": "AUS",
                    "LGA_AUS_NAME_2021": "AUSTRALIA",
                    "LGA_AREA_ALBERS_SQKM": 4.4875,
                    "LGA_ASGI_LOCI_URI_2021": "HTTP://LINKED.DATA.GOV.AU/DATASET/ASGSED3/MB/11231920000",
                    "LGA_CODE_2021": "16380",
                    "LGA_NAME_2021": "PORT MACQUARIE-HASTINGS"
                }
            }
        }
    ]
}

API Errors

              {
                "errorCode": xxxx,
                "errorMessage": "xxx"
              }
Error Code Description Resolution
4073

Supplied Parameter is invalid

One of parameter is empty or has an invalid value.
4071

search_word is missing

Parameter search_word is missing.
4072

search_word cannot be empty

Input partial address into the search_word query string of the request URL.
4064

limit cannot be empty.

Input 'limit' cannot be empty.
4065

states cannot be empty

Input valid comma-separate state codes to filter the results.
4066

Invalid state name provided.

One or more of the state codes are invalid.
4067

Postal Delivery Type (pdt) cannot be empty, acceptable values - 0 or 1.

Input valid pdt type (0 or 1) to the pdt query string.
4068

Invalid Postal Delivery Type (pdt) value provided, acceptable values - 0 or 1.

pdt type can be either 0 or 1.
4076

API key is missing or invalid.

Check the API Key, you can get the correct API Key from the "Credentials" section of "My Addresser" portal.
4077

Invalid Method or API URL.

You have used an incorrect URL. Check the URL from the API documentation.
4080

You have exceeded the allowed quota.

You have reached the maximum limit of API calls on your current plan. You can choose to add an additional quota via the Pricing page of the Addresser website.
4003

Internal Server Error

This is a server-side issue.
Below example error code and message. 
              {
                "errorCode": 4072,
                "errorMessage": "search_word cannot be empty."
              }

Response Specification

Field Type Description Example
FULL_ADDRESS String

Full address response the input partial address. The address data provided is based on the data source availability. Australia Post address is returned if available otherwise GNAF address.

 12 STRATHALLAN TCE THRUMSTER NSW 2444
FULL_ADDRESS_HIGHLIGHTED String

The 'FULL_ADDRESS_HIGHLIGHTED' response highlights text using 'strong' tags based on the provided input.

<strong>12</strong> <strong>STRATHALLAN</strong> TCE THRUMSTER NSW 2444
_id String

Unique record identifier of the address

 Yud0i5MB_**********
SOURCE Array

An array of strings based on the number of data sources the address is curated from.
• AU_PAF – Australia Post Address File.
• AU_GNAF- Geocoded National Address File.
• LGA – Australia Bureau of Statistics information used to augment local government information.

AU_PAF
Australia GNAF DATA
GNAF_ADDRESS_DETAIL_PID

String

Unique address identifier of GNAF dataset.

GANSW720*****
GNAF_BUILDING_NAME

String

Building name, if available

GNAF_LOT_NUMBER_PREFIX

String

Prefix of the LOT number.

GNAF_LOT_NUMBER

String

LOT number of the address provided by GNAF dataset.

GNAF_LOT_NUMBER_SUFFIX

String

Suffix of the LOT number.

GNAF_FLAT_TYPE

String

Flat type name.

GNAF_FLAT_NUMBER_PREFIX

String

Flat number prefix if any

GNAF_FLAT_NUMBER

Integer

Flat number

GNAF_FLAT_NUMBER_SUFFIX

String

Flat number suffix if any

GNAF_LEVEL_TYPE

String

Floor Level type name

GNAF_LEVEL_NUMBER_PREFIX

String

Floor Level number prefix, if any.

GNAF_LEVEL_NUMBER

Integer

Floor level number

GNAF_LEVEL_NUMBER_SUFFIX

String

Floor level number suffix, if any

GNAF_NUMBER_FIRST_PREFIX

String

Street number first prefix, if any.

GNAF_NUMBER_FIRST

Integer

Street number of the address.

12
GNAF_NUMBER_FIRST_SUFFIX

String

Street Number suffix if any

GNAF_NUMBER_LAST_PREFIX

String

Street number last prefix, if any. This number prefix is for ranged addresses.

GNAF_NUMBER_LAST

Integer

Street number last (for ranged addresses only), if any.

GNAF_NUMBER_LAST_SUFFIX

String

Street number last (for ranged addresses only) suffix, if any.

GNAF_STREET_LOCALITY_PID

String

Unique locality identifier.

NSW4126167
GNAF_STREET_NAME

String

Street name

STRATHALLAN
GNAF_STREET_TYPE_ABBR

String

Street type abbreviation.

TCE
GNAF_STREET_SUFFIX_CODE

String

Street suffix code

GNAF_LOCALITY_NAME

String

Suburb/Locality name

THRUMSTER
GNAF_STATE_ABBREVIATION

String

Three letter state code.

NSW
GNAF_POSTCODE

String

Postal code of the suburb/locality.

2444
GNAF_LATITUDE

Float

Geographical latitude

-31.45766724
GNAF_LONGITUDE

Float

Geographical longitude

152.83322529
GNAF_GEOCODE_TYPE

String

Geocode type representing the type of Geocoding of the Latitude and Longitude.

PROPERTY CENTROID
GNAF_LEGAL_PARCEL_ID

String

Legal parcel identifier.

111/1278998
GNAF_ADDRESS_MESH_BLOCK_2016_PID

String

2016 Australian Mesh block PID.

NSW1585188770
GNAF_MB_2016_PID

String

2016 MB PID

MB1611205458900
GNAF_MB_MATCH_CODE_2016

String

2016 MB match code

1
GNAF_MB_2016_CODE

String

2016 MB code

11205458900
GNAF_MBMC_2016_NAME

String

2016 MB MC code

PARCEL LEVEL MATCH
GNAF_ADDRESS_MESH_BLOCK_2021_PID

String

2021 Mesh block PID

NSW1585207387
GNAF_MB_2021_PID

String

2021 MB PID

MB2111231920000
GNAF_MB_2021_CODE

String

2021 MB code

11231920000
GNAF_MBMC_2021_NAME

String

2021 MB MC code

PARCEL LEVEL MATCH
GNAF_FULL_ADDRESS

String

Combined full address string based on GNAF data.

12 STRATHALLAN TCE THRUMSTER NSW 2444
GNAF_ADDRESS_LINE_1

String

GNAF Address Line 1 string based on GNAF data.

12 STRATHALLAN TCE
GNAF_ADDRESS_LINE_2

String

GNAF Address Line 2 string based on GNAF data.

THRUMSTER NSW 2444
GNAF_ADDRESS_LINE_3

String

GNAF Address Line 3 string based on GNAF data.

AUSTRALIA
GNAF_ADDRESS_LINE_4

String

GNAF Address Line 4 string based on GNAF data.

COUNTRY_CODE

String

ISO two letter country code

AU
Australia Post Data
DELIVY_POINT_GROUP_ID

Integer

Australia Post Delivery point group identifier of the address.

14831
DELIVY_POINT_ID

Integer

Unique Delivery point identifier (DPID) of the address.

83301977
BARCODE_4STATE

String

4 state Barcode number of the address.

1301012210100001302121321002021032213
THOROUGHFARE_NBR_1

String

Street number

12
THOROUGHFARE_NBR_SFX_1

String

Street number suffix if any

THOROUGHFARE_NBR_2

String

Street number last (only for addresses with ranged street numbers).

THOROUGHFARE_NBR_SFX_2

String

Last street number (only for addresses with ranged street numbers) suffix, if any.

FLAT_UNIT_TYPE

String

Flat unit type, e.g. U - Unit, F - Flat etc.

U
FLAT_UNIT_NBR

String

Flat/Unit number of address for multi-dwelling buildings

FLOOR_LEVEL_TYPE

String

Floor level type of address for multi-floor/level buildings

FLOOR_LEVEL_NBR

String

Floor level type of unit for multi-floor/level buildings

LOT_NBR

String

LOT Number of the dwelling.

POSTAL_DELIVERY_NBR

String

Postal delivery number for address such as PO BOX

POSTAL_DELIVERY_NBR_PFX

String

Postal delivery number prefix for address such as PO BOX

POSTAL_DELIVERY_NBR_SFX

String

Postal delivery number suffix for address such as PO BOX

PRIMARY_POINT_IND

String

Indicator if the dwelling is Primary delivery point.

BLDG_PROP_NAME_1

String

Building/property name if any

BLDG_PROP_NAME_2

String

Building/property name continuation to BLDG_PROP_NAME_1

LOCALITY_ID

Integer

Unique locality/suburb identifier.

21905
STREET_NAME

String

Street name of the address.

STRATHALLAN
STREET_TYPE

String

Standardised street name abbreviation

TCE
STREET_SFX

String

Street suffix, if any.

POSTAL_DELIVERY_TYPE

String

Indicates of the address is PO BOX or similar kind of address

DELIVY_POINT_GROUP_DID

Integer

Unique Delivery Point Group identifier.

LOCALITY_NAME

String

Locality/suburb name of the address.

THRUMSTER
POSTCODE

String

Post code of the suburb/locality.

2444
STATE

String

State abbreviation of the address.

NSW
LOCALITY_DID

Integer

Locality delivery identifier.

LOCALITY_NAME_SYNONYM

String

Locality/suburb name synonym, if any.

ST_ALT_STREET_NAME

String

Alternate name of the street.

ST_ALT_STREET_TYPE

String

Alternate street type

ST_ALT_STREET_SFX

String

Alternate street suffix

BORDERING_LOCALITY_NAME

String

Comma separated bordering locality names of the address locality/suburb. These are returned as coma separated values.

FERNBANK CREEK, LAKE INNES, PORT MACQUARIE, SANCROX
BORDERING_POSTCODE

String

Comma separated bordering locality/suburb post codes corresponding to the Bordering locality names returned in the BORDERING_LOCALITY_NAME. These are returned as coma separated values.

2444, 2446, 2444, 2446
FULL_ADDRESS

String

Commonly used full address representation of the Australia Post matched address.

12 STRATHALLAN TCE THRUMSTER NSW 2444
ADDRESS_LINE_1

String

Address Line 1 representation of the Australia Post matched address.

12 STRATHALLAN TCE
ADDRESS_LINE_2

String

Address Line 2 representation of the Australia Post matched address.

THRUMSTER NSW 2444
ADDRESS_LINE_3

String

Address Line 3 representation of the Australia Post matched address.

AUSTRALIA
ADDRESS_LINE_4

String

Address Line 3 representation of the Australia Post matched address.

PAF_EXPIRY

Date

Australia Post mandated data expiry date pertaining to this record.

2025-04-30
COUNTRY_CODE

String

ISO two letter country code

AU
Local Government Data
LGA_MB_CODE_2021

String

2021 Mesh block code corresponding to Local government data.

11231920000
LGA_STATE_CODE_2021

String

2021 LGA code.

1
LGA_STATE_NAME_2021

String

State name as per Local government dataset.

NEW SOUTH WALES
LGA_AUS_CODE_2021

String

Three letter country code as per Local government dataset.

AUS
LGA_AUS_NAME_2021

String

Country name as per Local government dataset.

AUSTRALIA
LGA_AREA_ALBERS_SQKM

Float

Local government area coverage in square kilometres.

4.4875
LGA_ASGI_LOCI_URI_2021

String

Local government area reference dataset URI.

HTTP://LINKED.DATA.GOV.AU/DATASET/ASGSED3/MB/11231920000
LGA_CODE_2021

String

2021 LGA code.

16380
LGA_NAME_2021

String

2021 Local government area name.

PORT MACQUARIE-HASTINGS