Horizon API — terrain horizon panorama by azimuth

`GET /v1/horizon`

Terrain horizon profile — the terrain elevation angle for every azimuth around a point. Combine it with a sky object's track (sun, moon, Milky Way) to find when the object clears the ridge after rising and when it disappears behind terrain before setting. Earth curvature and atmospheric refraction are accounted for. Billed as one unit per ten returned azimuths (rounded up).

Request

Field	Type	Required	Default	Description
`lat`	float	yes	—	Observer latitude, −90..90.
`lng`	float	yes	—	Observer longitude, −180..180.
`azStepDeg`	float	no	1.0	Azimuth step in degrees, 0.5–10.
`fromAzimuthDeg`, `toAzimuthDeg`	float	no	full 360°	Limit to an arc (both or neither); wraps through 360° when from > to.
`lengthM`	float	no	30000	Ray length in metres, max 50000.
`observerHeightM`	float	no	1.7	Eye/camera height above ground.

Examples

curl -H "X-API-Key: gi_live_..." \
  "https://geoinsight.dev/v1/horizon?lat=49.2992&lng=19.9496"

import requests

r = requests.get(
"https://geoinsight.dev/v1/horizon",
params={"lat": 49.2992, "lng": 19.9496},
headers={"X-API-Key": "gi_live_..."},
)
print(r.json()["azimuths"][:3])

const res = await fetch(
  "https://geoinsight.dev/v1/horizon?lat=49.2992&lng=19.9496",
  { headers: { "X-API-Key": "gi_live_..." } },
);
console.log((await res.json()).azimuths.slice(0, 3));

Response

{
  "observer_height_m": 1.7,
  "length_m": 30000,
  "az_step_deg": 1.0,
  "azimuths": [
{ "azimuth_deg": 0.0, "horizon_elevation_deg": 2.3 },
{ "azimuth_deg": 1.0, "horizon_elevation_deg": 2.4 }
  ],
  "dataset": "copernicus-glo-30",
  "resolution_m": 30
}

Field	Type	Unit	Description
`observer_height_m`	number	m	Eye height above ground used for the calculation, echoed from the request (default 1.7). Raising it lowers every horizon angle.
`length_m`	number	m	Ray-march radius, echoed from the request (default 30 000). Terrain beyond this distance is not considered, so a far mountain range can be missed if this is too small.
`az_step_deg`	number	deg	Angular spacing between returned azimuths, echoed from the request.
`azimuths`	array	—	The horizon panorama, ordered by increasing azimuth.
`azimuths[].azimuth_deg`	number	deg	Compass bearing: 0 = north, 90 = east, increasing clockwise.
`azimuths[].horizon_elevation_deg`	number	deg	Terrain elevation angle in that bearing, above the astronomical horizon. Negative where the ground falls away. An object is visible when its altitude exceeds this value.
`dataset`	string	—	Source dataset identifier.
`resolution_m`	integer	m	Ground sample distance of the source raster.

Using it (effective sunrise): your app already knows the sun's track — azimuth and elevation over time. The sun is visible when its elevation exceeds horizon_elevation_deg at its current azimuth. The first such moment after astronomical sunrise is the effective sunrise over terrain; the last before sunset is when it dips behind the ridge. One panorama serves the sun, moon and Milky Way for the whole day/night — cache it client-side.

Note: GLO-30 is a ~30 m surface model, not a building-height database.