Address Verification API

This API requires authentication. See Authentication Overview for details on using API key + secret or OAuth2 bearer tokens.

The Address Verification API takes an address (potentially containing spelling mistakes and/or other errors) and attempts to match it against a valid address record in the Addressfinder database. This API can verify your addresses against either Australia Post's PAF, Geoscape's GNAF or both.

Response 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.

Parameters

Endpoint

Australia

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

Parameter	Description	Test Value
`key`	Your unique licence key (find on Portal credentials) Type: `string` `required`
`format`	The required format of the response. Default value: `json` Type: `string`
`q`	The address to be verified. Type: `string`
`gnaf`	Returns physical addresses from the GNAF database. One or both of GNAF or PAF databases need to be selected. `1` - Queries the GNAF database Default value: `1` Type: `string`
`paf`	Returns postal addresses from the PAF database. One or both of GNAF or PAF databases need to be selected. `1` - queries the AU PAF database Default value: `1` Type: `string`
`post_box`	Box type addresses are included by default (only available from PAF database). Box type addresses include PO Box, Locked Bag, GPO Box, CMB, RMS, Care PO, MS, RSD, Parcel Locker and Parcel Collect. Use this attribute to exclude them. `0` - Excludes Box type addresses from the verification results. Type: `string`
`gps`	Returns gps coordinates from the datasource specified (when available). `1` - Returns latitude and longitude. Type: `string`
`extended`	Returns `lga_name`, `lga_type_code`, `gnaf_id` and `legal_parcel_id` from the GNAF database. `1` - Returns additional data available from GNAF. Type: `string`
`census`	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. Type: `integer`
`state_codes`	Filter the results according to the states or territories. Use a comma to separate multiple values: `ACT` - Only returns addresses from Australian Capital Territory `NSW` - Only returns addresses from New South Wales `NT` - Only returns addresses from Northern Territory `QLD` - Only returns addresses from Queensland `SA` - Only returns addresses from South Australia `TAS` - Only returns addresses from Tasmania `VIC` - Only returns addresses from Victoria `WA` - Only returns addresses from Western Australia `OT` - Only returns addresses from Other Territories Type: `string`
`domain`	Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. Type: `string`
`ascii`	Set to `1` to reformat special characters like macrons and other accents characters with their ASCII equivalent (e.g. Pōneke and Café will be returned as Poneke and Cafe). Type: `string`

Responses

200 OK

Name	Description	Example
`matched`	Indicates if the address has been matched or not. Type: `boolean`	true
`success`	Indicates if the request was successful or not. Type: `boolean`	true
`address`	description text Type: `object`	-
`id`	The unique address identifier. This ID will change following a data refresh. gnaf paf gnaf-paf Type: `string`	73e8268c-bd5c-57a0-c20c-bcce334fe361
`full_address`	Full address string. gnaf paf gnaf-paf Type: `string`	274 Harbour Drive, COFFS HARBOUR NSW 2450
`address_line_1`	First line of the non-locality/state/postcode portion of the address. gnaf paf gnaf-paf Type: `string`	274 Harbour Drive
`address_line_2`	Second line of the non-locality/state/postcode portion of the address. This will be null for addresses without a unit/level/etc number. gnaf paf gnaf-paf Type: `string`	-
`address_line_combined`	A combination of the first and second lines of the non-locality/state/postcode portion of the address. gnaf paf gnaf-paf Type: `string`	274 Harbour Drive
`locality_name`	The locality/suburb of this address. gnaf paf gnaf-paf Type: `string`	COFFS HARBOUR
`state_territory`	The Australian state or territory where the address is located. gnaf paf gnaf-paf Type: `string`	NSW
`postcode`	Holds the four digit postcode. gnaf paf gnaf-paf Type: `string`	2450
`latitude`	Latitude coordinate (in WGS84 format). gnaf paf gnaf-paf Type: `string`	-30.304978
`longitude`	Longitude coordinate (in WGS84 format). gnaf paf gnaf-paf Type: `string`	153.126321
`box_identifier`	Identifies a specific box. Can be an alpha, number or a combination. paf Type: `string`	-
`box_type`	Describes the type of box. paf Type: `string`	-
`street_number_1`	The number of the building on the street. gnaf paf gnaf-paf Type: `string`	274
`street_number_2`	Holds the upper bound when this is a ranged address. For single number addresses this field is `null` gnaf paf gnaf-paf Type: `string`	-
`unit_identifier`	Identifies a specific sub-dwelling. Can be an alpha, number or a combination. gnaf paf gnaf-paf Type: `string`	-
`unit_type`	Describes the category of a sub-dwelling. gnaf paf gnaf-paf Type: `string`	-
`level_number`	Identifies a specific level within a multi-level building. Can be an alpha, number or a combination. gnaf paf gnaf-paf Type: `string`	-
`level_type`	Describes the level type within a multi-level building. gnaf paf gnaf-paf Type: `string`	-
`lot_identifier`	Identifies a specific lot on a site. Can be an alpha, number or a combination. gnaf paf gnaf-paf Type: `string`	CP
`site_name`	Holds the address element that identifies the name of a site or building. gnaf paf gnaf-paf Type: `string`	-
`street_name`	Holds the name of the street. gnaf paf gnaf-paf Type: `string`	Harbour
`street_type`	The type of street. gnaf paf gnaf-paf Type: `string`	Drive
`street_suffix`	The suffix of the street. Typically contains a compass direction. gnaf paf gnaf-paf Type: `string`	-
`street`	Holds the full name of the street. gnaf paf gnaf-paf Type: `string`	Harbour Drive
`meshblock`	The meshblock identifier in which the address is located. gnaf Type: `string`	-
`sa1_id`	The statistical area (SA1) identifier in which the address is located. gnaf Type: `string`	-
`sa2_id`	The statistical area (SA2) identifier in which the address is located. gnaf Type: `string`	-
`lga_name`	The name of the Local Government Area in which the address is located. The `source` must be set to `gnaf`. gnaf Type: `string`	Bundaberg
`lga_type_code`	The code relating to the type (or status) of the Local Government Area (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`). The `source` must be set to `gnaf`. gnaf Type: `string`	DC
`gnaf_id`	The unique persistent identifier of the G-NAF address. gnaf Type: `string`	-
`legal_parcel_id`	Government legal property description. gnaf Type: `string`	-

400 Bad request

Name	Description	Example
`completions`	An empty array will be returned due to the error Type: `array`	-
`error_code`	A unique numerical value identifying the error that occured Type: `string`	1004
`message`	An informative message describing the error that occured Type: `string`	Secret not provided
`success`	Indicates that the result was a failure Type: `boolean`	false

See API Error Reference for details.