Predictive v1 · Predictions

Download schema

Before calling these endpoints, use a Geoscape Hub application with access to this API product. Authenticate with your Consumer Key in the Authorization header. See Authentication, Error Handling, Rate Limiting, and Attribution for shared integration guidance.

Suggest addresses

GET

https://api.psma.com.au

/v1/predictive/address

Authorization (header)

Authentication: Use your Consumer Key in the Authorization header.

Return ranked address suggestions from partial input. Use the selected suggestion’s id to retrieve address details. This is autocomplete. Use the Addresses API to match a complete address.

See Autocomplete for filters and result handling.

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

Suggest addresses › query Parameters

query

string · minLength: 3 · maxLength: 50 · required

Partial address, from 3 to 50 characters after trimming leading and trailing spaces.

maxNumberOfResults

integer · min: 1 · max: 20

Maximum suggestions to return. Defaults to 5 and accepts 1 to 20.

Default: 5

stateTerritory

string[] · style: form

State or territory abbreviations as one comma-separated value, for example stateTerritory=NSW,QLD. Omit for no restriction. ALL also applies no restriction.

Enum values:

ACT

NSW

QLD

VIC

TAS

dataset

string[] · style: form

Datasets as one comma-separated value, for example dataset=gnaf,gnaflive. Omit or use all to search all three datasets. See Autocomplete.

Enum values:

gnaf

mailAddress

gnaflive

all

addressType

string · enum

Filter for physical or mailing addresses. Omit or use all for both types. An address can be both physical and mailing.

Enum values:

physical

mailing

all

excludeAliases

boolean · enum

Exclude alias addresses when true. Defaults to false.

Enum values:

Default: false

excludePrimaryWithSec

boolean

Exclude primary addresses that have related secondary addresses when true. Defaults to false.

Default: false

Suggest addresses › Responses

Success

Ranked suggestions and response information.

PredictiveV1_Predictive_Suggestion.v1

object[] · required

Suggestions in ranked order. Empty when nothing matches.

messages

string[]

GET/v1/predictive/address

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"

Example Responses

{
  "suggest": [
    {
      "address": "219 NORMAN ST, BALLARAT NORTH VIC 3350",
      "id": "GAVIC423834288",
      "rank": 0
    },
    {
      "address": "219 NORRING RD, WEDGECARRUP WA 6315",
      "id": "GAWA_162256790",
      "rank": 1
    },
    {
      "address": "219 NORRIS RD, BRACKEN RIDGE QLD 4017",
      "id": "GAQLD156304488",
      "rank": 2
    },
    {
      "address": "219 NORTHAM AV, BANKSTOWN NSW 2200",
      "id": "GANSW704013582",
      "rank": 3
    },
    {
      "address": "219 NORTH BEACH DR, TUART HILL WA 6060",
      "id": "GAWA_162412697",
      "rank": 4
    },
    {
      "address": "219 NORTHBOURNE AV, TURNER ACT 2612",
      "id": "GAACT714884655",
      "rank": 5
    },
    {
      "address": "219 NORTHBOURNE RD, CAMPBELLFIELD VIC 3061",
      "id": "GAVIC422416073",
      "rank": 6
    },
    {
      "address": "219 NORTHCLIFFE DR, BERKELEY NSW 2506",
      "id": "GANSW704087051",
      "rank": 7
    },
    {
      "address": "219 NORTHCOTE AV, SWANSEA NSW 2281",
      "id": "GANSW710262832",
      "rank": 8
    },
    {
      "address": "219 NORTH CURRAMORE RD, CURRAMORE NSW 2533",
      "id": "GANSW704548627",
      "rank": 9
    },
    {
      "address": "219 NORTH DALLARNIL RD, DALLARNIL QLD 4621",
      "id": "GAQLD160228211",
      "rank": 10
    },
    {
      "address": "219 NORTH EAST RD, HAMPSTEAD GARDENS SA 5086",
      "id": "GASA_415842421",
      "rank": 11
    },
    {
      "address": "219 NORTH HARLEY ST, STRATHDALE VIC 3550",
      "id": "GAVIC421604220",
      "rank": 12
    },
    {
      "address": "219 NORTH JINDONG RD, CARBUNUP RIVER WA 6280",
      "id": "GAWA_162267446",
      "rank": 13
    },
    {
      "address": "219 NORTHLAKES DR, CAMERON PARK NSW 2285",
      "id": "GANSW718381720",
      "rank": 14
    },
    {
      "address": "219 NORTH LIVERPOOL RD, BONNYRIGG NSW 2177",
      "id": "GANSW704202249",
      "rank": 15
    },
    {
      "address": "219 NORTH RD, CAULFIELD SOUTH VIC 3162",
      "id": "GAVIC419630800",
      "rank": 16
    },
    {
      "address": "219 NORTH RD, CENTENNIAL PARK WA 6330",
      "id": "GAWA_147069898",
      "rank": 17
    },
    {
      "address": "219 NORTH RD, EASTWOOD NSW 2122",
      "id": "GANSW704670138",
      "rank": 18
    },
    {
      "address": "219 NORTH RIVER RD, NORTH PLANTATIONS WA 6701",
      "id": "GAWA_147041593",
      "rank": 19
    }
  ]
}

json

application/json

Suggest localities

GET

https://api.psma.com.au

/v1/predictive/locality

Authorization (header)

Authentication: Use your Consumer Key in the Authorization header.

Return locality and postcode suggestions from partial locality input. Locality IDs cannot be used to retrieve address details.

See Autocomplete for filters and result handling.

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 "maxNumberOfResults=5"

Suggest localities › query Parameters

query

string · minLength: 1 · maxLength: 50 · required

Partial locality name, from 1 to 50 characters.

maxNumberOfResults

integer · min: 1 · max: 20

Maximum suggestions to return. Defaults to 5 and accepts 1 to 20.

Default: 5

stateTerritory

string[] · style: form

State or territory abbreviations as one comma-separated value, for example stateTerritory=NSW,QLD. Omit for no restriction.

Enum values:

ACT

NSW

QLD

VIC

TAS

postcode

string[] · style: form

Postcodes as a single comma-separated value, for example postcode=2603,2604. Preserve leading zeros.

Suggest localities › Responses

Success

Ranked suggestions and response information.

PredictiveV1_Predictive_Locality.v1

object[] · required

Suggestions in ranked order. Empty when nothing matches.

query

string · required

The query the user provided to produce the results

requestTimeStamp

string · required

requestDateTime

string · required

attribution

string · required

messages

string[]

GET/v1/predictive/locality

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 "maxNumberOfResults=5"

Example Responses

{
  "suggest": [
    {
      "displayName": "WEABONGA NSW 2340",
      "id": "loc459f16460191",
      "localityName": "WEABONGA",
      "stateTerritory": "NSW",
      "postcode": "2340",
      "rank": 0
    }
  ],
  "query": "WE",
  "requestTimeStamp": "1724678340.323472",
  "requestDateTime": "2024-08-26T23:19:00.323487",
  "attribution": "NOTICE All rights reserved. Use of this data is subject to the Geoscape Developer Terms and Conditions (https://geoscape.com.au/legal/geoscape-developer-terms/)"
}

json

application/json

Get address details

GET

https://api.psma.com.au

/v1/predictive/address/{id}

Authorization (header)

Authentication: Use your Consumer Key in the Authorization header.

Retrieve the address selected from suggest[].id. Returns an address object containing a GeoJSON Feature with snake_case property names. Optional address components are returned as null. Coordinates use GDA94 unless Accept-Crs requests another supported CRS.

Code
curl --fail-with-body --get \
  "https://api.psma.com.au/v1/predictive/address/GAACT717940975" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json"

Get address details › path Parameters

id

string · minLength: 3 · maxLength: 28 · pattern: ^[A-Za-z0-9_-]+$ · required

ID from an address suggestion. Keep its casing. Locality suggestion IDs are not address IDs.

Get address details › Headers

Accept-Crs

string

Response CRS as an angle-bracketed URI. Defaults to GDA94 (EPSG:4283). See CRS & GDA2020.

Get address details › Responses

Success

Structured address details for a selected address suggestion.

PredictiveV1_Predictive_AddressValidation.v1

object · required

GET/v1/predictive/address/{id}

curl --fail-with-body --get \
  "https://api.psma.com.au/v1/predictive/address/GAACT717940975" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json"

Example Responses

{
  "address": {
    "contributor": [],
    "dataset": "gnaf,mailAddress,gnaflive",
    "geometry": {
      "coordinates": [
        149.14668176,
        -35.32202098
      ],
      "type": "Point"
    },
    "id": "GAACT717940975",
    "properties": {
      "address_identifier": "GAACT717940975",
      "alias_principal": "PRINCIPAL",
      "cadastral_identifier": "CANB/GRIF/25/14/",
      "formatted_address": "113 CANBERRA AV, GRIFFITH ACT 2603",
      "geo_feature": "FRONTAGE CENTRE SETBACK",
      "gnaf_locality_pid": "ACT220",
      "gnaf_street_locality_pid": "ACT1507",
      "locality_aliases": "CANBERRA CENTRAL,KINGSTON,MANUKA",
      "locality_name": "GRIFFITH",
      "locality_neighbours": "BARTON,FORREST,FYSHWICK,KINGSTON,NARRABUNDAH,RED HILL",
      "postcode": "2603",
      "primary_secondary": "PRIMARY",
      "state_territory": "ACT",
      "street_name": "CANBERRA",
      "street_number_1": "113",
      "street_type": "AVENUE",
      "street_type_description": "AV",
      "complex_level_number": null,
      "complex_level_type": null,
      "complex_level_type_description": null,
      "complex_unit_identifier": null,
      "complex_unit_type": null,
      "complex_unit_type_description": null,
      "location_descriptor": null,
      "lot_identifier": null,
      "postal_delivery_number": null,
      "postal_delivery_type": null,
      "site_name": null,
      "street_aliases": null,
      "street_number_2": null,
      "street_suffix": null
    },
    "type": "Feature"
  }
}

json

application/json

Maps v1 · Tiles Verify v1 · Email

Suggest addresses

GET

https://api.psma.com.au

/v1/predictive/address

Authorization (header)

Authentication: Use your Consumer Key in the Authorization header.

Return ranked address suggestions from partial input. Use the selected suggestion’s id to retrieve address details. This is autocomplete. Use the Addresses API to match a complete address.

See Autocomplete for filters and result handling.

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

Suggest addresses › query Parameters

query

string · minLength: 3 · maxLength: 50 · required

Partial address, from 3 to 50 characters after trimming leading and trailing spaces.

maxNumberOfResults

integer · min: 1 · max: 20

Maximum suggestions to return. Defaults to 5 and accepts 1 to 20.

Default: 5

stateTerritory

string[] · style: form

State or territory abbreviations as one comma-separated value, for example stateTerritory=NSW,QLD. Omit for no restriction. ALL also applies no restriction.

Enum values:

ACT

NSW

QLD

VIC

TAS

dataset

string[] · style: form

Datasets as one comma-separated value, for example dataset=gnaf,gnaflive. Omit or use all to search all three datasets. See Autocomplete.

Enum values:

gnaf

mailAddress

gnaflive

all

addressType

string · enum

Filter for physical or mailing addresses. Omit or use all for both types. An address can be both physical and mailing.

Enum values:

physical

mailing

all

excludeAliases

boolean · enum

Exclude alias addresses when true. Defaults to false.

Enum values:

Default: false

excludePrimaryWithSec

boolean

Exclude primary addresses that have related secondary addresses when true. Defaults to false.

Default: false

Suggest addresses › Responses

Success

Ranked suggestions and response information.

PredictiveV1_Predictive_Suggestion.v1

object[] · required

Suggestions in ranked order. Empty when nothing matches.

messages

string[]

Suggest localities

GET

https://api.psma.com.au

/v1/predictive/locality

Authorization (header)

Authentication: Use your Consumer Key in the Authorization header.

Return locality and postcode suggestions from partial locality input. Locality IDs cannot be used to retrieve address details.

See Autocomplete for filters and result handling.

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 "maxNumberOfResults=5"

Suggest localities › query Parameters

query

string · minLength: 1 · maxLength: 50 · required

Partial locality name, from 1 to 50 characters.

maxNumberOfResults

integer · min: 1 · max: 20

Maximum suggestions to return. Defaults to 5 and accepts 1 to 20.

Default: 5

stateTerritory

string[] · style: form

State or territory abbreviations as one comma-separated value, for example stateTerritory=NSW,QLD. Omit for no restriction.

Enum values:

ACT

NSW

QLD

VIC

TAS

postcode

string[] · style: form

Postcodes as a single comma-separated value, for example postcode=2603,2604. Preserve leading zeros.

Suggest localities › Responses

Success

Ranked suggestions and response information.

PredictiveV1_Predictive_Locality.v1

object[] · required

Suggestions in ranked order. Empty when nothing matches.

query

string · required

The query the user provided to produce the results

requestTimeStamp

string · required

requestDateTime

string · required

attribution

string · required

messages

string[]

Get address details

GET

https://api.psma.com.au

/v1/predictive/address/{id}

Authorization (header)

Authentication: Use your Consumer Key in the Authorization header.

Code
curl --fail-with-body --get \
  "https://api.psma.com.au/v1/predictive/address/GAACT717940975" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/json"

Get address details › path Parameters

id

string · minLength: 3 · maxLength: 28 · pattern: ^[A-Za-z0-9_-]+$ · required

ID from an address suggestion. Keep its casing. Locality suggestion IDs are not address IDs.

Get address details › Headers

Accept-Crs

string

Response CRS as an angle-bracketed URI. Defaults to GDA94 (EPSG:4283). See CRS & GDA2020.

Get address details › Responses

Success

Structured address details for a selected address suggestion.

PredictiveV1_Predictive_AddressValidation.v1

object · required