# 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](https://data.gov.au/data/dataset/geocoded-national-address-file-g-naf).

## Before you begin

You need:

- A [Geoscape Hub](https://hub.geoscape.com.au) 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](/guides/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:

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

```shell
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:

```json
{
  "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](/guides/gda-2020).
- Preserve the top-level `attribution` text. See [Attribution](/guides/attribution).

Use [Assessing Address Matches](/guides/addresses/assessing-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:

```shell
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](/guides/addresses/additional-properties).

## 5. Try another input

### Use structured address components

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

```shell
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](/apis/addresses#when-to-use-this-api) 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.

<span id="transaction-usage-and-request-rates"></span>

## 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](/guides/addresses/additional-properties#understand-credit-costs) for costs and [Rate Limiting](/guides/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](/guides/errors) for body handling and retry guidance, including `429` and transient `500` failures.

## Next steps

- [Assess address matches](/guides/addresses/assessing-matches)
- [Find addresses from coordinates](/guides/addresses/reverse-geocoding)
- [Retrieve additional properties](/guides/addresses/additional-properties)
- [Match a postal address with MailPoint](/guides/addresses/mailpoint)