# Solar Shadow Simulator

> Solar Shadow Simulator is a paid API for AI agents from solar.halowerk.com, paid per call via x402, $0.002/call, status unknown (last checked 2026-09-13).

Calculates sun position and shadow length for a vertical object at a given location, date, and time interval using the NOAA astronomical method, and reports whether a specified nearby point falls in shadow.

## Facts

- Endpoint: POST https://solar.halowerk.com/shadow-simulator
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/solar-shadow-simulator-e6f38cb4
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_xZ-gF-xiqL_EZw2Nd7aeP

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability solar-shadow-simulator-e6f38cb4 -d '<json body>'
```

Example prompt: For our construction site at 48.8566° N, 2.3522° E, simulate the shadow cast by a 15-meter-tall crane on June 21, checking every 30 minutes, and tell me whether a point 40 meters away at bearing 270° falls in shadow at any point during the day.

## When to prefer this

Use this endpoint when you need precise NOAA-method astronomical shadow length and position calculations for a vertical object at a known GPS coordinate and date. It is ideal for architectural planning, garden or solar panel shading assessments, and any use case requiring time-series shadow data throughout a day. Prefer this over general solar irradiance endpoints when the key question is whether a specific point will be in shadow, not how much energy is available. Note it does not model terrain slope, surrounding obstructions, or diffuse light — for complex 3D urban shadow modeling, a full ray-tracing tool would be needed.

## Known failure modes

- Invalid latitude/longitude values outside ±90/±180 range returns validation error
- Date string not in YYYY-MM-DD format causes parse error
- object_height_m below 0.01 or above 1000 returns out-of-range error
- step_minutes outside 5–60 range rejected
- obstacle_bearing_deg outside 0–360 rejected
- All shadow lengths reported as capped if sun remains very low (polar winter) or object is very tall
- Result is purely geometric — real-world shading may differ due to terrain, buildings, vegetation not modelled

## How this service works

Pure astronomy and geometry on level ground: sun position by the NOAA method, shadow length as object height divided by the tangent of the sun elevation. Refraction is only applied to sunrise and sunset. Terrain slope, surrounding buildings, vegetation and diffuse light are not modelled, so a point outside the shadow can still be shaded in reality. Times are UTC.

## Output

Returns a time series of shadow calculations at the requested step interval throughout the day (UTC). Each entry includes the UTC timestamp, sun elevation angle, sun azimuth, shadow length in meters (capped at max_shadow_length_m if very long or sun below horizon), and — when obstacle_distance_m and obstacle_bearing_deg are provided — a boolean indicating whether the specified point falls within the shadow cone given the bearing tolerance.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "lat": {
   "type": "number",
   "maximum": 90,
   "minimum": -90
  },
  "lon": {
   "type": "number",
   "maximum": 180,
   "minimum": -180
  },
  "date": {
   "type": "string",
   "description": "Day as YYYY-MM-DD."
  },
  "step_minutes": {
   "type": "integer",
   "default": 30,
   "maximum": 60,
   "minimum": 5
  },
  "object_height_m": {
   "type": "number",
   "maximum": 1000,
   "minimum": 0.01
  },
  "max_shadow_length_m": {
   "type": "number",
   "default": 500,
   "maximum": 100000,
   "minimum": 1,
   "description": "Shadow lengths above this are reported as capped."
  },
  "obstacle_distance_m": {
   "type": "number",
   "maximum": 10000,
   "minimum": 0.01,
   "description": "Distance of the point of interest from the object."
  },
  "obstacle_bearing_deg": {
   "type": "number",
   "maximum": 360,
   "minimum": 0,
   "description": "Compass bearing from the object to that point."
  },
  "bearing_tolerance_deg": {
   "type": "number",
   "default": 10,
   "maximum": 90,
   "minimum": 1
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/solar-shadow-simulator-e6f38cb4/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from solar.halowerk.com](https://www.zero.xyz/host/solar.halowerk.com/llms.txt)