Line-of-sight API — terrain visibility between two points

`GET /v1/visibility`

Is a sky object (sun, moon, Milky Way) at a given azimuth and elevation visible from a point, or hidden behind terrain? Earth curvature and atmospheric refraction are accounted for. Billed as 1 unit per call.

Request

Field	Type	Required	Default	Description
`lat`	float	yes	—	Observer latitude, −90..90.
`lng`	float	yes	—	Observer longitude, −180..180.
`azimuthDeg`	float	yes	—	Object azimuth. 0 = N, clockwise, [0, 360).
`objectElevationDeg`	float	yes	—	Object elevation angle above the horizon, degrees.
`lengthM`	float	no	30000	Analysis ray length in metres, max 50000.
`observerHeightM`	float	no	1.7	Eye/camera height above the ground, metres.

Examples

curl -H "X-API-Key: gi_live_..." \
  "https://geoinsight.dev/v1/visibility?lat=53.3310&lng=14.2510&azimuthDeg=135.2&objectElevationDeg=3.5"

import requests

r = requests.get(
"https://geoinsight.dev/v1/visibility",
params={
    "lat": 53.3310, "lng": 14.2510,
    "azimuthDeg": 135.2, "objectElevationDeg": 3.5,
},
headers={"X-API-Key": "gi_live_..."},
)
print(r.json()["visible"])

const res = await fetch(
  "https://geoinsight.dev/v1/visibility?lat=53.3310&lng=14.2510&azimuthDeg=135.2&objectElevationDeg=3.5",
  { headers: { "X-API-Key": "gi_live_..." } },
);
console.log((await res.json()).visible);

Response

{
  "visible": false,
  "horizon_elevation_deg": 4.1,
  "blocked_at": { "lat": 53.3122, "lng": 14.3305, "d_m": 6120, "elevation": 154.0, "required_elevation_deg": 4.1 },
  "dataset": "copernicus-glo-30",
  "resolution_m": 30
}

Field	Type	Unit	Description
`visible`	boolean	—	true when the object clears the terrain horizon in that azimuth, i.e. objectElevationDeg > horizon_elevation_deg.
`horizon_elevation_deg`	number	deg	Terrain horizon angle in the requested azimuth, above the astronomical horizon. Negative when the ground falls away. Compare an object's altitude against this to decide visibility yourself.
`blocked_at`	object	—	The terrain point that blocks the line of sight, or null when the object is visible.
`blocked_at.lat`	number	deg	Latitude of the blocking terrain point.
`blocked_at.lng`	number	deg	Longitude of the blocking terrain point.
`blocked_at.d_m`	number	m	Distance from the observer to the obstruction — tells you whether it is a nearby bank or a distant ridge.
`blocked_at.elevation`	number	m a.s.l.	Terrain height at the blocking point.
`blocked_at.required_elevation_deg`	number	deg	Minimum object altitude needed to clear this obstruction. A client that knows the object's track can compute when it will rise above the ridge.
`dataset`	string	—	Source dataset identifier.
`resolution_m`	integer	m	Ground sample distance; obstructions narrower than this are not represented — see the note below.

Note: GLO-30 is a ~30 m surface model (it partially includes tree canopy and dense built-up areas), not a building-height database. A single building may be too small to appear in the grid, so this endpoint is not a substitute for building-level line-of-sight.