Address Validate

POST /api/v2/address_validate operationId: address_validate

Live: https://gdapi.globaldata.net.au/api/v2/address_validate · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/address_validate

The Address Validate method tests the supplied address and returns the matched address and a score from 0 to 10 indicating the quality of the match.

Corrections to the address

The address validator will attempt to match the address to the GNAF address database and make corrections to the supplied address if necessary in order to find the closest match.

Permitted changes include:

Spelling corrections to the street name. For example, "10 Smyth Street" to "10 Smith Street" (permitted if the street number and street name are valid in the given suburb / postcode)
Changes to the street type. For example, "10 Paper Rd" to "10 Paper St" (permitted if the street number and street name are valid in the given suburb / postcode)
Changes to the unit type. For example, "Flat" to "Unit"
Changes to the postcode. For example, "3125" to "3124" (permitted if the street number and street name are valid in an adjacent postcode)
Spelling corrections to the suburb name. For example, "Smithtown" to "Smithton" (permitted if the street number and street name are valid in the given suburb)
Changes to the suburb if the street number and street name are valid in an adjacent suburb.
Changes to the street number if the street number is a range and one of the numbers in the range is matched. For example, "123 Smith St" to "123-125 Smith St"

When changes are made to the supplied address, the address_changes array will be returned with the details of the changes made and the matched_address will be returned with the corrections applied.

Minimum Validation Requirements

The following combinations of parameters are required on order to validate an address:

street_address plus at least one of suburb or postcode
street_address plus suburb_state_postcode
full_address

Request body

Content type application/json. The address to validate

Field	Description
`street_address`	string [4..100 characters] or null First line of the street or postal address Requires at least one of suburb or postcode to be provided Example: `Unit 12B, 123-125 Smith St`
`suburb`	string [2..60 characters] or null Suburb name Requires street_address to be provided Example: `Smithtown`
`state`	string or null State Requires street_address to be provided Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `ACT`
`postcode`	string [3..4 characters] or null Postcode Requires street_address to be provided Example: `2000`
`suburb_state_postcode`	string [4..100 characters] or null Combined suburb, state and postcode. Requires street_address to be provided Supports various address formats: Smithtown, ACT 2000 Smithtown 2000 ACT Example: `Smithtown ACT 2000`
`full_address`	string [4..255 characters] or null Full address Supports various address formats: 123 Smith St, Smithtown, ACT 2000 Unit 12, 123 Smith Street, Smithtown 2000 ACT 1/12-34 Smith St, Upper Smithtown, 2000 Example: `Unit 12B, 123-125, Smithtown, ACT 2000`

Responses

200

Successful response

application/json

Field	Description
`message`	string A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok`
`api_reference`	string (uuid) A unique identifier for this request. This can be used to track the request in the logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95`
`valid`	boolean Indicates if the address is valid Example: `true`
`score`	integer or null A score from 0 to 10 indicating the quality of the match with 0 being the worst match and 10 being the best match or null if the address is not valid. The score is calculated as: 10 - number of address changes (with a minimum of 0) Example: `9`
`matched_address`	object The matched address or an empty object if the address is not valid
`matched_address.address_id`	string The GNAF address id of the address Example: `GAACT714845933`
`matched_address.full_address`	string The full address Example: `Unit 12B, 123-125 Smith St, Smithtown, ACT 2000`
`matched_address.address_line_1`	string The first line of the address Example: `Unit 12B, 123-125 Smith St`
`matched_address.address_line_2`	string The second line of the address Example: `Smithtown ACT 2000`
`matched_address.suburb`	string The suburb of the address Example: `Smithtown`
`matched_address.state`	string The state of the address Example: `ACT`
`matched_address.postcode`	string The postcode of the address Example: `2000`
`matched_address.unit_type`	string or null The type of unit of the address eg: 'Flat' in the address: "Flat AA12B, 100 Some St" Example: `U`
`matched_address.unit_number_prefix`	string or null The prefix of the unit number eg: 'AA' in the address: "Flat AA12B, 100 Some St"
`matched_address.unit_number`	string or null The unit number of the address eg: '12' in the address: "Flat AA12B, 100 Some St" Example: `12`
`matched_address.unit_number_suffix`	string or null The suffix of the unit number eg: 'B' in the address: "Flat AA12B, 100 Some St" Example: `B`
`matched_address.level_type`	string or null The type of level of the address eg: 'L' in the address: "L A12F, 100 Some St"
`matched_address.level_number_prefix`	string or null The prefix of the level number eg: 'A' in the address: "L A12F, 100 Some St"
`matched_address.level_number`	string or null The level number of the address eg: '12' in the address: "L A12F, 100 Some St"
`matched_address.level_number_suffix`	string or null The suffix of the level number eg: 'F' in the address: "L A12F, 100 Some St"
`matched_address.street_number_1_prefix`	string or null The prefix of the street number eg: 'B' in the address: "B100C - D110E Some St"
`matched_address.street_number_1`	string or null The numeric part of the first street number eg: '100' in the address: "B100C - D110E Some St" Example: `123`
`matched_address.street_number_1_suffix`	string or null The suffix of the first street number eg: 'C' in the address: "B100C - D110E Some St"
`matched_address.street_number_2_prefix`	string or null The prefix of the second street number eg: 'D' in the address: "B100C - D110E Some St"
`matched_address.street_number_2`	string or null The numeric part of the second street number eg: '110' in the address: "B100C - D110E Some St" Example: `125`
`matched_address.street_number_2_suffix`	string or null The suffix of the second street number eg: 'E' in the address: "B100C - D110E Some St"
`matched_address.lot_number_prefix`	string or null The prefix of the lot number eg: 'F' in the address: "Lot F200G Some St"
`matched_address.lot_number`	string or null The numeric part of the lot number eg: '200' in the address: "Lot F200G Some St"
`matched_address.lot_number_suffix`	string or null The suffix of the lot number eg: 'G' in the address: "Lot F200G Some St"
`matched_address.postal_delivery_type`	string or null The type of postal delivery eg: 'PO Box' in the address: "PO Box H1234J"
`matched_address.postal_delivery_number_prefix`	string or null The prefix of the postal delivery number eg: 'H' in the address: "PO Box H1234J"
`matched_address.postal_delivery_number`	string or null The numeric part of the postal delivery number eg: '1234' in the address: "PO Box H1234J"
`matched_address.postal_delivery_number_suffix`	string or null The suffix of the postal delivery number eg: 'J' in the address: "PO Box H1234J"
`matched_address.street_name`	string or null The name of the street eg: 'Smith St' in the address: "123 Smith St North" Example: `Smith`
`matched_address.street_type`	string or null The type of street eg: 'St' in the address: "123 Smith St North" Example: `ST`
`matched_address.street_suffix`	string or null The suffix of the street eg: 'North' in the address: "123 Smith St North"
`address_changes`	array of objects Array of changes made to the provided address in order to match with the GNAF address
`address_changes[].field`	string The address field that was changed Example: `street_type`
`address_changes[].change`	string The change made to the address field Example: `Changed from ST to PL`

Standard error responses: 400 401 402 403 429 5XX See common error responses

Previous Address Autocomplete Next Address Validate Bulk

Request body application/json

{
    "street_address": "Unit 12B, 123-125 Smith St",
    "suburb": "Smithtown",
    "state": "ACT",
    "postcode": "2000",
    "suburb_state_postcode": "Smithtown ACT 2000",
    "full_address": "Unit 12B, 123-125, Smithtown, ACT 2000"
}

Response

200 Successful response

{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "valid": true,
    "score": 9,
    "matched_address": {
        "address_id": "GAACT714845933",
        "full_address": "Unit 12B, 123-125 Smith St, Smithtown, ACT 2000",
        "address_line_1": "Unit 12B, 123-125 Smith St",
        "address_line_2": "Smithtown ACT 2000",
        "suburb": "Smithtown",
        "state": "ACT",
        "postcode": "2000",
        "unit_type": "U",
        "unit_number_prefix": null,
        "unit_number": "12",
        "unit_number_suffix": "B",
        "level_type": null,
        "level_number_prefix": null,
        "level_number": null,
        "level_number_suffix": null,
        "street_number_1_prefix": null,
        "street_number_1": "123",
        "street_number_1_suffix": null,
        "street_number_2_prefix": null,
        "street_number_2": "125",
        "street_number_2_suffix": null,
        "lot_number_prefix": null,
        "lot_number": null,
        "lot_number_suffix": null,
        "postal_delivery_type": null,
        "postal_delivery_number_prefix": null,
        "postal_delivery_number": null,
        "postal_delivery_number_suffix": null,
        "street_name": "Smith",
        "street_type": "ST",
        "street_suffix": null
    },
    "address_changes": [
        {
            "field": "street_type",
            "change": "Changed from ST to PL"
        }
    ]
}

400 Bad or missing input parameter shared error response

{
    "message": "string"
}

401 Unauthorized - The request is not authorized. shared error response

{
    "message": "API Key Inactive"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access"
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error"
}