On this page

Copy page

Documentation

Addresses API Quickstart

Use this guide to geocode an address, assess the match, and retrieve details with Addresses v2. It also shows structured input and how to choose your next endpoint.

For background on G-NAF address data, see the Geocoded National Address File dataset listing.

Before you begin

You need:

• A Geoscape Hub application with Addresses API access on your subscription.
• The application's Consumer Key.
• A terminal with curl and jq installed. The examples use jq to read the returned address ID.

Follow Authentication if you need to create an application. MailPoint and premium additional properties require paid-plan access. The first request below uses base address attributes.

1. Set your Consumer Key

Store the Consumer Key outside source code. Replace this placeholder with your application's key:

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 for these requests. Addresses v2 requests use https://api.psma.com.au/v2/addresses.

2. Geocode an address

Send a single-line address and save the response for the next request:

Code
ADDRESS_RESULT=$(curl --fail-with-body --get \
  "https://api.psma.com.au/v2/addresses/geocoder" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/geo+json" \
  --data-urlencode "address=113 Canberra Ave Griffith ACT 2603" \
  --data-urlencode "matchType=address")

printf '%s\n' "$ADDRESS_RESULT" | jq .

matchType=address restricts results to primary or secondary addresses. Without it, the geocoder can fall back to a street or locality. maxResults defaults to 1. Use up to 20 to review multiple candidates.

A successful request returns 200 and a GeoJSON FeatureCollection. This excerpt from the endpoint's example shows a match. Live results can differ:

Code
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [149.14668176, -35.32202098]
      },
      "properties": {
        "addressId": "GAACT717940975",
        "formattedAddress": "113 CANBERRA AV, GRIFFITH ACT 2603",
        "geoFeature": "FRONTAGE CENTRE SETBACK"
      },
      "matchType": "Primary Address",
      "matchQuality": "Exact",
      "matchScore": 100
    }
  ],
  "messages": []
}

3. Assess the match

Check the result before storing or using the returned address:

Field	What to check
features	An empty array means no match was returned. A 200 status alone does not confirm an address.
features[].matchType	Whether the match is an address, street, or locality. A street or locality match does not confirm a specific premise.
features[].properties.formattedAddress	The returned address label. Ask the user to confirm material changes.
features[].matchQuality and matchScore	Match quality and candidate ranking. The score is not a percentage or a probability.
features[].matchCode	How individual input components matched, where supplied. Use it to investigate changes.
features[].properties.geoFeature	What the returned point represents, such as an address access point or a locality point.
messages and features[].messages	Request information and feature-specific warnings. These can accompany a successful result.

When using the returned data:

• Read point coordinates in [longitude, latitude] order.
• Use Accept-Crs to request a different response CRS. The default is GDA94 (EPSG:4283). See CRS & GDA2020.
• Preserve the top-level attribution text. See Attribution.

Use Assessing Address Matches for quality, score, and code definitions, and to review component changes and point detail before accepting a candidate.

4. Retrieve attributes for the matched address

Once you have reviewed the match, use its addressId to retrieve the address and related ASGS attributes. Check that an ID is present before making the call:

Code
ADDRESS_ID=$(printf '%s\n' "$ADDRESS_RESULT" | jq -r '.features[0].properties.addressId // empty')

if [ -n "$ADDRESS_ID" ]; then
  curl --fail-with-body --get \
    "https://api.psma.com.au/v2/addresses/address/$ADDRESS_ID" \
    -H "Authorization: $GEOSCAPE_API_KEY" \
    -H "Accept: application/geo+json" \
    --data-urlencode "additionalProperties=asgsMain,asgsRemoteness"
else
  printf '%s\n' "No address ID returned. Review the input before making a lookup."
fi

The lookup returns a single GeoJSON Feature, rather than a FeatureCollection. Related attributes appear inside properties. Unavailable attributes may be omitted and reported in messages.

You can also add additionalProperties to the original geocoding request to avoid a separate lookup. Send the names in one comma-separated query value. Some properties require paid-plan access and add credit costs. See Additional Properties.

5. Try another input

Use structured address components

When your application already has separate fields, send them directly:

Code
curl --fail-with-body --get \
  "https://api.psma.com.au/v2/addresses/geocoder" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/geo+json" \
  --data-urlencode "streetNumber1=113" \
  --data-urlencode "streetName=Canberra" \
  --data-urlencode "streetType=AV" \
  --data-urlencode "localityName=Griffith" \
  --data-urlencode "stateTerritory=ACT" \
  --data-urlencode "postcode=2603" \
  --data-urlencode "matchType=address"

For structured input:

• Supply at least one of address, streetName, or localityName.
• Use explicit components to override corresponding parsed values when sending both components and an address string.
• Review parsedQuery to see the components used by the geocoder. Parsing alone does not confirm an address exists.

Choose your next endpoint

Use the Addresses API task selector to choose an endpoint for coordinates, known IDs, parcel or property identifiers, or postal matching.

For parcel and property searches:

• Use limit and offset for pagination and follow links.next while it is present.
• Use cadastralIdentifier as the parcel identifier or contributorPropertyId as the contributor property identifier.
• URL-encode identifiers. Decode JSON escaping before using a Victorian parcel identifier containing backslashes.

Credit usage and request rates

Geocoding and address lookups use 1 base credit per processed request, including geocoding searches with no matches. Related attributes can add charges for each returned feature. See Additional Properties for costs and Rate Limiting for request-rate allowances.

If the request fails

• For 400, correct the invalid input before retrying.
• For 401 or 403, resolve credentials or subscription restrictions before retrying.
• For an ID lookup's 404, check the identifier. A geocoder no-match result is 200 with an empty features array.

Service errors contain a messages array. Gateway authentication failures can use a fault object. Follow Error Handling for body handling and retry guidance, including 429 and transient 500 failures.

Next steps

• Assess address matches
• Find addresses from coordinates
• Retrieve additional properties
• Match a postal address with MailPoint