Docs › Observation windows for a night

Observation windows for a night

When each planet and the Moon can be observed from a place during a night: windows above a minimum altitude while the sky is dark, with the best time, altitude, azimuth and magnitude.

POST https://astro-agent.dev/v1/astronomy/visibility · $0.02 per call · MCP tool observation_windows · Try it in the playground

For observation planning: over the night that starts on 'date' (local noon to noon), the intervals when each body stands at least min_altitude_deg above the horizon while the Sun is at or below sun_altitude_max_deg (default -6: after civil dusk), each with start, end, duration and the best moment (highest altitude) with its azimuth and visual magnitude; plus the dark interval itself.

Authentication

Send your key in the X-Credits-Token header. A free key comes with the Free plan (10,000 calls a month on the core routes, 100 a month on the premium data routes). Without a key, each client gets 1 free call on the $0.01-0.02 routes; past it the API answers 402 with an x402 / MPP pay-per-call offer.

Parameters

ParameterTypeRequiredDefaultDescription
datestringyesThe evening that starts the observing night, YYYY-MM-DD: the night runs from local noon on that date to local noon the next day.
latitudenumberyesDecimal degrees, north positive.
longitudenumberyesDecimal degrees, east positive.
elevation_mnumber0Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled).
timezonestringIANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules).
bodiesarray of string (moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto)Bodies to plan. Default: the Moon and Mercury..Neptune.
optionsobjectWhat counts as observable.
options.min_altitude_degnumber10Lowest useful altitude of the body above the horizon, degrees.
options.sun_altitude_max_degnumber-6The sky counts as dark when the Sun is at or below this altitude: -6 civil, -12 nautical, -18 astronomical.

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/visibility \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-06-21", "latitude": 48.8566, "longitude": 2.3522}'

Python

import os
import requests

body = {'date': '2026-06-21', 'latitude': 48.8566, 'longitude': 2.3522}
r = requests.post("https://astro-agent.dev/v1/astronomy/visibility", json=body,
                  headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()

for b in data["result"]["bodies"]:
    for w in b["windows"]:
        print(f'{b["body"]:<8} {w["start"]["local"][11:16]}-{w["end"]["local"][11:16]}  '
              f'best {w["best"]["local"][11:16]} at {w["best"]["altitude"]} deg')
print("result_sha256:", data["meta"]["result_sha256"])

JavaScript (Node 18+)

// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"date": "2026-06-21", "latitude": 48.8566, "longitude": 2.3522};
const res = await fetch("https://astro-agent.dev/v1/astronomy/visibility", {
  method: "POST",
  headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();

for (const b of data.result.bodies)
  for (const w of b.windows)
    console.log(b.body.padEnd(8), w.start.local.slice(11, 16) + "-" + w.end.local.slice(11, 16),
                "best", w.best.local.slice(11, 16), "at", w.best.altitude, "deg");
console.log("result_sha256:", data.meta.result_sha256);

Example response

A real response to the request above (lists shortened to 3 items). The same request always returns this result_sha256:

1798b51878fffe13c0bc76737c61c4c0b80b678f4d22da95e1f54af0c056a0bc

{
  "endpoint": "astronomy/visibility",
  "result": {
    "subject": {
      "location": {
        "latitude": 48.8566,
        "longitude": 2.3522,
        "elevation_m": 0.0
      },
      "timezone": "Europe/Paris",
      "timezone_source": "resolved_from_coordinates",
      "date": "2026-06-21",
      "window_utc": {
        "start": "2026-06-20T22:00:00Z",
        "end": "2026-06-21T22:00:00Z"
      },
      "night_window_utc": {
        "start": "2026-06-21T10:00:00Z",
        "end": "2026-06-22T10:00:00Z"
      }
    },
    "settings": {
      "bodies": [
        "moon",
        "mercury",
        "venus"
      ],
      "min_altitude_deg": 10.0,
      "sun_altitude_max_deg": -6.0,
      "sampling_minutes": 2,
      "conventions": {
        "night": "the observing night of 'date': local noon to the next local noon",
        "window": "the body's geometric (airless) altitude >= min_altitude_deg while the Sun's is <= sun_altitude_max_deg (default -6: the end of civil twilight)",
        "edges": "found on a 2-minute grid and interpolated (about a minute)",
        "best": "the sample of highest altitude in the window, with azimuth and magnitude",
        "magnitude": "visual magnitude of the planets (Mallama & Hilton 2018, Skyfield); none for the Sun, Moon, Pluto"
      }
    },
    "dark": [
      {
        "start": {
          "utc": "2026-06-21T20:40:32Z",
          "local": "2026-06-21T22:40:32+02:00",
          "timestamp": 1782074432
        },
        "end": {
          "utc": "2026-06-22T03:04:31Z",
          "local": "2026-06-22T05:04:31+02:00",
          "timestamp": 1782097471
        }
      }
    ],
    "bodies": [
      {
        "body": "moon",
        "visible": true,
        "windows": [
          {
            "start": {
              "utc": "2026-06-21T20:40:32Z",
              "local": "2026-06-21T22:40:32+02:00",
              "timestamp": 1782074432
            },
            "end": {
              "utc": "2026-06-21T22:29:39Z",
              "local": "2026-06-22T00:29:39+02:00",
              "timestamp": 1782080979
            },
            "duration_minutes": 109.1,
            "best": {
              "utc": "2026-06-21T20:42:00Z",
              "local": "2026-06-21T22:42:00+02:00",
              "timestamp": 1782074520,
              "altitude": 25.58,
              "azimuth": 230.78,
              "magnitude": null
            }
          }
        ],
        "total_minutes": 109.1,
        "max_altitude": 25.58
      },
      {
        "body": "mercury",
        "visible": false,
        "windows": [],
        "total_minutes": 0,
        "max_altitude": null
      },
      {
        "body": "venus",
        "visible": true,
        "windows": [
          {
            "start": {
              "utc": "2026-06-21T20:40:32Z",
              "local": "2026-06-21T22:40:32+02:00",
              "timestamp": 1782074432
            },
            "end": {
              "utc": "2026-06-21T21:11:09Z",
              "local": "2026-06-21T23:11:09+02:00",
              "timestamp": 1782076269
            },
            "duration_minutes": 30.6,
            "best": {
              "utc": "2026-06-21T20:42:00Z",
              "local": "2026-06-21T22:42:00+02:00",
              "timestamp": 1782074520,
              "altitude": 14.61,
              "azimuth": 283.38,
              "magnitude": -4.01
            }
          }
        ],
        "total_minutes": 30.6,
        "max_altitude": 14.61
      }
    ]
  },
  "meta": {
    "engine": "astro-agents/1.9.0",
    "ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
    "astronomy_library": "skyfield/1.55",
    "frame": "geocentric apparent positions, true ecliptic and equinox of date (IAU 2006/2000A)",
    "deterministic": true,
    "llm_used": false,
    "input_sha256": "b1de560e2916e311e1761d541518abca2ebfc7cf3b18ea69c45c26f6f53a9f4c",
    "result_sha256": "1798b51878fffe13c0bc76737c61c4c0b80b678f4d22da95e1f54af0c056a0bc",
    "reproducibility": "result_sha256 = SHA-256 of the result serialized as JSON with sorted keys, no whitespace, UTF-8, floats rounded to 6 decimals. Same input + same engine version => same hash."
  }
}

Response fields

FieldTypeDescription
result.subjectobjectThe place, its time zone, the date and the night's window in UTC (local noon to noon).
result.settingsobjectThe bodies, min_altitude_deg, sun_altitude_max_deg, the sampling step and every convention.
result.darkarrayThe intervals when the Sun is at or below sun_altitude_max_deg: [{start, end}].
result.bodiesarrayOne row per body: visible, total_minutes, max_altitude and windows [{start, end, duration_minutes, best: {utc, local, timestamp, altitude, azimuth, magnitude}}].
endpointstringThe route that computed it.
meta.input_sha256stringSHA-256 of the canonical request.
meta.result_sha256stringSHA-256 of the canonical result: POST /v1/verify recomputes it.
meta.engine_version / meta.ephemerisstringEngine release and ephemeris (NASA/JPL DE440).

CSV

Add ?format=csv to get the table of the result as CSV (gzip when your client sends Accept-Encoding: gzip): POST https://astro-agent.dev/v1/astronomy/visibility?format=csv. Same price and quota as JSON; the X-Result-SHA256 header is the hash of the JSON result the CSV is a view of. Long ranges in one file: bulk export.

Errors

400 for an invalid input (never charged), 401 / 403 for a key problem, 402 to pay, 429 for a quota or rate limit: see the error reference.