Address Verification API (AU)

Version

Build
Send
Response
Errors

This page contains the technical information for our Address Verification API (V2)(V1). If you are an existing customer using our V1 api, click here to see the relevant documentation. Click here to view the technical information of our more feature rich V2 Address Verification API. Please visit our address verification page to view non-technical information about address verification and validation services.

The Address Verification API receives a full address from your system and attempts to match it with a verified address. If successful, it returns the matched address and associated metadata from our official data source (Geoscape's GNAF).the selected data source(s). This API can verify your addresses against either Australia Post's PAF, Geoscape's GNAF or both. You can automate this process by calling our API directly from your application.

FAQ: How do I get the best results from Address Verification?

Build the GET request URL

Use the form below to build your request URL from the available parameters. The URL string will be generated and can be sent to the API in order to provide insight into how the API works and the response it returns. Or, if you are using Postman for your investigation, development and testing, include the desired parameters and copy and paste the request URL below into Postman's GET request URL field.

Field Name	Value	Type	Description
key *		String	Your unique licence key (find on Portal credentials)
secret *		String	Your unique secret key (find on Portal credentials). Alternatively, you can pass your secret key into the Authorization header of the request as such: `Authorization: your-secret`. FAQ: Learn more about authenticating direct API calls in request headers
format *		String	The format of the response.
	Options json `json` for a response in json format. xml `xml` for a response in xml format.
q *		String	The address to be verified.
gnaf		String	Returns physical addresses from the GNAF database. One or both of GNAF or PAF databases need to be selected.
	Options gnaf `1` queries the GNAF database
paf		String	Returns postal addresses from the PAF database. One or both of GNAF or PAF databases need to be selected.
	Options paf `1` queries the AU PAF database
post_box		String	Box type addresses are included by default (only available from PAF database). Use this attribute to exclude them.
	Options post_box `0` Excludes Box type addresses from the verification results.
gps		String	Returns gps coordinates from the datasource specified (when available).
	Options gps `1` Returns latitude and longitude.
extended		String	Returns lga_name, lga_type_code, gnaf_id and legal_parcel_id from the GNAF database.
	Options extended metadata `1` Returns additional data available from GNAF.
census		String	Used to determine which census year’s statistical area identifiers (Meshblock, SA1 & SA2) will be returned in the response. Defaults to `2016` if omitted.
	Options 2016 `2016` to collect 2016 census related metadata 2021 `2021` to collect 2021 census related metadata
census		String	Returns statistical area identifiers (Meshblock, SA1 & SA2) from the specified census year. These attributes are only available from the GNAF database and are not returned if census is omitted.
	Options 2016 `2016` to collect 2016 census related metadata 2021 `2021` to collect 2021 census related metadata
state_codes		String	Filter the results according to the states or territories. Use a comma to separate multiple values
	Options Australian Capital Territory `ACT` New South Wales `NSW` Northern Territory `NT` Queensland `QLD` South Australia `SA` Tasmania `TAS` Victoria `VIC` Western Australia `WA` Other territories `OT`
domain		String	Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. FAQ: learn more about the domain parameter
ascii		Integer	A filter that replaces macron-containing characters with their ASCII counterparts. It doesn't exclude addresses with macron characters from the results, it translates these characters into their corresponding English equivalents within the addresses. Use when your systems are having issues processing macron-containing addresses.
	Options Converted `1` Converts the response to ASCII. Original Leaves the response as is, potentially containing macrons or non-ascii characters.

* Parameters marked with an asterisk are mandatory for this API call.

Request URL

https://api.addressfinder.io/api/au/address/verification/

https://api.addressfinder.io/api/au/address/v2/verification/

      
        /* Click the button above to see a real API response here */
        {
          "success": true
        }

Response Specification

The API response will include all the attributes listed below in the format requested in the API request. Empty attributes for the matched address will be returned with a null value.

Key

GNAF Returned (if present) when searching the gnaf database.

PAF Returned (if present) when searching the paf database.

GNAF,PAF Returned (if present) when searching the combined gnaf,paf datasets.

Field Name	Type	Description	Example
`id` GNAF PAF	String	The unique address identifier. This ID will change following a data refresh.	8097e3df-a3ab-43ad-bc66-22c8f5812361
`full_address` GNAF PAF	String	Full address string. FAQ: alias address vs canonical address.	13 Neville Street, RYDE NSW 2112
`canonical_address`	String	The canonical or official full address string associated with this address. Can differ from the full_address in either street number, locality name or state name. FAQ: alias address vs canonical address.	11-15 Neville Street, RYDE NSW 2112
`canonical_address_id`	String	The ID of the canonical or official address associated with this search result. Note: The ID and Canonical Address ID will be identical when the search result is canonical. FAQ: alias address vs canonical address.	d70230a9-a3d8-402f-971e-1b798d00f2f5
`address_line_1` GNAF PAF	String	First line of the non-locality/state/postcode portion of the address	Unit 209
`address_line_2` GNAF PAF	String	Second line of the non-locality/state/postcode portion of the address. This will be `null` for addresses without a unit/level/etc number.	274 Harbour Drive
`address_line_combined` GNAF PAF	String	A combination of the first and second lines of the non-locality/state/postcode portion of the address.	Unit 209, 274 Harbour Drive
`locality_name` GNAF PAF	String	The locality/suburb of this address.	KATOOMBA
`state_territory` GNAF PAF	String	The Australian state or territory where the address is located.	NSW
`postcode` GNAF PAF	String	Holds the four digit postcode.	0983
`latitude` GNAF PAF	String	Latitude coordinate (in WGS84 format).	-37.899031
`longitude` GNAF PAF	String	Longitude coordinate (in WGS84 format).	144.999530
`box_type` PAF	String	Describes the type of box.	GPO Box
`box_identifier` PAF	String	Identifies a specific box. Can be an alpha, number or a combination.	17
`parcel_locker_type` PAF	String	Describes the type of parcel locker	Parcel Collect
`parcel_locker_identifier` PAF	String	The 10 digit parcel locker identifier number. Also known as the Australia Post customer number (APCN)	10900112233
`street_number_1` GNAF PAF	String	The number of the building on the street.	1703
`street_number_2` GNAF PAF	String	Holds the upper bound when this is a ranged address. For single number addresses this field is `null`	1705
`unit_identifier` GNAF PAF	String	Identifies a specific sub-dwelling. Can be an alpha, number or a combination.	2
`unit_type` GNAF PAF	String	Describes the category of a sub-dwelling.	Suite
`level_number` GNAF PAF	String	Identifies a specific level within a multi-level building. Can be an alpha, number or a combination.	3
`level_type` GNAF PAF	String	Describes the level type within a multi-level building.	Basement
`lot_identifier` GNAF PAF	String	Identifies a specific lot on a site. Can be an alpha, number or a combination.	3
`site_name` GNAF PAF	String	Holds the address element that identifies the name of a site or building.	Kenilworth Police Station
`street_name` GNAF PAF	String	Holds the name of the street. Note: The attribute response does not contain the street type.	Queen
`street_type` GNAF PAF	String	The type of street.	Street
`street_suffix` GNAF PAF	String	The suffix of the street. Typically contains a compass direction.	North
`street` GNAF PAF	String	Holds the full name of the street. This attribute is a composite of the street name, the street type, and the street suffix if present.	Queen Street North
`meshblock` GNAF	String	The meshblock identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census. The format is `MB`, followed by a 2 digit year identifier, followed by the 11 digit meshblock identifier.	10671120000
`sa1_id` GNAF	String	The statistical area (SA1) identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census.	12602159143
`sa2_id` GNAF	String	The statistical area (SA2) identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census.	126021591
`lga_name` GNAF	String	The name of the Local Government Area in which the address is located. These values are provided by the ABS and are an approximation of the gazetted local government boundaries. Only returned when parameter `gnaf=1` supplied.	Bundaberg
`lga_type_code` GNAF	String	The code relating to the type (or status) of the Local Government Area. Codes used are Area `A`, Aboriginal Council `AC`, Borough `B`, City `C`, District Council `DC`, Municipality / Municipal Council `M`, Regional Council `R` or `RegC`, Rural City `RC`, Shire `S` and Town `T`. Only returned when parameter `gnaf=1` supplied.	DC
`gnaf_id` GNAF	String	The unique persistent identifier of the G-NAF address.	GANSW705051429
`legal_parcel_id` GNAF	String	Government legal property description	D61425/A9
`supplementary` GNAF PAF	String	Additional words such as addressee, recipient or building name that are included in the queried address string but are not part of the official verified address. You may wish to save the supplementary value and include it when printing delivery labels.	Jane Smith
`success`	Boolean	Indicates if the request was successful or not.	true
`matched`	Boolean	Indicates if the address has been matched or not.	true

Errors

Below are the possible errors that can be returned by the API.