GET/v1/places/in-view

Auth	An API key, as `Authorization: Bearer snk_…` or `?api_key=snk_…`. Metered. Needs a full key; a browser (`maps`) key is refused.
Price	A flat 5 calls. Class: standard. Published as `unit_rules.places_in_view` in /pricing.json.

What it does

GET /v1/places/in-view.

Call it

bash

curl -fsS -X GET "https://api.mapmap.ai/v1/places/in-view?lat=…&lon=…&bearing_deg=…" \
  -H "Authorization: Bearer $MAPMAP_KEY"

Parameters

Name	In	Type	Required	Description
lat	query	number	yes	Observer latitude in decimal degrees
lon	query	number	yes	Observer longitude in decimal degrees
bearing_deg	query	number	yes	Direction the observer is facing, degrees CLOCKWISE FROM TRUE NORTH (0 = north, 90 = east). Magnetic bearings must be converted by the caller; nothing here corrects for declination
fov_deg	query	number	no	FULL width of the cone in degrees (1–360, default 60, so 30 degrees either side of the bearing). The same meaning `fov_deg` has on the `nearby_places` MCP tool
radius_m	query	integer	no	Maximum straight-line range in metres (1–5000, default 1000) Limits: at least 0.
categories	query	string	no	Comma-separated place categories, normalised through the same vocabulary `GET /geocode/reverse` accepts (`cafe`, `pub`, `fuel`, `charging_station`, …; `coffee` → `cafe`, `petrol` → `fuel`). `categories=building` reaches named buildings, which is how to ask "what is that building over there". At least one of `categories` and `name` is required
name	query	string	no	Place name or brand filter, matched exactly as `GET /geocode/reverse`'s `name` matches it. At least one of `categories` and `name` is required
limit	query	integer	no	Results to return (1–25, default 5) Limits: at least 0.
eye_height_m	query	number	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; a first-floor window is nearer 4 m
target_height_m	query	number	no	Height above its own ground at which each place is tested (0–500, default 0, the place's door). Raise it to ask about rooflines, spires or masts
visible_only	query	boolean	no	When true, drop everything whose verdict is not `clear`. Default false: an occluded or unchecked place is returned WITH its verdict, because dropping it would be a visibility claim made silently

Responses

200Places in the cone, each with distance_m, bearing_deg, angular_offset_deg and a visibility report naming exactly what was checked; plus an observer echo, an excluded count, a coverage block naming the datasets that answered, and the standing caveat

Field	Type	Required	Description
caveat	string	no	Visibility is modelled, not observed.
coverage	object	no	The terrain and building data the visibility model read.
excluded	object	no	What was left out and why: out of the sector, occluded, or beyond the visibility check.
observer	object	no	The observer: position, `bearing_deg`, `fov_deg`, eye height and ground elevation.
results	object[]	no	Places in the field of view: `name`, `label`, `categories`, `bearing_deg`, `angular_offset_deg`, `distance_m` and `visibility`.

Example: Recorded from the hosted gateway on 2026-11-05 with a test key: GET /v1/places/in-view?lat=51.5074&lon=-0.1278&bearing_deg=90&fov_deg=60&radius_m=800&categories=pub&limit=3; lists trimmed to their first items

json

{
  "caveat": "Visibility is modelled, not observed. It is a straight sight line over sampled bare-earth terrain and over OpenStreetMap building footprints extruded to their tagged heights, corrected for earth curvature and standard refraction. It does not model trees, walls, fences, hoardings, scaffolding, vehicles, street furniture, weather, darkness or which way a frontage points, and building height coverage in OpenStreetMap is uneven. Treat a clear verdict as 'nothing in the data stands in the way', never as 'you will see it'.",
  "coverage": {
    "buildings": {
      "archive": "planet",
      "footprints_considered": 3275,
      "height_attribute": "render_height",
      "heights_defaulted": 1033,
      "heights_tagged": 2242,
      "note": "Heights come from the OSM `height` and `building:levels` tags. Where neither is mapped the tile schema substitutes a flat 5 m, which a tile cannot tell from a real 5 m building; any obstruction resting on one is reported with `building_height_basis: \"schema-default\"`. `heights_defaulted` counts how many of the footprints consulted for THIS query were in that position. Coverage is uneven and often poor: well tagged in large city centres, thin in most towns, industrial estates and new-build areas. A footprint the map gives no usable height at all is dropped rather than given an invented one, so it cannot occlude.",
      "source": "openstreetmap",
      "tiles_read": 1,
      "via": "vector tiles, `building` layer",
      "zoom": 14
    },
    "buildings_unavailable_reason": null,
    "datasets_available": "terrain-and-buildings",
    "statement": "Visibility was checked against both the bare-earth elevation model and OpenStreetMap building footprints.",
    "terrain": {
      "model": "bare-earth",
      "resolution_m": 30,
      "source": "mapzen-terrain-tiles"
    },
    "terrain_unavailable_reason": null,
    "tiles_failed": 0,
    "tiles_read": 1,
    "tiles_wanted": 1
  },
  "excluded": {
    "beyond_visibility_check": 0,
    "browse_truncated": false,
    "not_clear": {
      "occluded": 0,
      "unknown": 0
    },
    "out_of_sector": 88
  },
  "observer": {
    "bearing_deg": 90,
    "eye_height_m": 1.6,
    "fov_deg": 60,
    "ground_elevation_m": 14.54,
    "half_angle_deg": 30,
    "lat": 51.5074,
    "lon": -0.1278,
    "radius_m": 800,
    "target_height_m": 0
  },
  "results": [
    {
      "angular_offset_deg": 1,
      "bearing_deg": 91,
      "categories": [
        "pub"
      ],
      "city": "London",
      "country_code": "GB",
      "distance_m": 180.4,
      "label": "The Sherlock Holmes, 10-11 Northumberland Street, WC2N 5DB, London, Knepp Wildland, United Kingdom",
      "lat": 51.50737266540527,
      "lon": -0.12519396841526031,
      "name": "The Sherlock Holmes",
      "postcode": "WC2N 5DB",
      "type": "pub",
      "visibility": {
        "basis": "terrain-and-buildings",
        "checks": {
          "buildings": "occluded",
          "terrain": "occluded"
        },
        "obstruction": {
          "distance_m": 25.769621452396525,
          "height_above_sightline_m": 2.5088481550293444,
          "kind": "terrain"
        },
        "verdict": "occluded"
      }
    },
    {
      "angular_offset_deg": -5.8,
      "bearing_deg": 84.2,
      "categories": [
        "pub"
      ],
      "city": "London",
      "country_code": "GB",
      "distance_m": 218.3,
      "label": "The Ship and Shovell, London, Knepp Wildland, United Kingdom",
      "lat": 51.50760028236791,
      "lon": -0.12466162129452354,
      "name": "The Ship and Shovell",
      "postcode": null,
      "type": "pub",
      "visibility": {
        "basis": "terrain-and-buildings",
        "checks": {
          "buildings": "occluded",
          "terrain": "occluded"
        },
        "obstruction": {
          "distance_m": 27.292915546120952,
          "height_above_sightline_m": 2.7903621439703095,
          "kind": "terrain"
        },
        "verdict": "occluded"
      }
    }
  ]
}

400Invalid request