Address Metadata API (AU)

Build
Send
Response
Errors

The Address Metadata API is used to load the full metadata associated with an address selected from the Address Autocomplete API.

Build the request URL

Use the form below to build your request URL from the parameters. A URL string will be generated from these parameters and sent to the API in order to provide insight into how the API works and the responses it returns.

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)
format *		String	The format of the response.
	Options json `json` for a response in json format. xml `xml` for a response in xml format.
id		String	Unique address id obtained from the Address Autocomplete API. You must supply either an id, or a gnaf_id, or a dpid field.
gnaf_id		String	Unique id from the G-NAF dataset. You must supply either an id, or a gnaf_id, or a dpid field.
dpid		String	Australia Post delivery point identifier. You must supply either an id, or a gnaf_id, or a dpid field.
au_paf		String	Used to determine which address database you will receive address and metadata from.
	Options PAF `1` Returns postal address and metadata from the Australia Post PAF GNAF `0` Default - Returns physical address and metadata from the GNAF database and ABS
gps		String	Request GPS coordinates for `latitude` and `longitude` be returned when available
	Options Yes `1` GPS coordinates wil be included in the response No `0`
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
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.

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

Request URL

        
          /* 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 au_paf database.

Field Name	Type	Description	Example
`full_address` GNAF PAF	String	Full address string. FAQ: alias address vs canonical address.	13 Neville Street, RYDE NSW 2112
`id` GNAF PAF	String	The unique address identifier. This ID will change following a data refresh.	8097e3df-a3ab-43ad-bc66-22c8f5812361
`canonical_address` GNAF PAF	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` GNAF PAF	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
`latitude` GNAF PAF	String	Latitude coordinate (in WGS84 format).	-37.899031
`longitude` GNAF PAF	String	Longitude coordinate (in WGS84 format).	144.999530
`lot_identifier` GNAF PAF	String	Identifies a specific lot on a site. Can be an alpha, number or a combination.	3
`box_identifier` GNAF PAF	String	The number portion of a PO Box address	123
`box_type` GNAF PAF	String	The type portion of a PO Box address, including `PO Box`, `Locked Bag`, `GPO Box`, `CMB`, `RMS`, `Care PO`, `MS` and `RSD`	PO Box
`site_name` GNAF PAF	String	Holds the address element that identifies the name of a site or building.	Kenilworth Police Station
`level_type` GNAF PAF	String	Describes the level type within a multi-level building.	Basement
`level_number` GNAF PAF	String	Identifies a specific level within a multi-level building. Can be an alpha, number or a combination.	3
`unit_type` GNAF PAF	String	Describes the category of a sub-dwelling.	Suite
`unit_identifier` GNAF PAF	String	Identifies a specific sub-dwelling. Can be an alpha, number or a combination.	2
`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
`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
`street_name` GNAF PAF	String	Holds the name of the street. Note: This attribute does not include the street type or suffix.	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
`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
`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
`success` GNAF PAF	Boolean	Indicates if the request was successful or not.	true
`dpid` PAF	String	Australia Post delivery point identifier.	99119187
`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. Code example - collect LGA data	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`.	DC
`legal_parcel_id` GNAF	String	Government legal property description.	10//SP9489
`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. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.	MB1610671120000
`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. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.	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. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.	126021591
`gnaf_id` GNAF	String	The unique persistent identifier of the G-NAF address.	GANSW705051429

Errors

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

Code	Error	Cause	Resolution
`1000`	Validation error	Returned when one of the supplied parameters is missing or incorrect. The response will contain a message attribute which explains the cause of the validation error. An example JSON response is shown below for a request which failed to include the `q` parameter. `{ completions: [ ], message: 'Q can not be blank', error_code: '1000' }`	Check that the supplied parameters contain valid values, and that the mandatory parameters have been included.
`1001`	Key not found	Returned when the key included in your API call cannot be found in our database. This will normally happen when you make a copy ’n paste error.	Compare the key included in your API call with the key listed in the AddressFinder Portal credentials. Also confirm there are no additional spaces or characters in your API call.
`1002`	Key not provided	Returned when you fail to send through your key with each request. The key is a mandatory parameter.	Check that you are using the correct parameter name `key`.
`1003`	Domain not registered with AddressFinder	The URL of the website where you are using the AddressFinder widget is not listed correctly in the allowed domains on the AddressFinder Portal. *Here are a few ways this could have happened:* The website domain not added to the portal: Domain listed: `some-other-site.com`, Website URL: `my-site.com` The website domain is added with 'www' but the website URL doesn't contain 'www': Domain listed: `www.my-site.com`, Website URL:`my-site.com` The website domain is added, but it has the wrong prefix (also known as a subdomain): Domain listed: `staging.my-site.com`, Website URL: `production.my-site.com`	Login to the AddressFinder Portal and add the domain of your website to your account. Adding the root domain, which means the domain without any prefix, will allow queries from all subdomains. For example, if you would like to use the widget on `staging.my-site.com` and `production.my-site.com`, all you need to do is add `my-site.com` in the Portal. Note: in this case, all lookups will be recorded under `my-site.com`
`1004`	Secret not provided	Returned when you fail to send through your secret with an API call. Can also occur when using the widget and the HTTP `Referer` header is not included.	Include the secret listed in the AddressFinder Portal credentials in your API call. When using the widget, you must load the page from a web server (e.g. localhost) and not a `file://` scheme.
`1005`	Direct API calls are not permitted on your current plan.	Returned if you try to call the API and you are on either a Free or Agile plan. These plan types provide access to the JavaScript Widget and plugins only.	Upgrade to a Business plan. Visit the AddressFinder Portal to change plan.
`1006`	Invalid credentials	Returned when the supplied key and/or secret value are incorrect. This will normally happen when you make a copy ’n paste error.	Compare the key and secret included in your API call with the values listed on the AddressFinder Portal credentials page. Also confirm there are no additional spaces or characters in your API call.
`1008`	Secret should not be supplied	This is a safety check to ensure that the secret parameter has not been included when making requests from your web browser. You should never include the secret on any web page.	The secret should be used for server-to-server API calls only.
`1009`	The AddressFinder plugin has exceeded the number of allowed lookups, and is now suspended	Returned when your account (free plans only) has hit its 100% usage limit for the billing period.	Visit the AddressFinder Portal and switch to a Paid plan. Alternatively wait until the end of the month when suspended accounts are automatically reactivated.
`1010`	Account not authorised to use this API	Returned when you make an API call that you are not permitted to use	Contact AddressFinder support to request access to this API.
`1011`	The record you are trying to load does not exist	Returned when the supplied address identifier cannot be found. This can happen when a stale identifier is included in the API call.	Do not save address identifiers in your database, as they are transient and may change after each database update.
`1012`	Account not authorised to use this API	Returned when you make an API call that you are not permitted to use	Contact AddressFinder support to request access to this API.
`1013`	This API has been discontinued	This API has been discontinued	Contact AddressFinder support to discuss alternatives.
`1015`	Domain parameter must not be included in a web request	You have included a domain parameter in your browser based API call. The domain parameter is for direct API calls only.	Remove the domain parameter from your web request.
`1016`	This domain has been blocked	These credentials are not permitted to be used on this domain.	Contact AddressFinder support to discuss removing the block.
`1017`	This service is not enabled on your current plan	You have attempted to use an AddressFinder service that is not enabled on your current plan.	Visit the AddressFinder Portal to change plan.
`1018`	Your IP address has been blocked for these credentials	This service has been configured to only allow access from defined IP addresses.	Visit the AddressFinder Portal and add your IP address to the IP Allow List.
`1019`	HTTP Referer or Origin header record must be present when making a browser initiated request	You have attempted to use the AddressFinder widget from a browser that does not include the referrer or origin headers along with each request.	Confirm that this request was sent from a valid web server (not the local filesystem), and that you do not have browser plugins interfering with the request.
`1020`	Your AddressFinder trial has ended	Returned when the trial term has ended.	Log into the AddressFinder Portal and upgrade your account to a suitable plan.
`1021`	Your AddressFinder trial has exceeded its allowed lookups	Returned when you have exceeded the number of lookups permitted on the trial plan.	Log into the AddressFinder Portal and upgrade your account to a suitable plan.
`1022`	Postal addresses are not enabled on your current plan	You have attempted to query postal addresses, this service is not included in your current plan.	You can use our service without specifying postal addresses. For Australia, use the param `gnaf:1` (and remove `au_paf:1`). For New Zealand, remove `delivered:1` and `post_box:1`. If you would like to continue using postal addresses, log into the AddressFinder Portal and upgrade your account to a suitable plan.