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
- NASA/JPL DE440: the reference planetary ephemeris, read through Skyfield (IAU 2006/2000A).
- Benchmarked against NASA/JPL Horizons: method and every value published at /benchmark.md.
- Deterministic, no LLM: computed, never generated: zero hallucination, the same request returns the same bytes.
- SHA-256 on every result: meta.input_sha256 and meta.result_sha256; POST /v1/verify (free) recomputes them, so a result can be cached, cited and replayed.
- The hard parts done for you: the time zone and daylight saving of any era, found from the place, and the astronomical corrections (Delta T, sidereal time, refraction) applied and stated in every result.
Breadth
- 20+ routes: positions, rise/set and twilight, altitude-azimuth, observation planning, Moon, seasons, solunar periods, eclipses (global and local circumstances), planetary phenomena, event calendar, longitude series, sky analogues, coordinate and time-scale conversion, the day's sky in one call.
- Any date from 1800 to 2200: past, present or future, events to the minute.
For agents and developers
- For AI agents: connect Claude, Cursor or any agent in one line, nothing to install (an MCP server at /mcp; an A2A agent card too).
- REST and MCP: the same routes, prices and hashes on both.
- Python SDK: pandas DataFrames (MIT).
- Playground and per-route docs: parameters, response fields, real examples, curl, Python and Node.
- CSV and bulk export: ?format=csv on tabular routes; POST /v1/export for long ranges as one gzip CSV.
Access
- Free key: an email, no card: 1,000 calls a month, up to 100 of them on the premium data routes; plus 1 free call per visitor without a key.
- Monthly plan by card: Indie, Pro or Scale, cancel any time from the customer portal.
- Prepaid credits or pay per call: for software agents: credit packs in USDC that never expire, or pay each call in USDC with no account (x402 or MPP).
- Clean licensing: Skyfield and jplephem (MIT) over public-domain JPL data: no AGPL ephemeris, no licence obligation on your code.
- Data only: no predictions, never a signal or forecast.
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
| Route | Path | Price | What it returns |
|---|---|---|---|
| Planetary positions for any date (ephemeris) | POST /v1/astronomy/positions | $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. |
| The sky now: positions, Moon phase, next events | POST /v1/astronomy/sky | $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. |
| Rise, set and twilight times for a place | POST /v1/astronomy/rise-set | $0.01 | Rise, 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 place | POST /v1/astronomy/altaz | $0.01 | Where 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 night | POST /v1/astronomy/visibility | $0.02 | 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. |
| Moon phase, illumination, distance and next phases | POST /v1/astronomy/moon | $0.01 | The 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 place | POST /v1/astronomy/day | $0.02 | One 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 year | POST /v1/astronomy/seasons | $0.01 | The 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 scales | POST /v1/astronomy/time | $0.01 | One 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 frames | POST /v1/astronomy/convert | $0.01 | Convert 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, elongations | POST /v1/astronomy/phenomena | $0.10 | Every 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 eclipses | POST /v1/astronomy/eclipse-local | $0.10 | For 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 moonset | POST /v1/astronomy/solunar | $0.01 | The 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 bodies | POST /v1/astronomy/angles | $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. |
| Celestial event calendar (eclipses, stations, lunations) | POST /v1/astronomy/events | $0.25 | Solar 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.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. |
| Sky similarity search (matching skies) | POST /v1/astronomy/sky-analogues | $0.25 | The 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.01 | Local 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