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

## Endpoint

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

Returns GeoJSON features ranked by relevance, with `display_name`, match `score`, and OSM metadata.

## Request body

| Field          | Type   | Default | Description                                                                                                        |
| -------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `q`            | string | —       | **Required.** The address or place name to geocode.                                                                |
| `limit`        | int    | 20      | Max results (1–1,000).                                                                                             |
| `focus`        | object | —       | GeoJSON Point geometry. Results near this coordinate rank higher (`{"type": "Point", "coordinates": [lng, lat]}`). |
| `country_code` | string | —       | ISO 3166-1 alpha-2 code. Restrict results to one country.                                                          |
| `layer`        | string | —       | Filter by type: `address`, `poi`, `admin`.                                                                         |
| `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 \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PLAZA_API_KEY" \
  -d '{"q": "1600 Pennsylvania Ave NW Washington DC"}'
```

```
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-77.0365, 38.8977]
      },
      "properties": {
        "osm_id": 238241022,
        "osm_type": "way",
        "display_name": "The White House, 1600 Pennsylvania Avenue NW, Washington, DC 20500",
        "score": 0.98,
        "source": "structured",
        "country_code": "us"
      }
    }
  ]
}
```

## SDK examples

### TypeScript

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


const client = new Plaza();


const results = await client.v1.geocode.forward({
  q: "Alexanderplatz, Berlin",
  limit: 3,
  countryCode: "de",
});


for (const feature of results.features) {
  const [lng, lat] = feature.geometry.coordinates;
  console.log(`${feature.properties.display_name}: ${lat}, ${lng}`);
}
```

### Python

```
import plaza


client = plaza.Client()


results = client.v1.geocode.forward(
    q="Shibuya Crossing, Tokyo",
    limit=3,
    country_code="jp",
    lang="en",
)


for feature in results.features:
    coords = feature.geometry.coordinates
    print(f"{feature.properties['display_name']}: {coords[1]}, {coords[0]}")
```

### Go

```
package main


import (
    "context"
    "fmt"
    "github.com/plazafyi/plaza-go"
)


func main() {
    client := plaza.NewClient()


    results, err := client.V1.Geocode.Forward(context.Background(), &plaza.GeocodeParams{
        Q:           "Copacabana Beach, Rio",
        Limit:       plaza.F(3),
        CountryCode: plaza.F("br"),
    })
    if err != nil {
        panic(err)
    }


    for _, f := range results.Features {
        fmt.Printf("%s: %f, %f\n",
            f.Properties.DisplayName,
            f.Geometry.Coordinates[1],
            f.Geometry.Coordinates[0],
        )
    }
}
```

## Address interpolation

When an exact housenumber isn’t mapped but the street has address ranges, Plaza interpolates the coordinate along the street segment. Interpolated results have `"interpolated": true`, a `"confidence"` field, a lower `"score"` (0.5), and `"source": "interpolation"`. Common in suburban and rural areas.

## Synonym expansion

Queries are normalized before matching. “St” expands to “Street” and “Saint”, “Ave” to “Avenue”, “Dr” to “Drive”, etc. Works across languages — “Str.” matches “Straße”, “Pl.” matches “Place” and “Platz”. Send input as-is.

## Tips for better results

**Use the focus point.** If you know roughly where the user is, pass `focus` as a GeoJSON Point. “Springfield” matches dozens of cities across the US. With a focus point near Illinois, Springfield IL wins.

**Set `country_code` when you can.** It cuts ambiguity and speeds up the query. If your app only serves one country, always pass it.

**Use `layer` to filter noise.** Looking for street addresses? Set `layer=address` to skip POIs and admin boundaries. Building a region picker? Use `layer=admin`.

**Prefer full addresses over fragments.** “123 Main St, Portland OR” is much better than “123 Main”. Include city and state/country when available.