Geocoding

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

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.