GeoInsight API Docs Log in Get an API key

Sun exposure API

Whether a point is sunlit or shaded at a given moment, with solar position.

GET /v1/sun-exposure POST /v1/sun-exposure

Base URL https://geoinsight.dev. Every request needs the X-API-Key header — see authentication, what this call costs and error codes.

GET /v1/sun-exposure

Terrain aspect and slope at a point, plus optional illumination against a given light source direction (sun or moon). Useful for photographers scouting golden hour light and for solar/snow-melt/vegetation exposure analysis.

Request

FieldTypeRequiredDefaultDescription
latfloatyes—Latitude, −90..90.
lngfloatyes—Longitude, −180..180.
lightAzimuthDegfloatno—Light source azimuth. 0 = N, clockwise, [0, 360). Must be given together with lightAltitudeDeg, or neither.
lightAltitudeDegfloatno—Light source altitude above the horizon, −90..90. Must be given together with lightAzimuthDeg, or neither.

Providing only one of lightAzimuthDeg / lightAltitudeDeg returns 400 with incomplete_light_params. Omit both to get aspect_deg / slope_deg without illumination.

Examples

curl -H "X-API-Key: gi_live_..." \
  "https://geoinsight.dev/v1/sun-exposure?lat=45.8326&lng=6.8652&lightAzimuthDeg=100&lightAltitudeDeg=8.5"
import requests

r = requests.get(
"https://geoinsight.dev/v1/sun-exposure",
params={"lat": 45.8326, "lng": 6.8652, "lightAzimuthDeg": 100, "lightAltitudeDeg": 8.5},
headers={"X-API-Key": "gi_live_..."},
)
print(r.json()["results"][0]["illumination"])
const res = await fetch(
  "https://geoinsight.dev/v1/sun-exposure?lat=45.8326&lng=6.8652&lightAzimuthDeg=100&lightAltitudeDeg=8.5",
  { headers: { "X-API-Key": "gi_live_..." } },
);
const data = await res.json();
console.log(data.results[0].illumination);

Response

{
  "results": [{
"lat": 45.8326,
"lng": 6.8652,
"aspect_deg": 92.4,
"slope_deg": 31.7,
"illumination": 0.6409
  }],
  "dataset": "copernicus-glo-30",
  "resolution_m": 30
}
Field Type Unit Description
results array — One entry per requested point, in input order.
results[].lat number deg Latitude echoed back from the request.
results[].lng number deg Longitude echoed back from the request.
results[].aspect_deg number deg Compass direction the slope faces: 0 = north, increasing clockwise. null on flat terrain (no downhill direction) or on nodata.
results[].slope_deg number deg Steepness from horizontal; 0 = flat, 90 = vertical. null on nodata.
results[].illumination number 0–1 How directly the surface faces the given light: 0 = facing away or grazing, 1 = head-on. null when no light params were supplied, or on nodata. Local lighting only — see the note below.
dataset string — Source dataset identifier.
resolution_m integer m Ground sample distance. Aspect and slope are derived from neighbouring cells at this spacing, so they describe terrain at ~30 m scale, not individual boulders.

Aspect, slope & illumination

  • aspect_deg — the compass direction the slope faces (0 = N, clockwise). null on flat terrain (no defined downhill direction) or where elevation data is missing (nodata).
  • slope_deg — steepness of the terrain, 0 = flat. null where elevation data is missing (nodata).
  • illumination — how directly the surface faces the given light source, from 0 (facing away / grazing) to 1 (directly facing). null when lightAzimuthDeg/lightAltitudeDeg were not provided, or on nodata. illumination reflects local light hitting the surface only — it does not account for occlusion by distant terrain (a ridge blocking the sun). Combine with /v1/visibility to check whether the light source itself is above the local horizon.

Photographer's tip: golden hour

A slope with aspect_deg ≈ 90 (east-facing) catches direct light earliest, at sunrise / golden hour. A slope with aspect_deg ≈ 270 (west-facing) catches it last, at sunset / golden hour. Pair with /v1/horizon to find the exact azimuth and altitude the sun clears the local ridge.

POST /v1/sun-exposure

Aspect, slope and optional illumination for up to 100 points in a single request. Results are returned in the same order as the input points. See the field notes and golden-hour tip under GET /v1/sun-exposure above.

Request (JSON body)

FieldTypeRequiredDefaultDescription
pointsarrayyes—1–100 objects, each { "lat": …, "lng": … }.
points[].latfloatyes—Latitude, −90..90.
points[].lngfloatyes—Longitude, −180..180.
lightAzimuthDegfloatno—Light source azimuth. 0 = N, clockwise, [0, 360). Must be given together with lightAltitudeDeg, or neither. Applied to every point in the batch.
lightAltitudeDegfloatno—Light source altitude above the horizon, −90..90. Must be given together with lightAzimuthDeg, or neither. Applied to every point in the batch.

Examples

curl -H "X-API-Key: gi_live_..." -X POST "https://geoinsight.dev/v1/sun-exposure" \
  -H "Content-Type: application/json" \
  -d '{"points":[{"lat":45.8326,"lng":6.8652},{"lat":46.5197,"lng":6.6323}],"lightAzimuthDeg":100,"lightAltitudeDeg":8.5}'
import requests

r = requests.post(
"https://geoinsight.dev/v1/sun-exposure",
json={
    "points": [{"lat": 45.8326, "lng": 6.8652}, {"lat": 46.5197, "lng": 6.6323}],
    "lightAzimuthDeg": 100,
    "lightAltitudeDeg": 8.5,
},
headers={"X-API-Key": "gi_live_..."},
)
print(r.json()["results"])
const res = await fetch("https://geoinsight.dev/v1/sun-exposure", {
  method: "POST",
  headers: { "X-API-Key": "gi_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({
points: [{ lat: 45.8326, lng: 6.8652 }, { lat: 46.5197, lng: 6.6323 }],
lightAzimuthDeg: 100,
lightAltitudeDeg: 8.5,
  }),
});
console.log((await res.json()).results);

Response

{
  "results": [
{ "lat": 45.8326, "lng": 6.8652, "aspect_deg": 92.4, "slope_deg": 31.7, "illumination": 0.6409 },
{ "lat": 46.5197, "lng": 6.6323, "aspect_deg": 210.0, "slope_deg": 12.0, "illumination": 0.0743 }
  ],
  "dataset": "copernicus-glo-30",
  "resolution_m": 30
}
Field Type Unit Description
results array — One entry per input point, in the same order. Match by index.
results[].lat number deg Latitude echoed back from the request.
results[].lng number deg Longitude echoed back from the request.
results[].aspect_deg number deg Direction the slope faces: 0 = north, clockwise. null on flat terrain or nodata.
results[].slope_deg number deg Steepness from horizontal. null on nodata.
results[].illumination number 0–1 Directness of the light on the surface. null when no light params were supplied, or on nodata.
dataset string — Source dataset identifier.
resolution_m integer m Ground sample distance of the source raster.