Geocoding

By the end of this guide, you'll know how to turn addresses into coordinates (and coordinates into addresses) using Plaza's geocoding endpoints.

Everything runs against OSM data in Postgres. No external geocoding service is involved.

Forward geocoding

Turn an address or place name into coordinates.

curl "https://plaza.fyi/api/v1/geocode?q=221B+Baker+Street+London" \
  -H "x-api-key: pk_live_YOUR_KEY"

Parameter	Required	Description
q	yes	Address or place name
limit	no	Max results (default 20, max 100)
lat	no	Focus latitude -- biases results nearby
lng	no	Focus longitude

Response:

{
  "results": [
    {
      "osm_id": 12345678,
      "osm_type": "node",
      "display_name": "221B Baker Street, Marylebone, London, NW1 6XE",
      "lat": 51.5238,
      "lng": -0.1585,
      "address": {
        "house_number": "221B",
        "road": "Baker Street",
        "suburb": "Marylebone",
        "city": "London",
        "postcode": "NW1 6XE",
        "country": "United Kingdom"
      }
    }
  ],
  "count": 1
}

The focus point matters

If you search for "Springfield" without a focus point, you could get Springfield, Illinois or Springfield, Massachusetts or Springfield, Oregon. Pass lat and lng to bias results toward a location:

# Springfield near Illinois
curl "https://plaza.fyi/api/v1/geocode?q=Springfield&lat=39.78&lng=-89.65" \
  -H "x-api-key: pk_live_YOUR_KEY"

If you know roughly where your user is (from IP geolocation, GPS, or their timezone), always pass it. The results are noticeably better.

Reverse geocoding

Turn coordinates into an address.

curl "https://plaza.fyi/api/v1/geocode/reverse?lat=48.8584&lng=2.2945" \
  -H "x-api-key: pk_live_YOUR_KEY"

Parameter	Required	Description
lat	yes	Latitude
lng	yes	Longitude
radius	no	Search radius in meters (default 200, max 5,000)

Returns the nearest address to the given point. If nothing is found within the radius, you get a 404 not_found.

The default 200m radius works well in cities where addresses are dense. In rural areas or places with sparse address data, bump it up to 1,000-5,000m.

Autocomplete

For search-as-you-type UIs. Returns fast results from partial input.

curl "https://plaza.fyi/api/v1/geocode/autocomplete?q=starbuck&lat=40.7&lng=-74.0" \
  -H "x-api-key: pk_live_YOUR_KEY"

Parameter	Required	Description
q	yes	Partial query
limit	no	Max results (default 10, max 20)
lat	no	Focus latitude
lng	no	Focus longitude

Autocomplete is tuned for speed over exhaustiveness. It returns fewer results than a full forward geocode, but responds faster. The intended flow: show autocomplete results as the user types, then run a full forward geocode when they pick a result or hit enter.

Client examples

Python

import requests

resp = requests.get(
    "https://plaza.fyi/api/v1/geocode",
    params={"q": "Arc de Triomphe", "limit": 5},
    headers={"x-api-key": "pk_live_YOUR_KEY"}
)

for result in resp.json()["results"]:
    print(f"{result['display_name']}: {result['lat']}, {result['lng']}")

JavaScript

const resp = await fetch(
  "https://plaza.fyi/api/v1/geocode?" + new URLSearchParams({
    q: "Arc de Triomphe",
    limit: "5"
  }),
  { headers: { "x-api-key": "pk_live_YOUR_KEY" } }
);

const { results } = await resp.json();
results.forEach(r => console.log(`${r.display_name}: ${r.lat}, ${r.lng}`));

Reverse geocoding in Python

resp = requests.get(
    "https://plaza.fyi/api/v1/geocode/reverse",
    params={"lat": 40.7484, "lng": -73.9857},
    headers={"x-api-key": "pk_live_YOUR_KEY"}
)

print(resp.json())

Tips for better results

• Be specific with addresses. "Baker Street London" returns better results than "Baker Street". Include the city or country when you have it.
• Always pass a focus point. For common place names, the difference between biased and unbiased results is dramatic.
• Use autocomplete for UI, forward geocode for precision. Autocomplete prioritizes speed. Once the user selects a result, you already have coordinates -- no second call needed.
• Adjust the reverse geocoding radius. 200m default is fine for dense urban areas. Suburbs might need 500m. Rural areas might need 2,000m+. Don't crank it to 5,000m by default though -- that can return misleadingly distant results.