Documentation

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 application with Predictive API product access and its Consumer Key. Follow Authentication to set up your application.

Code
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:

Code
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:

Code
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 and Attribution.

3. Suggest localities instead

Use the locality endpoint for a locality and postcode picker:

Code
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 and Rate Limiting for retry and rate guidance.

Next steps

Last modified on October 29, 2026