---
title: Reverse Geocoding | Plaza Docs
description: Convert coordinates into addresses and place names with Plaza's reverse geocoding API.
---

## Endpoint

```
POST /api/v1/geocode/reverse
```

Returns the nearest addresses and places for a coordinate pair.

## Request body

| Field      | Type   | Default | Description                                                                            |
| ---------- | ------ | ------- | -------------------------------------------------------------------------------------- |
| `geometry` | object | —       | **Required.** GeoJSON Point geometry (`{"type": "Point", "coordinates": [lng, lat]}`). |
| `radius`   | int    | 200     | Search radius in meters (1–5000).                                                      |
| `limit`    | int    | 20      | Max results (1–1,000).                                                                 |
| `layer`    | string | —       | Filter by type: `house`, `poi`.                                                        |
| `lang`     | string | —       | BCP 47 language tag for result names (e.g. `de`, `ja`, `en`).                          |

## Basic request

Terminal window

```
curl -X POST https://plaza.fyi/api/v1/geocode/reverse \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PLAZA_API_KEY" \
  -d '{"geometry": {"type": "Point", "coordinates": [2.2945, 48.8584]}}'
```

```
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [2.2945, 48.8584]
      },
      "properties": {
        "osm_id": 5013364,
        "osm_type": "way",
        "display_name": "Eiffel Tower",
        "name": "Eiffel Tower",
        "category": "tourism",
        "subcategory": "attraction",
        "distance_m": 12.4,
        "source": "place"
      }
    }
  ]
}
```

## SDK examples

### TypeScript

```
import Plaza from "@plazafyi/sdk";


const client = new Plaza();


const results = await client.v1.geocode.reverse({
  geometry: { type: "Point", coordinates: [-73.9857, 40.7484] },
  limit: 3,
});


console.log(results.features[0].properties.display_name);
// "Empire State Building"
```

### Python

```
import plaza


client = plaza.Client()


results = client.v1.geocode.reverse(
    geometry={"type": "Point", "coordinates": [139.6503, 35.6762]},
    limit=3,
)


for feature in results.features:
    name = feature.properties["display_name"]
    dist = feature.properties["distance_m"]
    print(f"{name} ({dist:.0f}m away)")
```

### Go

```
results, err := client.V1.Geocode.Reverse(ctx, &plaza.ReverseGeocodeParams{
    Geometry: plaza.GeoJSONPoint{Type: "Point", Coordinates: []float64{-74.0445, 40.6892}},
    Limit:    plaza.F(3),
})
if err != nil {
    panic(err)
}


fmt.Println(results.Features[0].Properties.DisplayName)
// "Statue of Liberty"
```

## When to adjust the radius

The default 200m works well in dense urban areas. Adjust based on context:

**Shrink (10–50m)** for precision — user taps a building, you want that building, not the coffee shop next door.

**Expand (500–2000m)** in suburban/rural areas where the nearest mapped address may be far from the GPS coordinate.

**Go wide (2000–5000m)** for “what area am I in” queries with `layer=poi`.

## Common patterns

### Pin drop lookup

Terminal window

```
curl -X POST https://plaza.fyi/api/v1/geocode/reverse \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PLAZA_API_KEY" \
  -d '{"geometry": {"type": "Point", "coordinates": [-0.1419, 51.5014]}, "limit": 1}'
```

### GPS track to addresses

```
coordinates = [(-73.985, 40.748), (-73.977, 40.752), (-73.969, 40.758)]


for lng, lat in coordinates:
    result = client.v1.geocode.reverse(
        geometry={"type": "Point", "coordinates": [lng, lat]},
        layer="house",
    )
    if result.features:
        addr = result.features[0].properties
        print(addr.get("display_name", "Unknown"))
```

For bulk conversion, use [batch geocoding](/guides/batch-geocoding/index.md) instead.

### Nearby POIs

Terminal window

```
curl -X POST https://plaza.fyi/api/v1/geocode/reverse \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PLAZA_API_KEY" \
  -d '{"geometry": {"type": "Point", "coordinates": [151.2093, -33.8688]}, "layer": "poi", "radius": 1000, "limit": 5}'
```

Returns POIs instead of house addresses, with `category` and `subcategory` fields.