Skip to content

50,000 free calls a month, card-free. Get an API key →

Documentation menu
docs / examples / nearby-places-heading
Example

Nearby places, described from where you are standing

Give the search a compass heading and every result is phrased from the user's point of view: "ahead and slightly to your right, about 80 metres". That is what a voice or wearable client reads out, instead of coordinates.

json
{
  "method": "tools/call",
  "params": {
    "name": "nearby_places",
    "arguments": {
      "lat": 51.50743,
      "lon": -0.09934,
      "category": "cafe",
      "radius_m": 500,
      "limit": 5,
      "heading_deg": 62,
      "fov_deg": 120
    }
  }
}

Worth knowing

  • heading_deg is degrees clockwise from true north: 0 is north, 90 east, 180 south, 270 west.
  • fov_deg is the full width of the cone, so 120 keeps only what lies within 60 degrees either side of dead ahead. The number of results dropped comes back as out_of_view.
  • Omit heading_deg and results fall back to cardinal directions, so the tool works with or without a compass.
  • Use name instead of, or alongside, category for "where is the nearest Lloyds": every word must appear in the place's name or one of its alternative names, with the last word also matching as a prefix.