places_in_view
What is over THERE: given a position and the direction the user is facing, the places inside that cone, and whether the ground and the buildings in between let them actually be seen. Use this for "what is that over there", "is there a pub in that direction", "what am I looking at". Use nearby_places instead when the question is about what is NEAR a point rather than what is in a direction. Provide lat, lon, bearing_deg (degrees CLOCKWISE FROM TRUE NORTH: 0 north, 90 east, 180 south, 270 west) and at least one of category or name; category=building reaches named buildings. Optional fov_deg is the FULL width of the cone (default 60, so 30 degrees either side), radius_m the range (default 1000, max 5000), eye_height_m the observer's eye height (default 1.6). Each result carries distance_m, bearing_deg, a signed angular_offset_deg (negative left, positive right), a spoken direction, and a visibility block. READ THE VISIBILITY BLOCK BEFORE SAYING ANYTHING: clear means nothing in the data stands in the way, occluded names what does (a hill, or a building with its height), and unknown means NO check could run: with unknown say you cannot tell, never that it is visible. Read basis too: terrain-only in a town means hills were checked and buildings were not, which is weak. A non-zero out_of_sector means there ARE matching places nearby, just not in that direction, so say that rather than "nothing nearby". coverage names the datasets that answered and caveat is the standing limit: visibility is modelled from maps, not observed, and trees, walls, scaffolding and weather are not in it. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude of the observer in decimal degrees (−90 to 90). | |
| lon | Yes | Longitude of the observer in decimal degrees (−180 to 180). | |
| name | No | A place name or brand to look for. At least one of `category` and `name` is required. | |
| limit | No | Maximum number of results (1–25, default 5). | |
| fov_deg | No | Full width in degrees of the cone centred on `bearing_deg` (1–360, default 60, so 30 degrees either side). The FULL width, not the half angle. | |
| category | No | The kind of place to look for, from the same vocabulary `nearby_places` uses ("cafe", "pub", "fuel", "charging_station" …). Use "building" to ask what a named building over there is. At least one of `category` and `name` is required. | |
| radius_m | No | Maximum straight-line range in metres (1–5000, default 1000). | |
| bearing_deg | Yes | Which way the observer is facing, in degrees **clockwise from true north** (0 = north, 90 = east, 180 = south, 270 = west). Required: this tool answers "what is over there", and "there" has to point somewhere. | |
| eye_height_m | No | Height of the observer's eye above the ground in metres (0–500, default 1.6, a standing adult). A driver's eye is nearer 1.2 m. | |
| visible_only | No | When true, return only places whose visibility verdict is `clear`. Default false, which returns everything in the cone WITH its verdict, usually the better answer, because "it is there but you cannot see it from here" is worth saying. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| caveat | Yes | The standing caveat: visibility here is modelled, not observed. | |
| results | Yes | Places inside the cone, best first: everything visible before everything unchecked before everything occluded, and within each of those, nearest and most nearly dead-ahead first. | |
| coverage | Yes | One sentence naming which datasets the visibility verdicts were actually checked against. Worth repeating when a verdict is being relied on. | |
| out_of_sector | No | How many otherwise-matching places were dropped for lying outside the cone. Non-zero means there ARE matching places near the observer, just not in the direction they are facing, so say that rather than "nothing nearby". |