openapi: 3.0.0 servers: - description: AddressFinder API Server url: https://api.addressfinder.io/api/ info: description: This is the documentation for the Addressfinder API version: 1.1.0 title: Addressfinder API contact: email: support@addressfinder.com.au paths: /au/address/autocomplete: get: summary: Address Autocomplete API x-doc-meta-title: Address Autocomplete API (AU) x-doc-meta-description: Interactive search that returns closely matching Australian addresses which are then selected by the user tags: - Australia operationId: au-address-autocomplete-api description: > The AU Address Autocomplete API is used to search the AU Addressfinder database to return closely matching addresses which can then be selected from by the user. This API works in tandem with the AU Address Metadata API which is used to load the metadata associated with the selected address. parameters: - in: query name: key description: Your unique licence key (find on Portal credentials) required: true schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: q description: The partial address being searched required: false schema: type: string example: Unit 2, 21 Kent Road - in: query name: format description: The format of the response. required: false schema: type: string enum: - json - xml default: json example: json - in: query name: source description: | Determines the source of the addresses being searched and returned. * `GNAF` - Returns physical addresses from the GNAF address dataset. * `PAF` - Returns postal addresses, including PO Box type addresses, from the Australia Post postal address file. * `GNAF,PAF` - Returns addresses from either of the PAF or GNAF address datasets. required: false schema: type: string enum: - GNAF,PAF - GNAF - PAF default: GNAF,PAF example: GNAF,PAF - in: query name: post_box description: > Return PO Box style addresses. This includes PO Box, Locked Bag, GPO Box, CMB, RMS, Care PO, MS and RSD. Used with the `source` filter above: * `0` - Set this option to exclude PO Box style addresses from your search results * `1` - A rarely used option that returns only PO Box style addresses * Omit to return PO Box addresses with deliverable addresses required: false schema: type: string enum: - "0" - "1" - in: query name: canonical description: > Return canonical and/or alias addresses - this allows for vanity suburbs, historic street names, and more: * `1` - Alias addresses are not included in the search results * Omit to return canonical and alias addresses are returned (most common option) required: false schema: type: string enum: - "1" - in: query name: state_codes description: > 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 required: false schema: type: string - in: query name: domain description: >- Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. required: false schema: type: string - in: query name: max description: The maximum number of results to return. The default is 10 results. required: false schema: type: integer minimum: 1 maximum: 100 default: 10 - in: query name: highlight description: > Returns an additional attribute in the response called `highlighted_full_address`. This attribute wraps the matching terms in the address with `` in order to highlight those terms: * `1` - Matching terms in the returned addresses are highlighted. * Omit to not return additional `highlighted_full_address` property required: false schema: type: string enum: - "1" - in: query name: ascii description: > 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*). schema: type: string enum: - "1" responses: "200": description: OK content: application/json: schema: type: object properties: completions: type: array items: $ref: "#/components/schemas/AU.Address.Autocomplete" success: type: boolean description: if the request completed successfully example: true "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/AU.Address.Error" /au/address/metadata: get: summary: Address Metadata API x-doc-meta-title: Address Metadata API (AU) x-doc-meta-description: Return the full metadata associated with an address selected from the Australia Address Autocomplete API tags: - Australia operationId: au-address-metadata-api description: >- The AU Address Metadata API is used to load the full metadata associated with an AU Address selected from the AU Address Autocomplete API. :::note Learn more about the [Address Verification](@WEBSITE_URL/address-verification/) service. :::

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: - in: query name: key description: Your unique licence key (find on Portal credentials) required: true schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: format description: The required format of the response. schema: type: string enum: - json - xml default: json example: json - in: query name: id description: > Unique address identifier obtained from the Address Autocomplete API. You must supply either an id, or a gnaf_id, or a dpid field. required: false schema: type: string example: a9cd30a9-d682-ee4a-91aa-ab9a66446934 - in: query name: gnaf_id description: | Unique id from the G-NAF dataset. You must supply either an id, or a gnaf_id, or a dpid field. required: false schema: type: string - in: query name: dpid description: | Australia Post delivery point identifier. You must supply either an id, or a gnaf_id, or a dpid field. required: false schema: type: string - in: query name: source description: | Determines the source of the address and metadata returned.. * `GNAF` - Returns physical addresses from the GNAF address dataset. * `PAF` - Returns postal addresses, including PO Box type addresses, from the Australia Post postal address file. * `GNAF,PAF` - Returns addresses from either of the PAF or GNAF address datasets. required: false schema: type: string enum: - GNAF,PAF - GNAF - PAF default: GNAF,PAF - in: query name: gps description: > Request GPS coordinates for `latitude` and `longitude` be returned when available: * `1` - GPS coordinates wil be included in the response * Omit to GPS coordinates required: false schema: type: string enum: - "1" - in: query name: domain description: >- Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. required: false schema: type: string - in: query name: census description: > Used to determine which census year’s statistical area identifiers (Meshblock, SA1 & SA2) will be returned in the response. Defaults to `2016` if omitted. required: false schema: type: integer enum: - 2016 - 2021 default: 2016 - in: query name: ascii description: > 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*). required: false schema: type: string enum: - "1" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/AU.Address.Metadata" "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/AU.Address.Error" /au/address/v2/verification: get: summary: Address Verification API x-doc-meta-title: Address Verification API (AU) x-doc-meta-description: The Australia 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. tags: - Australia operationId: au-address-verification-api description: > 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: - in: query name: key description: Your unique licence key (find on Portal credentials) required: true schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: format description: The required format of the response. schema: type: string enum: - json - xml default: json example: json - in: query name: q description: The address to be verified. required: false schema: type: string example: 274 Harbour Drive, COFFS HARBOUR NSW 2450 - in: query name: gnaf description: > Returns physical addresses from the GNAF database. One or both of GNAF or PAF databases need to be selected. * `1` - Queries the GNAF database required: false schema: type: string enum: - "1" default: "1" - in: query name: paf description: > 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 required: false schema: type: string enum: - "1" default: "1" - in: query name: post_box description: > Box type addresses are included by default (only available from PAF database). Use this attribute to exclude them. * `0` - Excludes Box type addresses from the verification results. required: false schema: type: string enum: - "0" - in: query name: gps description: > Returns gps coordinates from the datasource specified (when available). * `1` - Returns latitude and longitude. required: false schema: type: string enum: - "1" - in: query name: extended description: > Returns `lga_name`, `lga_type_code`, `gnaf_id` and `legal_parcel_id` from the GNAF database. * `1` - Returns additional data available from GNAF. required: false schema: type: string enum: - "1" - in: query name: census description: > 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. required: false schema: type: integer enum: - 2016 - 2021 - in: query name: state_codes description: > 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 required: false schema: type: string enum: - ACT - NSW - NT - QLD - SA - TAS - VIC - WA - OT - in: query name: domain description: >- Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. required: false schema: type: string - in: query name: ascii description: > 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*). required: false schema: type: string enum: - "1" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/AU.Address.Verification" "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/AU.Address.Error" /au/location/autocomplete: get: summary: Location Autocomplete API x-doc-meta-title: Location Autocomplete API (AU) x-doc-meta-description: Interactive search that returns closely matching Australian streets, suburbs and/or states which are then selected by the user operationId: au-location-autocomplete-api description: > This API lets you search for streets, suburbs, and/or states — referred to as "locations". This API works in tandem with the Location Metadata API to collect metadata associated with the selected location. tags: - Australia parameters: - name: key in: query required: true description: Your unique Addressfinder license key. schema: type: string example: ADDRESSFINDER_DEMO_KEY - name: q in: query required: true description: The query string to be matched with the location. schema: type: string example: Kent Road, MASCOT - name: format in: query required: true description: The format of the response. schema: type: string enum: [json, xml] default: json - name: location_types in: query required: false description: > A comma-separated list of location types to filter the results. Leave empty to allow any location type. Options are `street`, `locality` (suburb), and `state`. schema: type: string - name: state_codes in: query required: false description: > A comma-separated list of states or territories to filter results. Options: ACT, NSW, NT, QLD, SA, TAS, VIC, WA, OT. schema: type: string - name: domain in: query required: false description: > Used to identify in the Addressfinder Portal which of your services is calling the API for activity monitoring purposes. The domain needs to be registered in the Portal. schema: type: string example: example.com - name: max in: query required: false description: Maximum number of results to return (1–100). schema: type: integer default: 10 minimum: 1 maximum: 100 - name: highlight in: query required: false description: > Set to `1` to include a `highlighted_full_location` field in results, wrapping matching terms with ``. schema: type: integer enum: [0, 1] responses: "200": description: A list of location autocomplete completions content: application/json: schema: type: object properties: completions: type: array items: type: object properties: id: type: string description: The unique location identifier. example: full_location: type: string description: Full location as supplied by data sources. example: Martin Street, OUYEN VIC 3490 state_territory: type: string description: Australian state or territory. example: VIC location_type: type: string description: Type of location. Values are `street`, `locality` (suburb), or `state`. example: street highlighted_full_location: type: string description: >- When highlighting is enabled, contains the full location string with highlighted matching terms. example: "<span class='af_hl'>Kent</span> <span class='af_hl'>Road</span>, <span class='af_hl'>MASCOT</span> NSW 2020" success: type: boolean description: True if the service ran successfully. example: true "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/AU.Address.Error" /au/location/metadata: get: summary: Location Metadata API x-doc-meta-title: Location Metadata API (AU) x-doc-meta-description: Return the full metadata associated with an Australian location (street, suburb or state) selected from the Location Autocomplete API operationId: au-location-metadata-api description: > The Location Metadata API is used to collect the metadata associated with a location selected from the Location Autocomplete API. This includes attributes like full location string, state, postcode, latitude/longitude, and street details. tags: - Australia parameters: - name: key in: query required: true description: Your unique Addressfinder license key. schema: type: string example: ADDRESSFINDER_DEMO_KEY - name: format in: query required: true description: The format of the response. schema: type: string enum: [json, xml] default: json example: json - name: id in: query required: true description: Unique location identifier obtained from the Location Autocomplete API. schema: type: string example: 90089d44-f86e-11ef-8948-2e2a976ffd19 - name: domain in: query required: false description: > Used to identify in the Addressfinder Portal which of your services is calling the API. The domain needs to be registered in the Portal. schema: type: string example: example.com responses: "200": description: Metadata for the selected location content: application/json: schema: type: object properties: full_location: type: string description: Full location string. example: Martin Street, NYABING WA 6341 location_type: type: string description: Type of location. Values are `street`, `locality` (suburb), or `state`. example: street latitude: type: string description: Latitude coordinate in WGS84 format. example: -33.54227326 longitude: type: string description: Longitude coordinate in WGS84 format. example: 118.14670128 street_name: type: string description: Name of the street without type or suffix. example: Martin street_type: type: string description: The street type. example: Street street: type: string description: The full name of the street. example: Queen Street North street_suffix: type: string description: The suffix of the street. Typically contains a compass direction. example: North locality_name: type: string description: The locality or suburb of this address. example: KATOOMBA state_territory: type: string description: The state or territory where the address is located. example: NSW postcode: type: string description: The 4 digits postcode. example: "0983" success: type: boolean description: Returns true if the service ran successfully. example: true "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/AU.Address.Error" /nz/address/autocomplete: get: summary: Address Autocomplete API x-doc-meta-title: Address Autocomplete API (NZ) x-doc-meta-description: Interactive search that returns closely matching New Zealand addresses which are then selected by the user tags: - New Zealand operationId: nz-address-autocomplete-api description: > The Address Autocomplete API is used to search the Addressfinder database to return closely matching addresses which can then be selected from by the user. This API works in tandem with the Address Metadata API which is used to load the metadata associated with the selected address. parameters: - in: query name: key description: Your unique licence key (find on Portal credentials) required: true schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: q description: The partial address being searched required: false schema: type: string example: 184 will - in: query name: format description: The required format of the response. schema: type: string enum: - json - xml default: json example: json - in: query name: delivered description: > This filter determines if the results are either delivered or not delivered by NZ Post: * `0` A rarely used option that excludes addresses that NZ Post deliver to. * `1` - Only returns addresses that are delivered to by NZ Post. * Omit to not filter. Returns delivered and non-delivered addresses in the response. required: false schema: type: string enum: - "0" - "1" - in: query name: post_box description: | This filter includes/excludes PO Box style addresses. * `0` - Excludes PO Box type addresses from being returned in the response. * `1` - Returns only PO Box, Private Bag, Community Mailbox and Counter Delivery address types. * Omit to not filter. Returns PO Box type and standard addresses in the response. required: false schema: type: string enum: - "0" - "1" - in: query name: rural description: | This filter includes/excludes rural/urban addresses: * `0` - Excludes addresses likely to be considered rural by a courier company. * `1` - A rarely used option that returns rural addresses only. * Omit to not filter. Returns rural and urban addresses in the response required: false schema: type: string enum: - "0" - "1" - in: query name: strict description: > Determines how closely matched the results should be to the `q` parameter: * `0` - Normal search - Allows some address elements to be omitted but does not allow spelling errors. * `1` - Strict search - Requires all address elements entered in `q` to be ordered and spelt correctly. * `2` - Fuzzy search - Allows spelling errors and inaccurate address elements. required: false schema: type: string enum: - "0" - "1" - "2" default: "2" - in: query name: region_code description: > Only return addresses within the boundary of the selected region (Regional Authority): * `1` - Only returns addresses from the Auckland Region * `2` - Only returns addresses from the Bay of Plenty Region * `3` - Only returns addresses from the Canterbury Region * `4` - Only returns addresses from the Gisbourne Region * `5` - Only returns addresses from the Hawke's Bay Region * `6` - Only returns addresses from the Manawatu-Wanganui Region * `7` - Only returns addresses from the Marlborough Region * `8` - Only returns addresses from the Nelson Region * `9` - Only returns addresses from the Northland Region * `A` - Only returns addresses from the Otago Region * `B` - Only returns addresses from the Southland Region * `C` - Only returns addresses from the Taranaki Region * `D` - Only returns addresses from the Tasman Region * `E` - Only returns addresses from the Waikato Region * `F` - Only returns addresses from the Wellington Region * `G` - Only returns addresses from the West Coast Region * `H` - Only returns addresses from the Chatham Islands Region * Omit to not filter. Returns addresses from all Regions required: false schema: type: string enum: - "1" - "2" - "3" - "4" - "5" - "6" - "7" - "8" - "9" - A - B - C - D - E - F - G - H - in: query name: domain description: > Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. required: false schema: type: string - in: query name: max description: The maximum number of results to return. The default is 10 results. required: false schema: type: integer minimum: 1 maximum: 100 default: 10 - in: query name: highlight description: > Returns an additional attribute in the response called highlighted_a. This attribute wraps the matching terms in the address with `` in order to highlight those terms: * `1` - Highlighted. * Omit to not return additional `highlighted_a` property required: false schema: type: string enum: - "1" - in: query name: ascii description: > 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*). required: false schema: type: string enum: - "1" responses: "200": description: OK content: application/json: schema: type: object properties: completions: type: array description: >- The API response will contain all the addresses and associated IDs (pxid) in the format requested in the API request. items: $ref: "#/components/schemas/NZ.Address.Autocomplete" success: type: boolean description: Indicates if the request was successful or not. example: true "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/NZ.Address.Error" /nz/address/metadata: get: summary: Address Metadata API x-doc-meta-title: Address Metadata API (NZ) x-doc-meta-description: Return the full metadata associated with an address selected from the Address Autocomplete API tags: - New Zealand operationId: nz-address-metadata-api description: > The Address Metadata API is used to collect the metadata associated with an address selected from the Address Autocomplete API parameters: - in: query name: key description: Your unique licence key (find on Portal credentials) required: true schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: format description: The required format of the response. schema: type: string enum: - json - xml default: json example: json - in: query name: pxid description: > Unique address identifier obtained from the NZ Address Autocomplete or NZ Address Bounding Box APIs. You must supply either a pxid or dpid field. required: false schema: type: string example: 2-.F.1W.p.0G1Jx - in: query name: dpid description: | Unique reference number assigned to a delivery address by NZ Post. You must supply either a pxid or dpid field. required: false schema: type: string - in: query name: census description: Desired data source for Statistics NZ metadata. required: false schema: type: integer enum: - 2018 - 2023 default: 2023 - in: query name: domain description: > Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. required: false schema: type: string - in: query name: ascii description: > 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*). required: false schema: type: string enum: - "1" responses: "200": description: >- The API response will contain a hash with an element named completions, which is an array of hashes. content: application/json: schema: $ref: "#/components/schemas/NZ.Address.Metadata" "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/NZ.Address.Error" /nz/address/verification: get: summary: Address Verification API x-doc-meta-title: Address Verification API (NZ) x-doc-meta-description: Takes a New Zealand address (potentially containing spelling mistakes and/or other errors) and attempts to match it against a verified address record in the Addressfinder database tags: - New Zealand operationId: nz-address-verification-api description: > 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. parameters: - in: query name: key description: Your unique licence key (find on Portal credentials) required: true schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: format description: The required format of the response. schema: type: string enum: - json - xml default: json example: json - in: query name: q description: The address to be verified. required: false schema: type: string example: 1 Ghuznee Street, Te Aro, Wellington 6011 - in: query name: post_box description: | This filter includes/excludes PO Box style addresses. * `0` - Excludes PO Box type addresses from being returned in the response. * `1` - Returns only PO Box, Private Bag, Community Mailbox and Counter Delivery address types. * Omit to not filter. Returns PO Box type and standard addresses in the response. required: false schema: type: string enum: - "0" - "1" - in: query name: region_code description: > Will only match and return an address if exists within the selected region (Regional Authority). Including a region can improve your match success rate as it removes the possibility of matching addresses outside the selected region. * `1` - Only returns addresses from the Auckland Region * `2` - Only returns addresses from the Bay of Plenty Region * `3` - Only returns addresses from the Canterbury Region * `4` - Only returns addresses from the Gisbourne Region * `5` - Only returns addresses from the Hawke's Bay Region * `6` - Only returns addresses from the Manawatu-Wanganui Region * `7` - Only returns addresses from the Marlborough Region * `8` - Only returns addresses from the Nelson Region * `9` - Only returns addresses from the Northland Region * `A` - Only returns addresses from the Otago Region * `B` - Only returns addresses from the Southland Region * `C` - Only returns addresses from the Taranaki Region * `D` - Only returns addresses from the Tasman Region * `E` - Only returns addresses from the Waikato Region * `F` - Only returns addresses from the Wellington Region * `G` - Only returns addresses from the West Coast Region * `H` - Only returns addresses from the Chatham Islands Region * Omit to not filter. Returns addresses from all Regions required: false schema: type: string enum: - "1" - "2" - "3" - "4" - "5" - "6" - "7" - "8" - "9" - A - B - C - D - E - F - G - H - in: query name: census description: Desired data source for Statistics NZ metadata. required: false schema: type: integer enum: - 2018 - 2023 default: 2023 - in: query name: domain description: > Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. required: false schema: type: string - in: query name: ascii description: > 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*). required: false schema: type: string enum: - "1" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/NZ.Address.Verification" "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/NZ.Address.Error" /nz/location/autocomplete: get: summary: Location Autocomplete API x-doc-meta-title: Location Autocomplete API (NZ) x-doc-meta-description: Interactive search that returns closely matching New Zealand streets, suburbs, cities and/or regions which are then selected by the user operationId: nz-location-autocomplete-api description: > This API lets you search for streets, suburbs, cities, and/or regions — collectively called "locations". The filters (like `street`, `suburb`, `city`, `region`) are applied additively. To return multiple location types, exclude the location types you don’t want. Example: To search for suburbs and cities only, set `street=0` and `region=0`. This API works in tandem with the Location Metadata API. tags: - New Zealand parameters: - name: key in: query required: true description: Your unique Addressfinder license key (find on Portal credentials). schema: type: string example: ADDRESSFINDER_DEMO_KEY - name: q in: query required: true description: The query string to be matched with the location. schema: type: string example: "rankin" - name: format in: query required: true description: The format of the response. schema: type: string enum: [json, xml] default: json - name: street in: query required: false description: "Set to 0 to exclude streets, 1 to include only streets." schema: type: string enum: ["0", "1"] - name: suburb in: query required: false description: "Set to 0 to exclude suburbs, 1 to include only suburbs." schema: type: string enum: ["0", "1"] - name: city in: query required: false description: "Set to 0 to exclude cities, 1 to include only cities." schema: type: string enum: ["0", "1"] - name: region in: query required: false description: "Set to 0 to exclude regions, 1 to include only regions." schema: type: string enum: ["0", "1"] - name: region_code in: query required: false description: > Restricts results to a region. Valid codes include: Auckland `1`, Bay of Plenty `2`, Canterbury `3`, Gisborne `4`, Hawke's Bay `5`, Manawatū-Whanganui `6`, Marlborough `7`, Nelson `8`, Northland `9`, Otago `A`, Southland `B`, Taranaki `C`, Tasman `D`, Waikato `E`, Wellington `F`, West Coast `G`, Chatham Islands `H`. schema: type: string - name: strict in: query required: false description: > Match strictness: - `0`: normal (no spelling errors) - `1`: strict (must be ordered and spelled correctly) - `2`: fuzzy (allows misspelling) schema: type: string enum: ["0", "1", "2"] default: "0" - name: domain in: query required: false description: > Used to identify the calling service in the Addressfinder Portal. Must be a registered domain. schema: type: string example: example.com - name: max in: query required: false description: Max results to return (1–100). schema: type: integer minimum: 1 maximum: 100 default: 10 - name: highlight in: query required: false description: > Set to 1 to return an attribute `highlighted_a` which wraps matched text with ``. schema: type: integer enum: [0, 1] responses: "200": description: A list of location autocomplete completions content: application/json: schema: type: object properties: completions: type: array items: type: object properties: a: type: string description: Canonical location as supplied by data sources. example: Willcox Grove, Naenae, Lower Hutt pxid: type: string description: Unique identifier for the location. example: 1-.F.b.M.1C highlighted_a: type: string description: >- When highlighting is enabled, contains the full location string with highlighted matching terms. success: type: boolean description: True if the request completed successfully. example: true "400": description: Invalid input or missing required parameters. content: application/json: schema: type: object properties: error: type: string example: Missing required parameter 'key' /nz/location/metadata: get: summary: Location Metadata API x-doc-meta-title: Location Metadata API (NZ) x-doc-meta-description: Return the full metadata associated with a location (street, suburb, city or region selected from the Location Autocomplete API operationId: nz-location-metadata-api description: > The Location Metadata API is used to collect metadata associated with a location selected from the New Zealand Location Autocomplete API. The response includes geographic coordinates, canonical address formatting, and location metadata from LINZ. tags: - New Zealand parameters: - name: key in: query required: true description: Your unique Addressfinder license key. schema: type: string example: ADDRESSFINDER_DEMO_KEY - name: format in: query required: true description: The format of the response. schema: type: string enum: [json, xml] default: json example: json - name: pxid in: query required: true description: Unique address identifier from the Location Autocomplete API. schema: type: string example: 1-.B.11.4.2H - name: domain in: query required: false description: > Used to identify your calling service for usage tracking in the Addressfinder Portal. Must be registered in the Portal. schema: type: string example: example.com responses: "200": description: Location metadata for the selected pxid content: application/json: schema: type: object properties: pxid: type: string description: The unique location identifier. example: 1-.B.11.4.2H a: type: string description: Canonical location string. example: Seaview Road, Glenfield, Auckland x: type: number format: double description: Longitude in WGS84. example: 174.643199 y: type: number format: double description: Latitude in WGS84. example: -36.426956 success: type: boolean description: Whether the request completed successfully. example: true street: type: string description: Street name and type (from LINZ). example: Martin Street suburb: type: string description: Suburb or locality name (from LINZ). example: Gore city: type: string description: City, town, or locality (from LINZ). example: Gore region: type: string description: Regional Authority (from LINZ). example: Southland Region "400": description: Invalid input or missing parameters. content: application/json: schema: type: object properties: error: type: string example: Missing required parameter 'pxid' /nz/points_of_interest/autocomplete: get: summary: POI Autocomplete API x-doc-meta-title: Points of Interest Autocomplete API (NZ) x-doc-meta-description: Interactive search that returns closely matching points of interest and their associated addresses operationId: nz-poi-autocomplete-api description: > This API returns matching points of interest based on a partial name and optional filters. It works in tandem with the POI Metadata API, which is used to collect additional metadata about the selected POI. tags: - New Zealand parameters: - name: key in: query required: true description: Your unique Addressfinder license key. schema: type: string example: ADDRESSFINDER_DEMO_KEY - name: q in: query required: true description: The query string to match against POI names and addresses. schema: type: string example: auckland hospital - name: format in: query required: true description: The format of the response. schema: type: string enum: [json, xml] default: json example: json - name: domain in: query required: false description: > Used to identify your service in the Addressfinder Portal. Must be a registered domain in the Portal. schema: type: string - name: max in: query required: false description: Maximum number of results to return (1–100). schema: type: integer default: 10 minimum: 1 maximum: 100 - name: highlight in: query required: false description: > Set to `1` to include `highlighted_name_and_address` in results, wrapping matched text with ``. schema: type: integer enum: [0, 1] responses: "200": description: A list of matching points of interest content: application/json: schema: type: object properties: completions: type: array items: type: object properties: name_and_address: type: string description: Full name of the POI followed by its address. example: Middlemore Hospital, 100 Hospital Road, Middlemore Hospital, Auckland 2024 id: type: string description: The unique POI identifier. example: 3300 highlighted_name_and_address: type: string description: Highlighted string (if `highlight=1`). example: "Hospital, 100 Hospital Road..." success: type: boolean description: True if the request was successful. example: true "400": description: Invalid input or missing parameters. content: application/json: schema: type: object properties: error: type: string example: Missing required parameter 'q' /nz/points_of_interest/metadata: get: summary: POI Metadata API x-doc-meta-title: Points of Interest Metadata API (NZ) x-doc-meta-description: Return the full metadata associated with a point of interest selected from the Points of Interest Autocomplete API operationId: nz-poi-metadata-api description: > The Points of Interest Metadata API is used to collect metadata for a POI selected from the Points of Interest Autocomplete API. Metadata includes location, street, region, LINZ and NZ Post data. tags: - New Zealand parameters: - name: key in: query required: true description: Your unique Addressfinder license key. schema: type: string example: ADDRESSFINDER_DEMO_KEY - name: format in: query required: true description: Response format (`json` or `xml`). schema: type: string enum: [json, xml] example: json - name: id in: query required: true description: Unique POI identifier from the autocomplete API. schema: type: string example: 2457 - name: domain in: query required: false description: > Used to identify your service in the Addressfinder Portal. Must be registered in the Portal. schema: type: string responses: "200": description: Metadata for the selected point of interest content: application/json: schema: type: object properties: pxid: type: string description: The unique point of interest identifier. example: 2457 name: type: string description: Name of the point of interest. example: Middle School West Auckland x: type: string description: Longitude (WGS84). example: "174.643199" y: type: string description: Latitude (WGS84). example: "-36.426956" address_pxid: type: string description: Unique identifier for the associated address. example: 2-.1.6.t.25oRi number: type: string description: Street number (or PO box number). example: 287-289 alpha: type: string nullable: true description: Alpha suffix from address (e.g. "B" in "1B"). postcode: type: string description: Four-digit postcode. example: "0983" rd_number: type: string nullable: true description: NZ Post rural delivery number. a: type: string description: Canonical full address. example: 287-289 Lincoln Road, Henderson, Auckland 0610 postal: type: string nullable: true description: Postal address (if NZ Post delivers here). mailtown: type: string nullable: true description: Mailtown from NZ Post (if available). post_suburb: type: string nullable: true description: Postal suburb (if available). ta: type: string description: Territorial Authority (LINZ). example: Auckland aims_address_id: type: integer description: LINZ AIMS Address ID. example: 1518959 sufi: type: integer description: Same as `aims_address_id`, returned as integer. example: 1518959 street_type: type: string nullable: true description: Street type (e.g. Road, Avenue). example: Road building_name: type: string nullable: true description: Building name if available. city: type: string description: City, town or locality. example: Warkworth suburb: type: string description: Suburb or locality. example: Henderson region: type: string description: Regional Authority. example: Auckland Region street: type: string description: Full street name and type. example: Lincoln Road postal_line_1: type: string nullable: true description: NZ Post Line 1 example: 287-289 Lincoln Road postal_line_2: type: string nullable: true description: NZ Post Line 2 example: Henderson postal_line_3: type: string nullable: true description: NZ Post Line 3 example: Auckland postal_line_4: type: string nullable: true description: NZ Post Line 4 postal_line_5: type: string nullable: true description: NZ Post Line 5 meshblock: type: string nullable: true description: Meshblock identifier for census. example: 146004 dpid: type: string nullable: true description: Unique identifier from NZ Post. example: 2668726 success: type: boolean description: Whether the request was successful. example: true "400": description: Missing or invalid parameters content: application/json: schema: type: object properties: error: type: string example: Missing required parameter 'id' /nz/address/reverse_geocode: get: summary: Address Reverse Geocode API x-doc-meta-title: Address Reverse Geocode API (NZ) x-doc-meta-description: Takes the GPS coordinates (longitude and latitude) and returns the nearest addresses ordered by distance operationId: nz-address-reverse-geocode-api description: > This API takes GPS coordinates (latitude and longitude) and returns the nearest matching addresses, ordered by distance. It works in tandem with the Address Metadata API to load detailed information for a selected address. tags: - New Zealand parameters: - name: key in: query required: true description: Your unique Addressfinder license key. schema: type: string example: ADDRESSFINDER_DEMO_KEY - name: format in: query required: true description: Response format. schema: type: string enum: [json, xml] default: json example: json - name: x in: query required: true description: Longitude in WGS84 format. schema: type: string example: 174.773068233188 - name: y in: query required: true description: Latitude in WGS84 format. schema: type: string example: -41.2917018846201 - name: domain in: query required: false description: > Used to identify your service in the Addressfinder Portal. Must be registered in the Portal. schema: type: string example: example.com - name: max in: query required: false description: Maximum number of results to return (1–100). schema: type: integer default: 10 minimum: 1 maximum: 100 responses: "200": description: Closest addresses to the provided coordinates content: application/json: schema: type: object properties: success: type: boolean description: True if the query completed successfully. example: true completions: type: array items: type: object properties: a: type: string description: Canonical address. example: 184 Willis Street, Te Aro, Wellington 6011 pxid: type: string description: Unique address identifier. example: 2-.F.1W.p.0G1Jx "400": description: Invalid input or missing required parameters content: application/json: schema: type: object properties: error: type: string example: Missing required parameter 'x' /email/v1/verification: get: summary: Email Verification API x-doc-meta-title: Email Verification API x-doc-meta-description: The Email Verification API takes an email address (potentially containing spelling mistakes and/or other errors) and validates the syntax, the existence and availability of the domain, the existence of the email account, and returns a verified state and other metadata. tags: - Global operationId: email-verification-api description: > The Email Verification API takes an email address (potentially containing spelling mistakes and/or other errors) and validates the syntax, the existence and availability of the domain, the existence of the email account, and returns a verified state and other metadata. parameters: - in: query name: key description: Your unique licence key (find on Portal credentials) required: true schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: format description: The required format of the response. schema: type: string enum: - json - xml default: json example: json - in: query name: email description: The email to be verified. required: false schema: type: string example: john.doe@addressfinder.com - in: query name: domain description: >- Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. required: false schema: type: string - in: query name: features description: >- A comma-separated list of parameters that controls the methods of verification to be completed. This will impact the query processing time and data returned in the response. Options: * `domain` checks if the domain is configured to receive emails; * `connection` checks if the email account exists; * `provider` checks and returns the email service provider. required: false schema: type: string default: domain,connection responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Email.Address.Verification" "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/Email.Address.Error" /phone/v1/verification: get: summary: Phone Verification API x-doc-meta-title: Phone Verification API x-doc-meta-description: The Phone Verification API acts to verify a supplied number through a process which involves syntax and range checks prior to a network check for a connection status. The API returns the verified number, line type, connection status and other metadata. tags: - Global operationId: phone-verification-api description: > The Phone Verification API verifies a supplied number through a process which involves syntax and range checks prior to a network check for a connection status. parameters: - in: query name: key description: Your unique licence key (find on Portal credentials) required: true schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: format description: The required format of the response. schema: type: string enum: - json - xml default: json example: json - in: query name: phone_number description: The phone number to be verified. required: true schema: type: string example: 61285038000 - in: query name: domain description: >- Used to identify which of your services is calling the API for activity monitoring purposes. This domain needs to be registered in the portal. required: false schema: type: string - in: query name: default_country_code description: >- The iso2 country code to be used by default when the phone number does not include a country calling code. required: true schema: type: string example: AU - in: query name: mobile_only description: Require that the supplied number is a mobile phone. required: false schema: type: boolean default: 0 example: 1 - in: query name: timeout description: >- Maximum wait time permitted when verifying the number. If exceeded, will return a status of indeterminate. required: false schema: type: number example: 10 - in: query name: allowed_country_codes description: >- Require that the supplied phone number is registered in one of these supplied countries (comma separated using iso2 codes). required: false schema: type: string example: AU,NZ responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Phone.Verification" "400": description: | Bad request content: application/json: schema: $ref: "#/components/schemas/Phone.Verification.Error" /{country}/address/v2/autocomplete: get: summary: International Address Autocomplete API x-doc-meta-title: Address Autocomplete API - International x-doc-meta-description: Search API that returns closely matching international addresses which are then selected by the user operationId: int-address-autocomplete-api description: > This API is used to power the autocomplete capability of the Addressfinder JS widget and integrations. It can also be used to power your own custom autocomplete functionality, such as in a mobile or desktop app. This API works in tandem with the Address Metadata API which is used to collect the metadata associated with the selected address. Replace `country` in the path with the ISO 3166 alpha-2 code of the country you are searching in. Supported countries include: au, be, ca, cz, dk, fr, de, ie, nz, nl, pt, sg, es, se, gb, us. tags: - international parameters: - in: path name: country required: true description: ISO 3166 alpha-2 country code. schema: type: string example: fr - in: query name: key required: true description: Your unique Addressfinder license key. schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: q required: true description: The partial address being searched. Max length 200 characters. schema: type: string example: 15 Rue Sa - in: query name: format required: false description: The format of the response. schema: type: string enum: [json, xml] default: json example: json - in: query name: domain required: false description: > Used to identify in the Addressfinder Portal which of your services is calling the API for activity monitoring purposes. The domain needs to be registered in the Portal. schema: type: string example: example.com - in: query name: max required: false description: The maximum number of results to return. Between 1 and 15 (inclusive). schema: type: integer minimum: 1 maximum: 15 default: 10 responses: "200": description: A list of address completions content: application/json: schema: type: object properties: completions: type: array items: type: object properties: id: type: string description: The unique address identifier. example: _wEzMQD-UiYLas2j_kKyVwD-SRj_AcOp9f8ENzc3MjAA_keCPTwm2sz-QgTw6sz-Q09zJQ full_address: type: string description: Canonical address as supplied by our data sources. example: 31 Rue de la Belle Idée, 77720 Grandpuits-Bailly-Carrois success: type: boolean description: Returns true if the service ran successfully. example: true "400": description: Invalid input or missing parameters. content: application/json: schema: type: object properties: error: type: string description: Description of the error example: Missing required parameter 'key' /{country}/address/v2/metadata: get: summary: International Address Metadata API x-doc-meta-title: Address Metadata API - International x-doc-meta-description: Return the full metadata associated with an address selected from the International Address Autocomplete API operationId: int-address-metadata-api description: > The address metadata API is used to collect the metadata associated with an address selected from the Address Autocomplete API. Replace `{country}` in the path with the ISO 3166 alpha-2 code of the country where the address is located. Supported countries include: au, be, ca, cz, dk, fr, de, ie, nz, nl, pt, sg, es, se, gb, us. tags: - international parameters: - in: path name: country required: true description: ISO 3166 alpha-2 country code. schema: type: string example: fr - in: query name: key required: true description: Your unique Addressfinder license key. schema: type: string example: ADDRESSFINDER_DEMO_KEY - in: query name: format required: true description: The format of the response. schema: type: string enum: [json, xml] default: json example: json - in: query name: id required: true description: Unique address identifier obtained from the Address Autocomplete API. schema: type: string example: _wExNQD-UiYL_lMED0XM_k1PCPX_BDkyMjMwAP5HM4tt8JcbCg - in: query name: gps required: false description: Include GPS coordinates in the results if available (0 or 1). schema: type: integer enum: [0, 1] default: 0 - in: query name: domain required: false description: > Used to identify in the Addressfinder Portal which of your services is calling the API for activity monitoring purposes. The domain needs to be registered in the Portal. schema: type: string example: example.com responses: "200": description: Metadata for the selected address content: application/json: schema: type: object properties: id: type: string description: The unique address identifier. example: _wEzMQD-UiYLas2j_kKyVwD... address: type: object properties: full_address: type: string description: Full address in the country-specific format. example: 123 Edward St, Silver Berry, Toronto ON M5G address_line_1: type: string description: First address line. example: 123 Edward St address_line_2: type: string description: Second address line. example: Silver Berry address_line_combined: type: string description: Combined address lines 1 and 2. example: 123 Edward St, Silver Berry city: type: string description: City, town or locality name. example: Toronto city_line: type: string description: City formatted for postal services. example: Toronto ON M5G state: type: string description: Country-specific state or region. example: ON postcode: type: string description: Country-specific postcode or zipcode. example: M5G country_name: type: string description: Country name. example: Canada country_code: type: string description: ISO 3166 alpha-2 country code. example: CA metadata: type: object properties: street: type: string description: Full street name. example: Edward St street_number: type: string description: Street number. example: 123 position: type: object properties: latitude: type: number format: double example: 48.5827 longitude: type: number format: double example: 2.96747 success: type: boolean description: Returns true if the service ran successfully. example: true "400": description: Invalid input or missing parameters. content: application/json: schema: type: object properties: error: type: string description: Description of the error example: Missing required parameter 'id' components: schemas: AU.Address.Autocomplete: type: object description: >- The API response will contain all the addresses and associated IDs (pxid) in the format requested in the API request. required: - full_address - id - canonical_address_id properties: full_address: type: string description: Full address string. example: Unit 2, 21 Kent Road, DAPTO NSW 2530 id: type: string description: >- The unique address identifier. This ID will change following a data refresh. example: c10cf706-2e2e-4fe1-887c-156e6118ab76 canonical_address_id: type: string description: > 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. example: a4c4f26d-7327-40cc-9d05-ca94bd94a354 highlighted_full_address: type: string description: >- When highlighting is enabled, contains the full address string with highlighted matching terms. example: >- Unit <span class='af_hl'>2</span>, <span class='af_hl'>21</span> <span class='af_hl'>Kent</span> <span class='af_hl'>Road</span>, DAPTO NSW 2530 AU.Address.Metadata: type: object description: >- All the addresses and associated IDs (pxid) in the format requested in the API request. required: - full_address - id - locality_name - state_territory - postcode - address_line_1 - success properties: full_address: type: string description: Full address string. example: 13 Neville Street, RYDE NSW 2112 x-tags: - gnaf - paf - gnaf-paf id: type: string description: >- The unique address identifier. This ID will change following a data refresh. example: 8097e3df-a3ab-43ad-bc66-22c8f5812361 x-tags: - gnaf - paf - gnaf-paf canonical_address: type: string description: >- 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. example: 11-15 Neville Street, RYDE NSW 2112 x-tags: - gnaf - paf - gnaf-paf canonical_address_id: type: string description: > 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. example: d70230a9-a3d8-402f-971e-1b798d00f2f5 x-tags: - gnaf - paf - gnaf-paf latitude: type: string description: >- Latitude coordinate (in WGS84 format) from the G-NAF dataset, or PAF dataset (for PAF-only addresses). example: -37.899031 x-tags: - gnaf - paf - gnaf-paf longitude: type: string description: >- Longitude coordinate (in WGS84 format) from the G-NAF dataset, or PAF dataset (for PAF-only addresses). example: 144.99953 x-tags: - gnaf - paf - gnaf-paf lot_identifier: type: string description: >- Identifies a specific lot on a site. Can be an alpha, number or a combination. example: 3 x-tags: - gnaf - paf - gnaf-paf box_identifier: type: string description: The number portion of a PO Box address example: 123 x-tags: - gnaf - paf - gnaf-paf box_type: type: string description: >- The type portion of a PO Box address, including `PO Box`, `Locked Bag`, `GPO Box`, `CMB`, `RMS`, `Care PO`, `MS` and `RSD` example: PO Box x-tags: - gnaf - paf - gnaf-paf site_name: type: string description: >- Holds the address element that identifies the name of a site or building. example: Kenilworth Police Station x-tags: - gnaf - paf - gnaf-paf level_type: type: string description: Describes the level type within a multi-level building. example: Basement x-tags: - gnaf - paf - gnaf-paf level_number: type: string description: >- Identifies a specific level within a multi-level building. Can be an alpha, number or a combination. example: 3 x-tags: - gnaf - paf - gnaf-paf unit_type: type: string description: Describes the category of a sub-dwelling. example: Suite x-tags: - gnaf - paf - gnaf-paf unit_identifier: type: string description: >- Identifies a specific sub-dwelling. Can be an alpha, number or a combination. example: 2 x-tags: - gnaf - paf - gnaf-paf street_number_1: type: string description: The number of the building on the street. example: 1703 x-tags: - gnaf - paf - gnaf-paf street_number_2: type: string description: >- Holds the upper bound when this is a ranged address. For single number addresses this field is `null` example: 1705 x-tags: - gnaf - paf - gnaf-paf street: type: string description: >- 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. example: Queen Street North x-tags: - gnaf - paf - gnaf-paf street_name: type: string description: >- Holds the name of the street. Note This attribute does not include the street type or suffix. example: Queen x-tags: - gnaf - paf - gnaf-paf street_type: type: string description: The type of street. example: Street x-tags: - gnaf - paf - gnaf-paf street_suffix: type: string description: The suffix of the street. Typically contains a compass direction. example: North x-tags: - gnaf - paf - gnaf-paf address_line_combined: type: string description: >- A combination of the first and second lines of the non-locality/state/postcode portion of the address. example: 274 Harbour Drive x-tags: - gnaf - paf - gnaf-paf locality_name: type: string description: The locality/suburb of this address. example: KATOOMBA x-tags: - gnaf - paf - gnaf-paf state_territory: type: string description: The Australian state or territory where the address is located. example: NSW x-tags: - gnaf - paf - gnaf-paf postcode: type: string description: Holds the four digit postcode. example: "0983" x-tags: - gnaf - paf - gnaf-paf address_line_1: type: string description: First line of the non-locality/state/postcode portion of the address example: Unit 209 x-tags: - gnaf - paf - gnaf-paf address_line_2: type: string description: >- Second line of the non-locality/state/postcode portion of the address. This will be `null` for addresses without a unit/level/etc number. example: 274 Harbour Drive x-tags: - gnaf - paf - gnaf-paf success: type: boolean description: Indicates if the request was successful or not. example: true x-tags: - gnaf - paf - gnaf-paf dpid: type: string description: >- Australia Post delivery point identifier. Only returned on canonical addresses from Australia Post when parameter `paf=1` supplied. example: 99119187 x-tags: - paf gnaf_id: type: string description: >- The unique persistent identifier of the G-NAF address. Only returned when parameter `gnaf=1` supplied. example: GANSW705051429 x-tags: - gnaf legal_parcel_id: type: string description: >- Government legal property description. Only returned when parameter `gnaf=1` supplied. example: 10//SP9489 x-tags: - gnaf meshblock: type: string description: > 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 `2016` and `2021` census. Defaults to `2016` if not provided. Only returned when parameter `gnaf=1` supplied. example: MB1610671120000 x-tags: - gnaf sa1_id: type: string description: > 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 `2016` and `2021` census. Defaults to `2016` if not provided. Only returned when parameter `gnaf=1` supplied. example: 12602159143 x-tags: - gnaf sa2_id: type: string description: >- 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 `2016` and `2021` census. Defaults to `2016` if not provided. Only returned when parameter `gnaf=1` supplied. example: 126021591 x-tags: - gnaf lga_name: type: string description: >- The name of the Local Government Area in which the address is located.
**The `source` must be set to `gnaf`.** example: Bundaberg x-tags: - gnaf lga_type_code: type: string description: >- 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`.** example: DC x-tags: - gnaf AU.Address.Verification: type: object description: >- All the addresses metadata associated in the format requested in the API request. required: - matched - success - address properties: matched: type: boolean description: Indicates if the address has been matched or not. example: true success: type: boolean description: Indicates if the request was successful or not. example: true address: type: object description: description text required: - id - full_address - address_line_1 - address_line_2 - address_line_combined - locality_name - state_territory - postcode - latitude - longitude - box_identifier - box_type - street_number_1 - street_number_2 - unit_identifier - unit_type - level_number - level_type - lot_identifier - site_name - street_name - street_type - street_suffix - street - meshblock - sa1_id - sa2_id - lga_name - lga_type_code - gnaf_id - legal_parcel_i properties: id: type: string description: >- The unique address identifier. This ID will change following a data refresh. example: 73e8268c-bd5c-57a0-c20c-bcce334fe361 x-tags: - gnaf - paf - gnaf-paf full_address: type: string description: Full address string. example: 274 Harbour Drive, COFFS HARBOUR NSW 2450 x-tags: - gnaf - paf - gnaf-paf address_line_1: type: string description: >- First line of the non-locality/state/postcode portion of the address. example: 274 Harbour Drive x-tags: - gnaf - paf - gnaf-paf address_line_2: type: string description: >- Second line of the non-locality/state/postcode portion of the address. This will be null for addresses without a unit/level/etc number. example: null x-tags: - gnaf - paf - gnaf-paf address_line_combined: type: string description: >- A combination of the first and second lines of the non-locality/state/postcode portion of the address. example: 274 Harbour Drive x-tags: - gnaf - paf - gnaf-paf locality_name: type: string description: The locality/suburb of this address. example: COFFS HARBOUR x-tags: - gnaf - paf - gnaf-paf state_territory: type: string description: The Australian state or territory where the address is located. example: NSW x-tags: - gnaf - paf - gnaf-paf postcode: type: string description: >- Holds the four digit postcode. example: 2450 x-tags: - gnaf - paf - gnaf-paf latitude: type: string description: Latitude coordinate (in WGS84 format). example: -30.304978 x-tags: - gnaf - paf - gnaf-paf longitude: type: string description: Longitude coordinate (in WGS84 format). example: 153.126321 x-tags: - gnaf - paf - gnaf-paf box_identifier: type: string description: >- Identifies a specific box. Can be an alpha, number or a combination. example: null x-tags: - paf box_type: type: string description: Describes the type of box. example: null x-tags: - paf street_number_1: type: string description: The number of the building on the street. example: 274 x-tags: - gnaf - paf - gnaf-paf street_number_2: type: string description: >- Holds the upper bound when this is a ranged address. For single number addresses this field is `null` example: null x-tags: - gnaf - paf - gnaf-paf unit_identifier: type: string description: >- Identifies a specific sub-dwelling. Can be an alpha, number or a combination. example: null x-tags: - gnaf - paf - gnaf-paf unit_type: type: string description: Describes the category of a sub-dwelling. example: null x-tags: - gnaf - paf - gnaf-paf level_number: type: string description: >- Identifies a specific level within a multi-level building. Can be an alpha, number or a combination. example: null x-tags: - gnaf - paf - gnaf-paf level_type: type: string description: Describes the level type within a multi-level building. example: null x-tags: - gnaf - paf - gnaf-paf lot_identifier: type: string description: >- Identifies a specific lot on a site. Can be an alpha, number or a combination. example: CP x-tags: - gnaf - paf - gnaf-paf site_name: type: string description: >- Holds the address element that identifies the name of a site or building. example: null x-tags: - gnaf - paf - gnaf-paf street_name: type: string description: Holds the name of the street. example: Harbour x-tags: - gnaf - paf - gnaf-paf street_type: type: string description: The type of street. example: Drive x-tags: - gnaf - paf - gnaf-paf street_suffix: type: string description: >- The suffix of the street. Typically contains a compass direction. example: null x-tags: - gnaf - paf - gnaf-paf street: type: string description: Holds the full name of the street. example: Harbour Drive x-tags: - gnaf - paf - gnaf-paf meshblock: type: string description: The meshblock identifier in which the address is located. example: null x-tags: - gnaf sa1_id: type: string description: >- The statistical area (SA1) identifier in which the address is located. example: null x-tags: - gnaf sa2_id: type: string description: >- The statistical area (SA2) identifier in which the address is located. example: null x-tags: - gnaf lga_name: type: string description: >- The name of the Local Government Area in which the address is located.
**The `source` must be set to `gnaf`.** example: Bundaberg x-tags: - gnaf lga_type_code: type: string description: >- 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`.** example: DC x-tags: - gnaf gnaf_id: type: string description: The unique persistent identifier of the G-NAF address. example: null x-tags: - gnaf legal_parcel_id: type: string description: Government legal property description. example: null x-tags: - gnaf AU.Address.Error: type: object description: An informative message when an error occurs handling an API request required: - error_code - message properties: completions: type: array description: An empty array will be returned due to the error items: type: object error_code: type: string description: A unique numerical value identifying the error that occured example: 1004 message: type: string description: An informative message describing the error that occured example: Secret not provided success: type: boolean description: Indicates that the result was a failure example: false NZ.Address.Autocomplete: type: object description: >- A closely matching addresses to the partial address being searched. The pxid can be used to obtain the metadata associated with the address. required: - a - pxid - v properties: a: type: string description: >- Canonical address as supplied by Land Information New Zealand or NZ Post. example: 184 Williams Street, Kaiapoi 7630 pxid: type: string description: The unique address identifier. example: 2-.3.1q.2.4G.4c v: type: integer description: | The value of this field indicates if this address is the postal or the physical version of the address. * `1` indicates this is the postal version of the address. * `0` indicates this is the physical version of the address. This field can be used to determine the version of the address that was selected by the customer. example: 0 highlighted_a: type: string description: >- When highlighting is enabled, contains the full address string with highlighted matching terms. example: >- 184 Williams Street, Kaiapoi 7630 NZ.Address.Metadata: type: object description: >- All the addresses and associated IDs (pxid) in the format requested in the API request. required: - a - city - postcode - x - "y" - region - pxid - success properties: a: type: string description: >- Canonical address as supplied by Land Information New Zealand or NZ Post. example: Unit 2, 1703A State Highway 1, Warkworth 0983 postal: type: string description: >- Associated postal address when supplied by NZ Post. Field will be omitted if this address is not delivered to by NZ Post. example: Unit 2, 1703A State Highway 1, RD 3, Warkworth 0983 building_name: type: string description: Holds the building or property name. example: Miban Building unit_type: type: string description: Describes the category of a sub-dwelling. example: Flat unit_identifier: type: string description: >- Identifies a specific sub dwelling. Can be alpha, number or a combination. example: 1 floor: type: string description: The level number and level type in a multi-story building. example: Level 19 number: type: string description: >- The street number of the address. Also populated with the box number for PO Box type addresses. example: 1703 alpha: type: string description: >- Holds the alpha component of a street number. In the address 1B High Street, B is the alpha. example: B street: type: string description: >- Holds the full name of the street. Note The street attribute also includes the Street Type. example: State Highway 1 street_name: type: string description: Holds the name of the street. example: Queen post_street: type: string description: Holds the street name and type from NZ Post, it will be omitted if the address is not delivered to by NZ Post. example: Purakaunui Road post_street_name: type: string description: Holds the street name from NZ Post, it will be omitted if the address is not delivered to by NZ Post. example: Purakaunui street_type: type: string description: The type of street. example: Avenue street_suffix: type: string description: The suffix of the street. Typically contains a compass direction. example: North suburb: type: string description: >- The suburb or locality of the address as assigned by Land Information New Zealand. example: Warkworth city: type: string description: >- The city, town or locality name as assigned by Land Information New Zealand. example: Warkworth box_type: type: string description: The type of PO Box/CMB/Private Bag/Counter Delivery. example: PO Box lobby_name: type: string description: >- The name of the NZ Post outlet or Agency outlet where the PO Box, Private Bag or Counter Delivery is located. example: Fendalton rd_number: type: string description: The rural delivery number assigned by NZ Post to a rural address. example: 4 post_suburb: type: string description: Name of the suburb when supplied by NZ Post. example: Manukau mailtown: type: string description: Name of the town/city when supplied by NZ Post. example: Warkworth postcode: type: string description: Holds the four digit postcode. example: "0983" dpid: type: string description: >- A unique reference number assigned to each delivery address by NZ Post. example: 2668726 primary_parcel_id: type: string description: >- The unique identifier of the portion of land associated with the selected address. example: 3866475 x: type: string description: Longitude coordinate (in WGS84 format). example: 174.643199 "y": type: string description: Latitude coordinate (in WGS84 format). example: -36.426956 meshblock: type: string description: > The meshblock identifier for the requested census dataset (see census parameter). If not specified, the meshblock returned is from the 2023 census. example: 146004 sa1_id: type: string description: Statistical area 1 example: 7000010 sa2_id: type: string description: Statistical area 2 ID example: 100301 sa2: type: string description: Statistical area 2 name example: Rangaunu Harbour rural: type: boolean description: > An indicator to help determine if this address is located in a rural setting. Note Different courier companies have different rural/urban boundaries so this determination should be confirmed by your delivery agent. example: true ur: type: string description: Urban rural name (2018 census only) example: Kaimaumau ur_id: type: string description: Urban rural ID (2018 census only) example: 1002 iur: type: string description: Urban rural indicator name (2018 census only) example: Rural settlement iur_id: type: string description: Urban rural indicator ID (2018 census only) example: 21 aims_road_section_id: type: string description: >- The unique road section identifier from Land Information New Zealand (LINZ). example: 323309 postal_line_1: type: string description: Postal address line 1 example: 1 Ghuznee Street postal_line_2: type: string description: Postal address line 2 example: Te Aro postal_line_3: type: string description: Postal address line 3 example: Wellington 6011 postal_line_4: type: string description: Postal address line 4 postal_line_5: type: string description: Postal address line 5 region: type: string description: >- The Regional Authority in which this address exists. Note Regional Authorities are the top tier of local government in New Zealand. example: Auckland Region region_id: type: string description: Region ID (2018 census only) example: 4 ta: type: string description: >- The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. example: Auckland ta_id: type: string description: Territorial Authority ID (2018 census only) example: 48 sufi: type: integer description: Same as `aims_address_id`, returned as integer. example: 1518959 con: type: string description: Constituency name (2018 census only) example: Te Hiku Constituency con_id: type: string description: Constituency ID (2018 census only) example: 65 maoricon: type: string description: Maori Constituency name (2018 census only) example: Okurei Maori Constituency maoricon_id: type: string description: Maori Constituency ID (2018 census only) example: 258 ward: type: string description: Ward name (2018 census only) example: Banks Peninsula Ward ward_id: type: string description: Ward ID (2018 census only) example: 3086 cb: type: string description: Community Board name (2018 census only) example: Te Hiku Community cb_id: type: string description: Community Board ID (2018 census only) example: 65 tasub: type: string description: Territorial Authority Subdivision name (2018 census only) example: Akaroa Subdivision tasub_id: type: string description: Territorial Authority Subdivision ID (2018 census only) example: "06019" landwater: type: string description: Land/Water description (2018 census only) example: Inlet landwater_id: type: string description: Land/Water ID (2018 census only) example: 22 address_line_1: type: string description: First line of the non-suburb/city/postcode portion of the address example: Unit 2 address_line_2: type: string description: Second line of the non-suburb/city/postcode portion of the address. example: 1703A State Highway 1 pxid: type: string description: Unique address identifier. example: 3-.1.1d.2.42.1T.2 success: type: boolean description: Indicates if the request was successful or not. example: true NZ.Address.Verification: type: object description: >- All the addresses verification metadata associated in the format requested in the API request. required: - pxid - a - aims_address_id - address properties: pxid: type: string description: Unique address identifier. example: 2-2eNwG1oBJExni2nUFJm1cW a: type: string description: >- Canonical address as supplied by Land Information New Zealand or NZ Post. example: 1 Ghuznee Street, Te Aro, Wellington 6011 aims_address_id: type: string description: The unique identifier from Land Information New Zealand (LINZ). example: 2122864 ta_id: type: string description: Territorial Authority ID (2018 census only) example: "047" ta: type: string description: >- The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. example: Wellington City tasub_id: type: string description: Territorial Authority Subdivision ID (2018 census only) example: "04799" tasub: type: string description: Territorial Authority Subdivision name (2018 census only) example: Area Outside Subdivision number: type: string description: >- The street number of the address. Also populated with the box number for PO Box type addresses. example: 1 floor: type: string description: The level number and level type in a multi-story building. example: Level 19 box_type: type: string description: >- The type portion of a PO Box address, including `PO Box`, `Locked Bag`, `GPO Box`, `CMB`, `RMS`, `Care PO`, `MS` and `RSD` example: PO Box building_name: type: string description: Holds the building or property name. example: Miban Building post_street: type: string description: Holds the street name and type from NZ Post, it will be omitted if the address is not delivered to by NZ Post. example: Purakaunui Road post_street_name: type: string description: Holds the street name from NZ Post, it will be omitted if the address is not delivered to by NZ Post. example: Purakaunui post_suburb: type: string nullable: true description: Postal suburb (if available). postal: type: string nullable: true description: Postal address (if NZ Post delivers here). street_suffix: type: string description: The suffix of the street. Typically contains a compass direction. example: North sufi: type: integer description: Same as `aims_address_id`, returned as integer. example: 1518959 unit_identifier: type: string description: >- Identifies a specific sub-dwelling. Can be an alpha, number or a combination. example: 2 unit_type: type: string description: Describes the category of a sub-dwelling. example: Flat x: type: string description: Longitude coordinate (in WGS84 format). example: 174.777711971851 "y": type: string description: Latitude coordinate (in WGS84 format). example: -41.2940464548652 postcode: type: string description: Holds the four digit postcode. example: 6011 alpha: type: string nullable: true description: Alpha suffix from address (e.g. "B" in "1B"). street: type: string description: >- Holds the full name of the street. Note The street attribute also includes the Street Type. example: Ghuznee Street street_name: type: string description: Holds the name of the street. example: Ghuznee street_type: type: string description: The type of street. example: street city: type: string description: >- The city, town or locality name as assigned by Land Information New Zealand. example: Wellington suburb: type: string description: >- The suburb or locality of the address as assigned by Land Information New Zealand. example: Te Aro dpid: type: string nullable: true description: Unique identifier from NZ Post. example: 2668726 region_id: type: string description: Region ID (2018 census only) example: "09" region: type: string description: >- The Regional Authority in which this address exists. Note Regional Authorities are the top tier of local government in New Zealand. example: Wellington Region postal_line_1: type: string description: Postal address line 1 example: 1 Ghuznee Street postal_line_2: type: string description: Postal address line 2 example: Te Aro postal_line_3: type: string description: Postal address line 3 example: Wellington 6011 postal_line_4: type: string nullable: true description: NZ Post Line 4 postal_line_5: type: string nullable: true description: NZ Post Line 5 rd_number: type: string nullable: true description: NZ Post rural delivery number. rural: type: boolean description: > An indicator to help determine if this address is located in a rural setting. Note Different courier companies have different rural/urban boundaries so this determination should be confirmed by your delivery agent. example: false address_line_1: type: string description: First line of the non-suburb/city/postcode portion of the address example: 1 Ghuznee Street primary_parcel_id: type: string description: >- The unique identifier of the portion of land associated with the selected address. example: 4025566 meshblock: type: string description: > The meshblock identifier for the requested census dataset (see census parameter). If not specified, the meshblock returned is from the 2023 census. example: 2133700 sa1_id: type: string description: Statistical area 1 (2018 census only) example: 7021601 sa2_id: type: string description: Statistical area 2 ID (2018 census only) example: 251700 sa2: type: string description: Statistical area 2 name (2018 census only) example: Vivian West cb_id: type: string description: Community Board ID (2018 census only) example: "04799" cb: type: string description: Community Board name (2018 census only) example: Area Outside Community ward_id: type: string description: Ward ID (2018 census only) example: "04703" ward: type: string description: Ward name (2018 census only) example: Lambton Ward con_id: type: string description: Constituency ID (2018 census only) example: "0905" con: type: string description: Constituency name (2018 census only) example: Wellington Constituency maoricon_id: type: string description: Maori Constituency ID (2018 census only) example: "0999" maoricon: type: string description: Maori Constituency name (2018 census only) example: Area Outside Maori Constituency iur_id: type: string description: Urban rural indicator ID (2018 census only) example: 11 iur: type: string description: Urban rural indicator name (2018 census only) example: major urban area ur_id: type: string description: Urban rural ID (2018 census only) example: 1402 ur: type: string description: Urban rural name (2018 census only) example: Wellington landwater_id: type: string description: Land/Water ID (2018 census only) example: 12 landwater: type: string description: Land/Water description (2018 census only) example: Mainland supplementary: type: string description: 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. example: Jane Smith success: type: boolean description: Indicates if the request was successful or not. example: true matched: type: boolean description: Indicates if the address has been matched or not. example: true NZ.Address.Error: type: object description: An informative message when an error occurs handling an API request required: - completions - error_code - message properties: completions: type: array description: An empty array will be returned due to the error items: type: object error_code: type: string description: A unique numerical value identifying the error that occured example: 1004 message: type: string description: An informative message describing the error that occured example: Secret not provided success: type: boolean description: Indicates if the request was successful or not example: false Email.Address.Verification: type: object description: A successful email verification response. required: - email_account - email_domain - email_provider_domain - verified_email - is_verified - is_disposable - is_role - is_public - is_catch_all - not_verified_reason - not_verified_code - success properties: email_account: type: string description: The first part of an email address, before the `@` example: john.doe email_domain: type: string description: The second part of the email address, after the `@` example: addressfinder.com email_provider_domain: type: string description: >- The underlying provider of the email service. Only populated if the features=provider parameter is provided. example: google.com verified_email: type: string description: The full verified email address example: jane.smith@addressfinder.com is_verified: type: boolean description: >- We did not find any reason to believe an email sent to the address provided would fail to reach the associated mailbox example: true is_disposable: type: boolean description: Identified as a disposable email address example: false is_role: type: boolean description: >- The email account is for a group email. For example info@addressfinder.com example: false is_public: type: boolean description: >- Identified as a public email provider. For example john.doe@gmail.com example: false is_catch_all: type: boolean description: The email domain has a catch all policy example: false not_verified_reason: type: string description: >- If verified is false, this will contain a short description of the failure reason example: null not_verified_code: type: string description: A code indicating why the email did not verify example: null success: type: boolean description: Indicates if the request was successful or not example: true Email.Address.Error: type: object description: An informative message when an error occurs handling an API request required: - completions - message - error_code - success properties: completions: type: array description: An empty array will be returned due to the error items: type: object error_code: type: string description: A unique numerical value identifying the error that occured example: 1004 message: type: string description: An informative message describing the error that occured example: Secret not provided success: type: boolean description: Indicates if the request was successful or not example: false Phone.Verification: type: object description: A successful phone verification response required: - is_verified - line_type - line_status - line_status_reason - country_code - calling_code - raw_national - formatted_national - raw_international - formatted_international - not_verified_code - not_verified_reason - success properties: is_verified: type: boolean description: Indicates if the phone number is verified. example: true line_type: type: string description: The type of phone line the number is connected to. example: mobile line_status: type: string description: The connection status of the supplied number. example: connected line_status_reason: type: string description: Insights of the line_status result. example: false country_code: type: string description: The two character ISO code of the country of the phone number. example: AU calling_code: type: string description: The country calling code of the phone number. example: 61 raw_national: type: string description: The national phone number without any whitespace or punctuation. example: "0285038000" formatted_national: type: string description: >- The formatted national phone number including country-specific whitespace and punctuation. example: (02) 8503 8000 raw_international: type: string description: The international phone number in E.164 format. example: 61285038000 formatted_international: type: string description: >- The formatted international phone number including country-specific whitespace. example: +61 2 8503 8000 not_verified_code: type: string description: A code indicating why the number did not verify. example: LINE_DISCONNECTED not_verified_reason: type: string description: >- If the number did not verify, this will contain a short description of the failure reason. example: Phone number is not connected success: type: boolean description: Indicates if the request was successful or not example: true Phone.Verification.Error: type: object description: An informative message when an error occurs handling an API request required: - completions - message - error_code - success properties: completions: type: array description: An empty array will be returned due to the error items: type: object error_code: type: string description: A unique numerical value identifying the error that occured example: 1004 message: type: string description: An informative message describing the error that occured example: Secret not provided success: type: boolean description: Indicates if the request was successful or not example: false