# Address Validate

`POST /address_validate`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/address_validate`
- Sandbox: `POST 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

The address to validate

| Field | Type | 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` |

**Sample request**

```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"
}
```

## Responses

### 200 Successful response

Content type: `application/json`

| Field | Type | 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` |

**Sample response**

```json
{
    "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"
        }
    ]
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))