Geocoding

Nearby Search

Find places, venues, and points of interest near a geographic coordinate using our Pelias-powered geocoding engine.

Nearby search returns places sorted by distance from a given point. Use it for "what's around me" features, nearby POI discovery, or location-based recommendations.

Try It

Enter your API key to see live map demos.

Don't have one? Get your free API key

Endpoint

GET https://maps.guru/api/v1/geocoding/nearby?point.lat={lat}&point.lon={lon}&key={api_key}

Authentication

API key required via one of:

Query parameter: ?key=mapx_your_key
Header: Authorization: Bearer mapx_your_key
Header: X-API-Key: mapx_your_key

Parameters

Parameter	Type	Required	Default	Description
`point.lat`	number	Yes	—	Latitude of the center point (-90 to 90)
`point.lon`	number	Yes	—	Longitude of the center point (-180 to 180)
`boundary.circle.radius`	number	No	50	Search radius in kilometres (max 50)
`size`	number	No	10	Maximum results (1–40)
`layers`	string	No	—	Filter by layer: `venue`, `address`, `street`, `neighbourhood`, `locality`, `county`, `region`, `country`, `coarse`, `postalcode`
`sources`	string	No	—	Filter by data source: `osm`, `oa`, `gn`, `wof`
`lang`	string	No	`en`	Response language (BCP 47)

Example Request

Find places near Baner, Pune:

curl "https://maps.guru/api/v1/geocoding/nearby?point.lat=18.559&point.lon=73.786&size=5&key=mapx_your_key"

With a smaller radius and venue filter:

curl "https://maps.guru/api/v1/geocoding/nearby?point.lat=18.559&point.lon=73.786&boundary.circle.radius=1&layers=venue&size=10&key=mapx_your_key"

Example Response

Responses are GeoJSON FeatureCollection format with results sorted by distance:

{
  "geocoding": {
    "version": "0.2",
    "query": {
      "point.lat": 18.559,
      "point.lon": 73.786,
      "size": 5
    }
  },
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [73.787145, 18.558889]
      },
      "properties": {
        "id": "way:264286363",
        "gid": "openstreetmap:venue:way/264286363",
        "layer": "venue",
        "source": "openstreetmap",
        "name": "Baneshwar Temple",
        "label": "Baneshwar Temple, Pune, MH, India",
        "confidence": 0.7,
        "distance": 0.121,
        "country": "India",
        "region": "Maharashtra",
        "county": "Pune",
        "locality": "Pune"
      }
    }
  ]
}

The distance property indicates how far (in kilometres) each result is from the queried point.

Caching

Responses are cached for 1 hour at the edge using Cloudflare KV. The X-Cache response header indicates cache status:

X-Cache: HIT — served from cache
X-Cache: MISS — fetched from Pelias and cached

How Nearby Differs from Reverse Geocoding

Feature	Nearby	Reverse
Purpose	Find what's around a point	Find the address of a point
Results	Multiple places sorted by distance	Closest matching address
Use case	"Show me restaurants nearby"	"What address is at this pin?"
Default radius	50 km	N/A (closest match)
Layer filter	Commonly `venue`	Commonly `address`

Layers Reference

Layer	Description
`venue`	Points of interest, businesses, landmarks
`address`	Street-level addresses
`street`	Street names
`neighbourhood`	Neighbourhoods and districts
`locality`	Cities and towns
`county`	Counties
`region`	States and provinces
`country`	Countries
`postalcode`	Postal codes
`coarse`	All administrative layers combined

Place Lookup

Fetch full details for one or more places by their GID (global identifier), including building footprints when available.

Directions

Calculate routes between points with turn-by-turn navigation.