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:
Code
Use the CRS headers to control coordinate interpretation:
Content-Crsidentifies the input CRS.Accept-Crsselects the output CRS.
Both default to GDA94 (EPSG:4283). GeoJSON coordinates are returned in [longitude, latitude] order. See CRS & GDA2020.
Understand the default search
With matchType omitted, the service tries these searches in order and returns the first stage with results:
- Find a property containing the point and return matching address points within that property polygon.
- Find nearby address points.
- Find nearby street-locality points.
- Find a locality intersecting the search area.
- 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:
- Address, if any address type is included.
- Street, if no address type is included.
- 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.
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.
Follow Error Handling for failed requests. Preserve the returned attribution.