# Predictive API Quickstart

Use this guide to request address suggestions, retrieve details for a selected address, and try locality and postcode suggestions.

## Before you begin

You need a [Geoscape Hub](https://hub.geoscape.com.au/) application with Predictive API product access and its Consumer Key. Follow [Authentication](/guides/authentication) to set up your application.

```shell
export GEOSCAPE_API_KEY="YOUR_CONSUMER_KEY"
```

The header name is `Authorization`. Its value is the Consumer Key directly, without a `Bearer` prefix. The Consumer Secret is not used in these requests.

## 1. Suggest addresses

Send partial input once it has at least three characters. These examples use `curl` and `jq`:

```shell
SUGGESTIONS=$(curl --fail-with-body --get \
  "https://api.psma.com.au/v1/predictive/address" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "query=113 Canberra" \
  --data-urlencode "maxNumberOfResults=5")

printf '%s\n' "$SUGGESTIONS" | jq '.suggest'
```

Each `suggest` entry contains:

- `address`: the label to display
- `id`: the address ID to use after selection
- `rank`: its zero-based position in the suggestion list

An empty `suggest` array means there are no suggestions. Rank is an ordering value, not a confidence score. Ask the user to select the intended address rather than automatically accepting the first result.

## 2. Retrieve the selected address

In your application, use the selected suggestion's `id`. This command demonstrates a lookup with the first suggestion:

```shell
ADDRESS_ID=$(printf '%s\n' "$SUGGESTIONS" | jq -r '.suggest[0].id // empty')

if [ -n "$ADDRESS_ID" ]; then
  curl --fail-with-body --get \
    "https://api.psma.com.au/v1/predictive/address/$ADDRESS_ID" \
    -H "Authorization: $GEOSCAPE_API_KEY" \
    -H "Accept: application/json"
else
  printf '%s\n' "No suggestions returned. Review the input before requesting details."
fi
```

The response's `address` object contains a GeoJSON point and structured `properties`:

- Property names use snake_case, for example `formatted_address` and `street_name`
- Optional address components are returned as `null`
- Point coordinates use longitude,latitude order in GDA94 by default. Use `Accept-Crs` to request another supported response CRS
- `dataset` identifies the contributing datasets. `contributor` is currently an empty array

Retain the returned `attribution`. See [CRS & GDA2020](/guides/gda-2020) and [Attribution](/guides/attribution).

## 3. Suggest localities instead

Use the locality endpoint for a locality and postcode picker:

```shell
curl --fail-with-body --get \
  "https://api.psma.com.au/v1/predictive/locality" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "query=Griffith" \
  --data-urlencode "stateTerritory=ACT" \
  --data-urlencode "postcode=2603,2604"
```

Display `suggest[].displayName`. The response also supplies `localityName`, `stateTerritory`, `postcode`, `id`, and `rank`. Locality IDs cannot be used with the address-details endpoint.

## Usage and errors

Each suggestion request uses 0.1 credits. Retrieving address details uses 1 credit.

- For `400`, correct the query, filters, or address ID
- For `401` or `403`, resolve credentials or product access
- For address-details `404`, check that the selected address ID is still valid
- Debounce typed input and ignore stale responses to avoid displaying suggestions for an earlier query

See [Error Handling](/guides/errors) and [Rate Limiting](/guides/rate-limiting) for retry and rate guidance.

## Next steps

- [Configure autocomplete](/guides/predictive/autocomplete)
- [Configure an ArcGIS locator](/guides/predictive/esri-compatible-locator)