> ## Documentation Index
> Fetch the complete documentation index at: https://docs.footstep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# search_places

> Find places and points of interest near a location

Search for places by category or keyword near a location. Unlike `geocode` (which resolves a single specific address or landmark to coordinates), this is designed for discovery queries like "coffee shops near me" or "restaurants in Soho". Results are ranked by proximity.

`query` accepts both **categories** (cafe, restaurant, supermarket, park, gym, atm, pharmacy, hotel, hospital, fuel, library, museum, …) and **specific names** (Costa, Tesco, Black Sheep Coffee, Tower Bridge). Categories are expanded internally to multilingual synonyms — "cafe" also catches "coffee", "café", "kaffee", etc. Hybrid queries like "italian restaurant" combine the literal phrase with the category synonyms.

For "find X near Y" queries, pass `near` as a place name and the search center is geocoded for you — there is no need to call `geocode` first. If you already have coordinates, pass `lat` and `lon` instead — this disambiguates common place names that exist in multiple countries.

Qualify ambiguous `near` strings tightly: "Lebanon, NH" not just "Lebanon", "Cambridge, UK" when you specifically mean the English one. Add `country` (comma-separated ISO 3166-1 alpha-3 codes, e.g. `"GBR"` or `"USA,CAN"`) when the search context is country-bound.

## Example prompts

* "Find coffee shops near Kings Cross" → `search_places(query="coffee shop", near="Kings Cross, London")`
* "What restaurants are within 1km of my hotel?" → `search_places(query="restaurant", lat=..., lon=..., radius=1)`
* "Are there any supermarkets near 51.53, -0.12?" → `search_places(query="supermarket", lat=51.53, lon=-0.12)`
* "Show me parks within walking distance of Tower Bridge" → `search_places(query="park", near="Tower Bridge, London")`
* "Find an airport near Lebanon, NH" → `search_places(query="airport", near="Lebanon, NH", country="USA")`

## What you get back

A list of matching places, each with coordinates, name, full label, distance from the search point in meters, the bearing from the search point (`bearing_deg` 0–360 plus an 8-point `bearing_compass` like `"NE"`), and (when below 1.0) a confidence score. Results are sorted by proximity. Bearing is omitted for any place sitting essentially at the search point.

When every result is in the same country / region (the typical case for a proximity search), those admin fields are hoisted to a top-level `context` object instead of being repeated on each row. So the response shape is `{ results: [...], context?: { country, country_code, region } }` — read shared admin from `context`, per-result fields from `results[i]`.

## Map rendering

Responses include a `render` envelope with a `point` layer for the matched POIs. Each Feature carries the row's metadata (`name`, `label`, `place_type`, `confidence`) on `properties` so popups can be wired off the GeoJSON. Pass `compact: true` for summary-only responses. See [response defaults & controls](/mcp/defaults) and [render envelopes](/mcp/render-envelopes).

## Example response

```json theme={null}
{
  "structuredContent": {
    "results": [
      {
        "name": "Costa",
        "label": "Costa Coffee, Camden, London",
        "coordinates": { "lat": 51.54, "lng": -0.14 },
        "place_type": "venue",
        "distance_meters": 320,
        "bearing_deg": 38,
        "bearing_compass": "NE"
      }
    ],
    "context": { "country": "United Kingdom" },
    "render": [
      { "kind": "point", "label": "Matched places", "data": {/* FeatureCollection */}, "bbox": [/* … */] }
    ]
  }
}
```