> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prontiq.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Reverse Geocode

> Find Australian addresses near a latitude and longitude.

Reverse geocode returns addresses near a coordinate, sorted by distance. Use it
when a user drops a pin, shares device GPS coordinates, or chooses a point on a
map and you need nearby valid addresses.

<Info>
  Usage is metered in credits. See the [Credits guide](/guides/credits) for response headers and
  usage behaviour.
</Info>

## When to use it

* Find the nearest known address to a map pin.
* Validate whether a coordinate is close to an expected address.
* Build proximity workflows that start with latitude and longitude.

Use [Autocomplete](/guides/address/autocomplete) or
[Validate](/guides/address/validate) when the user starts with address text.

## Request

| Parameter | Type    | Required | Default | Description                                |
| --------- | ------- | -------- | ------- | ------------------------------------------ |
| `lat`     | number  | Yes      | —       | Latitude in decimal degrees, -90 to 90.    |
| `lon`     | number  | Yes      | —       | Longitude in decimal degrees, -180 to 180. |
| `radius`  | number  | No       | `100`   | Search radius in metres, 1-50,000.         |
| `limit`   | integer | No       | `5`     | Maximum nearby addresses to return, 1-20.  |

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.prontiq.dev/v1/address/reverse?lat=-33.8568&lon=151.2153&radius=200&limit=3" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```typescript TypeScript SDK theme={null}
  import { Prontiq } from "@prontiq/sdk";

  const prontiq = new Prontiq({
    serverURL: "https://api.prontiq.dev",
    apiKeyAuth: process.env.PRONTIQ_API_KEY!,
  });

  const response = await prontiq.address.reverseGeocodeAddress({
    lat: -33.8568,
    lon: 151.2153,
    radius: 200,
    limit: 3,
  });
  const { result } = response;

  for (const address of result.results) {
    console.log(`${address.addressLabel} — ${address.distanceM}m`);
  }
  ```

  ```python Python SDK theme={null}
  from prontiq import Prontiq

  client = Prontiq()

  response = client.address.reverse_geocode(
      lat=-33.8568,
      lon=151.2153,
      radius=200,
      limit=3,
  )

  for address in response.results:
      print(address.address_label, address.distance_m)
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "results": [
    {
      "id": "GANSW716903927",
      "addressLabel": "SHOP 14, 2 CIRCULAR QUAY EAST",
      "localityName": "SYDNEY",
      "state": "NSW",
      "postcode": "2000",
      "distance_m": 79.2
    }
  ],
  "total": 1
}
```

## Field notes

| Field        | Meaning                                            |
| ------------ | -------------------------------------------------- |
| `results`    | Nearby address documents sorted nearest-first.     |
| `distance_m` | Distance from the requested coordinate in metres.  |
| `total`      | Total addresses found inside the requested radius. |

Returned address documents may include the same geocode and boundary fields
documented in [Address API concepts](/guides/address/overview#geocode-and-location).

## Integration tips

* Start with a small radius for dropped pins, then let the user expand if no
  useful result appears.
* Show `distance_m` to users when multiple candidates are close together.
* Coordinates must be WGS84 decimal degrees.

See the [Reverse geocode API reference](/api-reference/reverse) for the
generated schema and live playground.