# Address Autocomplete

`GET /address_autocomplete`

- Live: `GET https://gdapi.globaldata.net.au/api/v2/address_autocomplete`
- Sandbox: `GET https://sandbox-gdapi.globaldata.net.au/api/v2/address_autocomplete`

Address Auto-Complete is a powerful API query that can save users time and reduce errors by predicting and
suggesting Australian addresses as they are being typed. This feature can be integrated into any web or mobile
application to streamline data entry and improve overall data accuracy.

The address autocomplete method is used for performing address autocomplete on user entry forms using AJAX or
similar. This method will return matching addresses when sent the starting characters of an address.

## Match Types

The following match types are supported:

- `address` - Match only full addresses. This search returns an address with a GNAF id
- `street` - Match only street names. This search returns a list of matching streets with suburb, postcode and state
- `suburb` - Match only suburb names. This search returns a list of matching suburbs with postcode and state
- `postcode` - Match only postcodes. This search returns a list of suburbs within the existing postcode, and the state and postcode

## Sandbox environment

When simulating queries in the sandbox environment, a restricted dataset is used and a number of responses are
possible. The response will be determined by the partial_address:

Type     | Partial Address                 | Response
:--------|:--------------------------------|:--------------------------------
address  | Any even street number          | A valid search will be performed
address  | Any odd street number           | No matches will be found
postcode | Any even postcode               | A valid search will be performed and returned
postcode | Any odd postcode                | No matches will be found
suburb   | Any suburb beginning with A - H | A valid search will be performed and returned
suburb   | Any suburb beginning with I - Z | No matches will be found
street   | Any street beginning with A - H | A valid search will be performed and returned
street   | Any street beginning with I - Z | No matches will be found

> In the production environment, the full Australian address database will be used to generate matches.

## Request body

The details of the record to enhance

| Field | Type | Description |
|-------|------|-------------|
| `partial_address` | string [4..100 characters] | The first 4 or more characters of the address/street/suburb/postcode to find Example: `123 Smith` |
| `type` | string or null | The type of address match to find * `address` - Match only full addresses. This search returns an address with a GNAF id * `street` - Match only street names. This search returns a list of matching streets with suburb, postcode and state * `suburb` - Match only suburb names. This search returns a list of matching suburbs with postcode and state * `postcode` - Match only postcodes. This search returns a list of suburbs within the existing postcode, and the state and postcode Enum: `address`, `street`, `suburb`, `postcode` Default: `address` Example: `address` |
| `max_results` | integer [1..100] or null | The maximum number of results to return Default: `20` Example: `20` |

**Sample request**

```json
{
    "partial_address": "123 Smith",
    "type": "address",
    "max_results": 20
}
```

## 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` |
| `matches` | array of objects | Array of matched addresses |
| `matches[].type` | string | The type of match returned Example: `address` |
| `matches[].address_id` | string | The GNAF address id of the address Example: `GAACT714845933` |
| `matches[].address_option` | string | Complete match as a single line ready to pass to a SELECT element Example: `6 PACKHAM PL CHARNWOOD ACT 2615` |
| `matches[].address_combined` | string | The combined street address as one string. eg  _2/10 Paper St_. This attribute is only returned for types address and street requests Example: `6 PACKHAM PL` |
| `matches[].suburb` | string | The matched suburb Example: `CHARNWOOD` |
| `matches[].postcode` | string | The matched postcode Example: `2615` |
| `matches[].state` | string | The matched state Example: `ACT` |
| `more_results` | boolean | Indicates if there are more than _max_results_ available. Example: `false` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "matches": [
        {
            "type": "address",
            "address_id": "GAACT714845933",
            "address_option": "6 PACKHAM PL CHARNWOOD ACT 2615",
            "address_combined": "6 PACKHAM PL",
            "suburb": "CHARNWOOD",
            "postcode": "2615",
            "state": "ACT"
        }
    ],
    "more_results": false
}
```

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