Astronomical time series and celestial events API
Planetary time series and celestial events as data: geocentric and heliocentric positions, declination, longitude series and a to-the-minute event calendar, reproducible to the byte. Provable and replayable: every result is SHA-256 hashed, so the same request returns the same bytes.
For developers, researchers and astronomy, calendar, observation and data applications: the NASA/JPL DE440 ephemeris behind one HTTP call, for any date from 1800 to 2200, returned as JSON (or pandas DataFrames with the Python client), with a SHA-256 hash on every result.
Celestial event calendar
Every solar and lunar eclipse (type, magnitude), planetary station (retrograde / direct), lunation, separation between planets, longitude crossing and declination event between two dates, 1800-2200, each to the UTC minute. $0.25 per call (up to a year).
Planetary positions
Geocentric or heliocentric, ecliptic or equatorial (right ascension, declination), with speeds and retrograde flags, for any moment. $0.01 per call.
The sky now
Positions, retrograde planets, the Moon's phase and illumination, and the exact times of the next stations, lunations and separations. $0.01 per call.
Longitude time series
Planet longitudes seen from the Earth and from the Sun in one call, as a series (1 hour to 1 week steps, up to 1,000 samples) with speeds, retrograde flags and declinations, in columns ready for pandas. $0.20 per call.
Sky similarity search
The past or future dates whose planetary positions best match a reference sky, ranked by an angular distance whose formula comes with every result. $0.25 per call (up to 100 matches).
Angles between bodies
Angular separations at 0, 60, 90, 120, 180 degrees or any angle you choose, with the deviation and whether the bodies approach or recede; optionally equal and opposite declinations. $0.02 per call.
Routes and prices
| Route | What | Price | Summary |
|---|---|---|---|
POST /v1/astronomy/events | Celestial event calendar (eclipses, stations, lunations) | $0.25 | Solar and lunar eclipses, planetary stations, lunations, separations, longitude crossings and declination events between two dates (1800-2200), to the minute. |
POST /v1/astronomy/positions | Planetary positions for any date (ephemeris) | $0.01 | Ecliptic longitude and latitude, daily speed, retrograde flag and distance of the Sun, the Moon, Mercury..Pluto and the lunar nodes, for any moment 1800-2200. |
POST /v1/astronomy/sky | The sky now: positions, Moon phase, next events | $0.01 | The sky at a moment: planetary positions, which planets are retrograde, the Moon's phase and illumination, and the exact times of the next stations, lunations and separations. |
POST /v1/astronomy/longitude-series | Planetary longitude series (geocentric + heliocentric) | $0.20 | Ecliptic longitudes of the planets at one moment or as a time series (1 hour to 1 week steps), geocentric and heliocentric, with optional angle offsets, multi-body averages and declinations. |
POST /v1/astronomy/sky-analogues | Sky similarity search (matching skies) | $0.25 | The past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance. |
POST /v1/astronomy/angles | Angular separations between bodies | $0.02 | Pairs of bodies whose ecliptic separation is within a tolerance of 0, 60, 90, 120 or 180 degrees (or any angle you choose), with the deviation; optionally equal and opposite declinations. |
Try it
curl -X POST https://astro-agent.dev/v1/astronomy/events -H 'Content-Type: application/json' \
-d '{"start":"2024-01-01","end":"2024-12-31","include":["eclipse","station"]}'
curl -X POST https://astro-agent.dev/v1/astronomy/positions -H 'Content-Type: application/json' \
-d '{"datetime":"2026-11-17T12:00:00Z","options":{"coordinates":"equatorial"}}'
Without a key, the first call on a $0.01-0.02 route is free; then get a free key (email
only, no card) and send it in X-Credits-Token.
2024 eclipses and stations (real output)
| Exact UTC | Event | Detail |
|---|---|---|
| 2024-01-02T03:08Z | Mercury stations direct | 262.18 deg |
| 2024-01-27T05:50Z | Uranus stations direct | 49.09 deg |
| 2024-03-25T07:13Z | lunar eclipse (penumbral) | magnitude -0.132051 |
| 2024-04-01T22:14Z | Mercury stations retrograde | 27.22 deg |
| 2024-04-08T18:17Z | solar eclipse (total) | magnitude None |
| 2024-04-25T12:55Z | Mercury stations direct | 15.98 deg |
| 2024-05-02T11:31Z | Pluto stations retrograde | 302.10 deg |
| 2024-06-29T17:25Z | Saturn stations retrograde | 349.43 deg |
| 2024-07-02T03:32Z | Neptune stations retrograde | 359.93 deg |
| 2024-08-05T04:56Z | Mercury stations retrograde | 154.10 deg |
| 2024-08-28T21:15Z | Mercury stations direct | 141.41 deg |
| 2024-09-01T12:02Z | Uranus stations retrograde | 57.26 deg |
result_sha256 17b7391016e184c3eeddf4649471701d736dd6fcb296b94c0a22e9bd976c4433
Python client: DataFrames
pip install "astro-agents @ git+https://github.com/aidatatools-dev/astro-agents-clients#subdirectory=python"
from astro_agents import Client
client = Client() # your key in ASTRO_AGENTS_KEY
events = client.export("astronomy/events", "2020-01-01", "2024-12-31", include=["eclipse", "station"])
Why the numbers can be trusted
- Positions from NASA/JPL DE440 (NASA/JPL), 1800-01-01..2200-01-01, via Skyfield: geocentric apparent, true equinox of date, IAU 2006/2000A.
- Historical time zones resolved for you (IANA tz database, DST of the era, Local Mean Time); ambiguous or non-existent local times are flagged, never guessed.
- Deterministic, no LLM: same input -> same bytes. Every response carries meta.input_sha256 and meta.result_sha256 (also as X-Input-SHA256 / X-Result-SHA256 headers); POST /v1/verify recomputes one.
- Every convention is in the response: frame, equinox, perspective (geocentric or heliocentric), coordinates (ecliptic or equatorial), refraction, horizon and tolerances.
- Accuracy vs NASA/JPL Horizons (12,400 comparisons, 1800-2199): positions within 0.024" (ICRF); ecliptic longitudes as served within 0.062" over 1962-2026. Method and every number: https://astro-agent.dev/benchmark.md
Accuracy benchmark against NASA/JPL Horizons · How this compares with Swiss Ephemeris or computing it yourself · Pricing
FAQ
Is this a prediction or a forecast?
No. Astro Agents returns astronomical data: positions, angles, and the exact times of events. The only score in the API is geometric and comes with its formula (the angular distance between two skies in /v1/astronomy/sky-analogues).
Which ephemeris is used, and how accurate is it?
NASA/JPL DE440 through Skyfield. Compared with NASA/JPL Horizons on 12,400 values from 1800 to 2200, positions agree to 0.024 arcseconds at worst (the method and every compared value are published).
What date range and time resolution do I get?
Any date from 1800 to 2200. Events each to the UTC minute (eclipses, stations, lunations, separations, longitude crossings, declination events). Longitude series at 1 hour to 1 week steps, up to 1,000 samples per call; the Python client pages longer ranges for you.
How do I prove which numbers I used?
Every response carries meta.input_sha256 and meta.result_sha256. The same request returns the same bytes, and POST /v1/verify (free) recomputes the hash. The hash proves the result is the one the API returned and can be reproduced; its accuracy comes from DE440 and is measured by the benchmark.
Do I need an account or an API key?
A free key needs only an email (no card). Every visitor also gets 1 free call on the $0.01-0.02 routes without a key. Paid plans are by card; software agents can also pay per call.