Reverse Geocoding

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

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

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 instead.

Nearby POIs

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.