Skip to main content

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 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.

​
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")

​
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 and render envelopes.

​
Example response

{
  "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": [/* … */] }
    ]
  }
}