# Assessing Address Matches

Use this guide to confirm a matched record’s type, interpret match quality, score, and code, and assess its coordinates.

A successful HTTP status means the search was processed. It does not establish a suitable match or postal deliverability.

## Confirm the record type

The geocoder tries addresses first, then streets, then localities. For a workflow that requires a specific premise, send `matchType=address` and handle an empty `features` array. A street or locality fallback provides a broader location.

The response's `matchType` identifies the record: `Primary Address`, `Secondary Address` (such as a unit), `Street`, or `Locality`. These labels differ from the query values. See the [Geocode parameter reference](/reference/addresses-v2-address-search#geocode-2/query-parameters) for filters and defaults.

An address record and an address-level geocode are separate requirements. A matched premise can have approximate coordinates. Check `properties.geoFeature` before using the point.

## Review the matching metadata

The geocoder returns three types of matching metadata. Read them together to understand a candidate:

| Field | Tells you |
| --- | --- |
| [`matchQuality`](#match-quality) | The overall quality label for the candidate |
| [`matchScore`](#match-score) | Its numeric match score from 0 to 100 |
| [`matchCode`](#match-code) | How individual address components matched |

Request multiple candidates with `maxResults` when you need to review alternatives. One result does not establish uniqueness. Exact matches can also produce multiple candidates.

## Match Quality

`features[].matchQuality` gives the candidate an overall quality label. Use it to decide how much review the result needs.

| `matchQuality` | How to use the result |
| --- | --- |
| `Exact` | An exact match after normalisation. Abbreviations or punctuation may have changed. |
| `Confident` | A strong candidate. Review material changes or assumptions. |
| `Good` | Review changes and missing components before accepting. |
| `Fair` | Review closely, especially the street and unit numbers. |
| `Poor` | Treat as speculative. Do not accept solely because it was returned. |

The response also permits `NoMatch`, `Bad`, and `NA`. These are not successful-match signals. The normal no-match result is an empty `features` array.

## Match Score

`features[].matchScore` is a number from 0 to 100 that ranks candidates for the same query. It is not a percentage or a probability, and fixed score bands do not determine the quality label. Consider the supplied components and the changes made to them.

Read quality and score together with the component feedback. A high score does not establish that a changed unit number or postcode is acceptable. The [matching examples](/guides/addresses/match-quality-examples) show quality labels and scores alongside the changes to review.

## Match Code

Each entry in `features[].matchCode` names an address component and describes how it matched. Use the code alongside the parsed input and returned value.

### Read match codes

| Code | Meaning | What to check |
| --- | --- | --- |
| `exact` | The component matched exactly after normalisation. | Abbreviations and punctuation may still differ. |
| `fuzzy` | The component matched with spelling differences. | Compare the supplied and returned spelling. |
| `phonetic` | The component matched by similar pronunciation. | Similar-sounding names can identify different places. |
| `alias` | The component matched an alternative name exactly. | Review the returned name and any locality or street aliases. |
| `alias_fuzzy` | An alternative name matched with spelling differences. | Review both the spelling change and alternative name. |
| `neighbour` | The locality matched a neighbouring locality. | Confirm that the returned locality is intended. |
| `neighbour_fuzzy` | A neighbouring locality matched with spelling differences. | Review both the locality change and spelling correction. |
| `partial` | Part of a multi-word name matched. | Check the complete returned street or locality name. |
| `numeric` | The numeric portion of a street number matched. | Compare the full number, including letters and range endpoints. |
| `in_range` | A street number matched within an address range, accounting for odd/even numbers where known. | A number within a range does not confirm the whole input range. |
| `close` | A nearby street number matched. | Check the changed number. This is numeric proximity, not a distance in metres. |
| `no` | A supplied component did not match. | Review the discrepancy before accepting the candidate. |
| `misc` | Supplementary component feedback, such as a matched site name or street suffix. | Compare the values directly. It does not express the overall match quality. |

When reading the object:

- Fields are optional. An omitted field does not mean `no` and does not confirm that the component matched.
- Codes describe individual components. An `exact` street name does not confirm a unit or street number.
- Different components can use different matching methods in the same candidate. Review material changes even when other fields are `exact`.

## Address token glossary

A token is an address component used in matching, such as a street name or unit number. The parsed fields show how the input was split into components. Their importance depends on the record type and matching method.

| Term | Meaning |
| --- | --- |
| Key tokens | Unit number, street numbers (including both endpoints of a range), street name, locality, state or territory, and postcode. |
| Supporting (lesser) tokens | Components that add detail, such as street type, unit type, level type, level number, and street suffix. Changes can still matter to your application. |
| Regional tokens | Locality name, state or territory, and postcode. Review these together to confirm the intended location. |
| Exact token | A supplied component matches the returned component after normalisation. |
| Partial token | A component matches through spelling, pronunciation, an alternative name, part of a name, or numeric or range matching. Review the complete returned value. |
| Omitted token | The input did not supply a component that appears in the matched record. For example, the response supplies a postcode. |
| Mismatched token | A supplied component differs from the matched record, such as an incorrect state or street number. |
| Unused token | A supplied component does not identify the returned record, such as a flat number when a primary address is returned. |
| Normalisation | Formatting changes that preserve the component's meaning, such as `Street` becoming `ST`, capitalisation, or punctuation changes. |

“Partial token” is a glossary term covering several matching methods. The specific `partial` match code means that part of a multi-word name matched. Use the actual code to distinguish the methods.

The relevant tokens depend on the returned record type:

- For an address, check the unit and street numbers as well as the street and regional tokens.
- For a street, unit and street numbers do not identify the street record.
- For a locality, premise and street components do not identify the locality record.

## Investigate component changes

Compare three parts of the response:

- `parsedQuery`: input components used for matching, including structured overrides.
- `features[].properties`: the returned address record.
- `features[].matchCode`: feedback on how individual components matched.

When reviewing parsed input:

- Retain the original input separately if you need it. The geocoder normalises the query, so `query` may differ from the submitted string.
- Check the matched record to confirm an address exists. Parsing alone does not confirm it.
- Supply a component's known value directly if it was parsed incorrectly. See the [structured input example](/guides/addresses/quickstart#use-structured-address-components).

This excerpt illustrates a candidate that needs review:

```json
{
  "matchCode": {
    "streetName": "fuzzy",
    "localityName": "neighbour",
    "complexUnitTypeDescription": "no",
    "complexUnitIdentifier": "exact",
    "streetNumber1": "exact"
  }
}
```

The feedback identifies these differences:

- `complexUnitIdentifier` and `streetNumber1` matched exactly.
- `streetName` matched with spelling differences.
- `localityName` matched a neighbouring locality.
- `complexUnitTypeDescription` did not match.

Compare the returned fields with the input to show the actual changes to a user.

Use the [match-code definitions](#match-code) to interpret each code. The [full input comparisons](/guides/addresses/match-quality-examples) show changes to review.

## Compare input and matched addresses

Use [Match Quality Examples](/guides/addresses/match-quality-examples) for the complete comparisons, matching conditions, and scores across address, street, and locality results.

## Check the returned point

`properties.geoFeature` describes the location represented by the point. For example, `FRONT DOOR ACCESS` describes an entrance, while `BUILDING CENTROID` describes a building centre. A centroid is not necessarily a suitable routing destination.

Approximate geocodes include values such as `GAP GEOCODE`, `LETTERBOX`, and `UNKNOWN`. `STREET LOCALITY` and `LOCALITY` identify broader points that do not locate a specific premise.

Use `minGeoFeatureLevel` to set the minimum category of geocode detail. It is independent of `matchType`, and broader levels also accept more detailed points. The filter does not set a maximum positional error in metres.

For example, require both an address record and an address-level geocode:

```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 "address=113 Canberra Ave Griffith ACT 2603" \
  --data-urlencode "matchType=address" \
  --data-urlencode "minGeoFeatureLevel=address"
```

Use a Geoscape Hub application's Consumer Key with Addresses API access. A stricter filter can leave a processed search with no candidates. See the [Geocode parameter reference](/reference/addresses-v2-address-search#geocode-2/query-parameters) for the available detail levels.

## Decide whether to accept the candidate

1. Confirm that the record type and point detail meet your needs.
2. Compare the formatted address with the input, checking unit and street numbers, street name, locality, state, and postcode. If you require a particular unit, confirm its returned fields match the input.
3. Review component changes and alternatives. Ask the user to confirm material changes or weaker candidates.
4. Apply your application's acceptance policy and preserve the accepted `addressId` for a lookup.

Read request-level and feature-level `messages` as well. A warning about unavailable additional data can accompany a usable address match. See [Additional Properties](/guides/addresses/additional-properties#handle-unavailable-data).

## Other matching workflows

[Addresses from Coordinates](/guides/addresses/reverse-geocoding) uses search method and distance to assess a result from coordinates. [Postal Address Matching](/guides/addresses/mailpoint) uses postal diagnostics for DPID matching. Their metadata differs from the geocoder's quality and component feedback.