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

RouteWhatPriceSummary
POST /v1/astronomy/eventsCelestial event calendar (eclipses, stations, lunations)$0.25Solar and lunar eclipses, planetary stations, lunations, separations, longitude crossings and declination events between two dates (1800-2200), to the minute.
POST /v1/astronomy/positionsPlanetary positions for any date (ephemeris)$0.01Ecliptic 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/skyThe sky now: positions, Moon phase, next events$0.01The 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-seriesPlanetary longitude series (geocentric + heliocentric)$0.20Ecliptic 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-analoguesSky similarity search (matching skies)$0.25The past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance.
POST /v1/astronomy/anglesAngular separations between bodies$0.02Pairs 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 UTCEventDetail
2024-01-02T03:08ZMercury stations direct262.18 deg
2024-01-27T05:50ZUranus stations direct49.09 deg
2024-03-25T07:13Zlunar eclipse (penumbral)magnitude -0.132051
2024-04-01T22:14ZMercury stations retrograde27.22 deg
2024-04-08T18:17Zsolar eclipse (total)magnitude None
2024-04-25T12:55ZMercury stations direct15.98 deg
2024-05-02T11:31ZPluto stations retrograde302.10 deg
2024-06-29T17:25ZSaturn stations retrograde349.43 deg
2024-07-02T03:32ZNeptune stations retrograde359.93 deg
2024-08-05T04:56ZMercury stations retrograde154.10 deg
2024-08-28T21:15ZMercury stations direct141.41 deg
2024-09-01T12:02ZUranus stations retrograde57.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

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.

Astronomical data only: no predictions, never a signal or forecast.