API reference

Astronomical data from NASA/JPL DE440, any date 1800-2200. One HTTPS POST per call, JSON in, JSON out, a SHA-256 on every result.

New here? The 60-second quickstart takes you from a key to your first result. Prefer to click? The playground runs any route from a form.

Why Astro Agents

Trust and accuracy

Breadth

For agents and developers

Access

Base URL and authentication

https://astro-agent.dev/v1/<route>, method POST, body JSON.

Send your key in the X-Credits-Token header. A free key comes with the Free plan (1,000 calls a month, up to 100 of them 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.

Routes

RoutePathPriceWhat it returns
Planetary positions for any date (ephemeris)POST /v1/astronomy/positions$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.
The sky now: positions, Moon phase, next eventsPOST /v1/astronomy/sky$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.
Rise, set and twilight times for a placePOST /v1/astronomy/rise-set$0.01Rise, transit and set of the Sun, Moon and planets for a place and local day, with civil, nautical and astronomical twilight, day length, golden hour and blue hour.
Altitude and azimuth of every body from a placePOST /v1/astronomy/altaz$0.01Where the Sun, Moon and planets are in the sky from a place at a moment: altitude, azimuth, compass point, topocentric right ascension and declination, distance, elongation, illumination and magnitude.
Observation windows for a nightPOST /v1/astronomy/visibility$0.02When 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.
Moon phase, illumination, distance and next phasesPOST /v1/astronomy/moon$0.01The Moon at a moment: phase name and angle, illuminated fraction, age, lunation number, distance and apparent size, the next new, first quarter, full and last quarter Moons, and the next perigee and apogee.
Astronomical summary of the day for a placePOST /v1/astronomy/day$0.02One call for a day at a place: sunrise, sunset, twilight, day length, golden and blue hour; the Moon's phase, illumination, rise and set; the planets observable that night; the next lunations, planetary stations and eclipse.
Equinoxes, solstices, perihelion and day length over a yearPOST /v1/astronomy/seasons$0.01The year's equinoxes and solstices and Earth's perihelion and aphelion to the second; optionally the Sun day by day: sunrise, sunset, day length, solar noon, declination and equation of time.
Julian day, sidereal time, Delta T and time scalesPOST /v1/astronomy/time$0.01One moment in every astronomical time scale: UTC, unix time, Julian day (UTC, UT1, TT, TDB), MJD, Julian centuries, Delta T, TAI-UTC, UT1-UTC, Greenwich and local mean and apparent sidereal time.
Coordinate conversion between sky framesPOST /v1/astronomy/convert$0.01Convert one direction on the sky between equatorial (J2000 and of date), ecliptic (J2000 and of date), galactic and, with a moment and a place, horizontal coordinates.
Planetary phenomena: oppositions, conjunctions, elongationsPOST /v1/astronomy/phenomena$0.10Every conjunction with the Sun (inferior / superior for Mercury and Venus), opposition, greatest elongation, conjunction between two planets, perihelion and aphelion between two dates, to the second.
Local circumstances of solar and lunar eclipsesPOST /v1/astronomy/eclipse-local$0.10For a place: every solar and lunar eclipse between two dates with its local circumstances: whether and how it is seen, contact times, magnitude, obscuration, duration and the Sun's or Moon's altitude.
Solunar periods: lunar transits, moonrise and moonsetPOST /v1/astronomy/solunar$0.01The day's solunar periods for a place: major periods centred on the Moon's upper and lower meridian transits, minor periods centred on moonrise and moonset, with the Moon's phase.
Angular separations between bodiesPOST /v1/astronomy/angles$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.
Celestial event calendar (eclipses, stations, lunations)POST /v1/astronomy/events$0.25Solar and lunar eclipses, planetary stations, lunations, separations, longitude crossings and declination events between two dates (1800-2200), to the minute.
Planetary longitude series (geocentric + heliocentric)POST /v1/astronomy/longitude-series$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.
Sky similarity search (matching skies)POST /v1/astronomy/sky-analogues$0.25The past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance.
Local time resolver (historical time zones)POST /v1/astronomy/local-time$0.01Local time + place -> exact UT, historical UTC offset, Delta T, Local Mean Time, true solar time.

By need

Astronomy API · Sunrise and sunset API · Moon phase API · Solar and lunar eclipse API · Planet positions API · Visible planets tonight API · Twilight times API · Golden hour and blue hour API · Equinox and solstice API · Delta T and time scales API

Every response

{"endpoint", "result", "meta"}: result holds the data, meta.input_sha256 and meta.result_sha256 identify the request and the result (POST /v1/verify recomputes the hash, free). Every convention (frame, equinox, perspective, tolerances) is stated in result.settings.

From JavaScript, send /v1/verify the result's raw JSON text, not JSON.stringify(data.result): JSON.parse turns 180.0 into 180, and the hash rule (sorted keys, no whitespace, floats rounded to 6 decimals) tells the two apart. Python's json keeps them apart and verifies as is.

More

Errors · CSV and bulk export · Catalog (JSON) · OpenAPI · llms.txt · MCP server: https://astro-agent.dev/mcp