# Addresses from Coordinates

Use this guide to find an address, street, or locality from coordinates and interpret how the result was selected.

The result can come from a property or locality intersection, or from a nearby point. Inspect how it was selected before using it.

## Submit a position

Use a Geoscape Hub application with Addresses API access and send its Consumer Key in the `Authorization` header. Supply both `latitude` and `longitude`:

```shell
curl --fail-with-body --get \
  "https://api.psma.com.au/v2/addresses/reverseGeocoder" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Accept: application/geo+json" \
  -H "Content-Crs: <https://www.opengis.net/def/crs/EPSG/0/4283>" \
  --data-urlencode "latitude=-35.32202098" \
  --data-urlencode "longitude=149.14668176"
```

Use the CRS headers to control coordinate interpretation:

- `Content-Crs` identifies the input CRS.
- `Accept-Crs` selects the output CRS.

Both default to GDA94 (EPSG:4283). GeoJSON coordinates are returned in `[longitude, latitude]` order. See [CRS & GDA2020](/guides/gda-2020).

## Understand the default search

With `matchType` omitted, the service tries these searches in order and returns the first stage with results:

1. Find a property containing the point and return matching address points within that property polygon.
2. Find nearby address points.
3. Find nearby street-locality points.
4. Find a locality intersecting the search area.
5. Search for a locality point, expanding the search radius if necessary.

`Locality Polygon Intersect` means a locality intersects the search area. The query point itself does not necessarily lie inside that locality. The result is not a combined list of all address, street, and locality candidates.

## Restrict the result category

Specifying `matchType` changes the search strategy:

| Query value | Search |
| --- | --- |
| `address`, `primaryAddress`, or `secondaryAddress` | Property intersection, then address-point distance with an expanding radius |
| `street` or `streetLocality` | Street-locality point distance with an expanding radius |
| `locality` | Locality intersection, then a locality search with an expanding radius |

Within the address category, primary and secondary filters restrict the returned records. For a comma-separated list, category selection follows this order:

1. Address, if any address type is included.
2. Street, if no address type is included.
3. Locality, if neither address nor street is included.

Requesting all supported match types uses the default search strategy.

An explicit list such as `matchType=street,locality` does not request a combined result or the default fallback sequence.

The radius expansion is bounded. A forced category can produce a result far from the query, so apply your own acceptable-distance rule. `maxResults` defaults to `1` and accepts up to `20`. An expanded search may return fewer candidates than requested.

Use `minGeoFeatureLevel` to filter the detail of the returned geocodes independently of the record category. See [geocode point guidance](/guides/addresses/assessing-matches#check-the-returned-point).

## Interpret match metadata

Each feature contains:

| Field | Meaning |
| --- | --- |
| `matchType` | `Primary Address`, `Secondary Address`, `Street`, or `Locality` |
| `matchDistance` | Distance in metres from the query point to the returned record's point |
| `matchMethod` | Search stage that produced the feature |
| `properties.geoFeature` | Type of geocode used for the returned point |

| `matchMethod` | How the result was selected |
| --- | --- |
| `Property Polygon Intersect` | The query point intersects a property polygon. An address point within the property is returned. |
| `Address Point Distance` | Address points were selected by distance. |
| `Street Locality Point Distance` | Street-locality points were selected by distance. |
| `Locality Polygon Intersect` | A locality polygon intersects the search area. |
| `Locality Point Distance` | Locality points were selected by distance. |

`matchDistance` is point-to-point distance, rather than distance to a polygon boundary. It can be non-zero for an intersection result. Reverse geocoding does not return the geocoder's `matchQuality`, `matchScore`, or `matchCode`.

## Handle missing results and related data

A processed search returns `200` with a `FeatureCollection`. No returned candidates means an empty `features` array. It is not an ID lookup's `404` response. Invalid or missing coordinates, unsupported filters, and malformed CRS headers return `400`.

Use `additionalProperties` for related data. Some properties require paid-plan access, add credit costs, and require an address-level match. Review feature-level `messages` when an attribute is unavailable. See [Additional Properties](/guides/addresses/additional-properties).

Follow [Error Handling](/guides/errors) for failed requests. Preserve the returned [attribution](/guides/attribution).

## Next steps

- [Review the Reverse Geocode endpoint](/reference/addresses-v2-address-search#reverse-geocode-2)
- [Retrieve attributes using a returned ID](/guides/addresses/quickstart#4-retrieve-attributes-for-the-matched-address)