Astro Agents
API dữ liệu thiên văn cấp độ nghiên cứu từ NASA/JPL DE440: thời điểm mọc/lặn và chạng vạng, Mặt Trăng, nhật thực/nguyệt thực, vị trí các hành tinh và sự kiện thiên thể cho mọi ngày từ năm 1800 đến 2200. Không dùng LLM, mọi kết quả đều có thể xác minh bằng SHA-256. Nhận khóa miễn phí bằng email.
Máy chủ MCP được lưu trữ
npx add-mcp 'https://astro-agent.dev/mcp'Cài vào Claude Code, Codex, Cursor và nhiều công cụ khác
Tài liệu
Research-grade astronomical data & computation API — NASA/JPL DE440 ephemerides for any date, past, present or future, reproducible and SHA-256 verifiable.
Plans are paid by card. Free needs only an email. Details and what each plan includes: pricing.
Try it
Sunrise, sunset and twilight in New York on 21 December 2026. Paste the request in a terminal: no key needed for your first call.
curl -X POST https://astro-agent.dev/v1/astronomy/rise-set \
-H 'Content-Type: application/json' \
-d '{"date": "2026-12-21", "latitude": 40.7128, "longitude": -74.006}'
{
"endpoint": "astronomy/rise-set",
"result": {
"subject": {
"timezone": "America/New_York",
"date": "2026-12-21"
},
"sun": {
"sunrise": {
"utc": "2026-12-21T12:16:35Z",
"local": "2026-12-21T07:16:35-05:00",
"timestamp": 1797855395,
"azimuth": 120.82
},
"solar_noon": {
"utc": "2026-12-21T16:54:11Z",
"local": "2026-12-21T11:54:11-05:00",
"timestamp": 1797872051,
"altitude": 25.85
},
"sunset": {
"utc": "2026-12-21T21:31:48Z",
"local": "2026-12-21T16:31:48-05:00",
"timestamp": 1797888708,
"azimuth": 239.18
},
"civil_dusk": {
"utc": "2026-12-21T22:02:48Z",
"local": "2026-12-21T17:02:48-05:00",
"timestamp": 1797890568
},
"day_length_minutes": 555.2
}
},
"meta": {
"ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
"result_sha256": "9952407e5fd4554cec0fbd237188eb1ef76e1bfaec40c3464844d6c5086fc414"
}
}
Right: an excerpt of the real response to this request (times to the second, in UTC and local time; the full response also lists the Moon and the planets). The same request always returns the same result_sha256.
What you can build
A photography app: when is the light good tonight?
San Francisco, 21 June 2026 · POST /v1/astronomy/rise-set
Sunset 20:35, evening golden hour 19:55-20:54, civil dusk 21:06 (local time, America/Los_Angeles).
Request {"date": "2026-06-21", "latitude": 37.7749, "longitude": -122.4194}
result_sha256 c8d49c7a3abf5cc2...
An astronomy club: which planets can we observe tonight?
London, night of 12 December 2026 · POST /v1/astronomy/visibility
Venus highest at 07:16 (24 deg); Mars highest at 05:08 (50 deg); Jupiter highest at 04:32 (52 deg); Saturn highest at 19:08 (39 deg) (local time).
Request {"date": "2026-12-12", "latitude": 51.5074, "longitude": -0.1278}
result_sha256 8fc6375d699589d5...
An eclipse planner: what will we see from here?
Luxor, Egypt, August 2027 · POST /v1/astronomy/eclipse-local
The total solar eclipse of 2 August is total here: magnitude 1.035, maximum at 13:05 local time with the Sun 81.8 deg above the horizon, 6 min 20 s of totality.
Request {"start": "2027-08-01", "end": "2027-08-31", "latitude": 25.6872, "longitude": 32.6396}
result_sha256 4025fd5c69649f1e...
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.
Astro Agents — a research-grade, verifiable astronomical data and computation API for developers, researchers and astronomy, calendar, observation and data applications. From the NASA/JPL DE440 ephemeris: sunrise, sunset and twilight, altitude and azimuth, observation windows, the Moon's phase and distance, the day's sky for a place, planetary positions (geocentric & heliocentric, ecliptic & equatorial), angular separations, longitude time series, eclipses with local circumstances, planetary phenomena, seasons, time scales and coordinate conversion, and a to-the-minute celestial event calendar (solar and lunar eclipses, stations, lunations), 1800-2200. Any date — past, present or future — reproducible: no LLM, historical time zones resolved for you, every result SHA-256 hashed and checkable, accuracy benchmarked against NASA/JPL Horizons. A free key with an email, plans by card, or, for software agents, prepaid credits or pay per call in USDC (x402, MPP). Data only — no predictions, never a signal or forecast.
Astronomy endpoints
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/rise-set | Rise, set and twilight times for a place | $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. |
POST /v1/astronomy/altaz | Altitude and azimuth of every body from a place | $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. |
POST /v1/astronomy/visibility | Observation windows for a night | $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. |
POST /v1/astronomy/moon | Moon phase, illumination, distance and next phases | $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. |
POST /v1/astronomy/day | Astronomical summary of the day for a place | $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. |
POST /v1/astronomy/seasons | Equinoxes, solstices, perihelion and day length over a year | $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. |
POST /v1/astronomy/time | Julian day, sidereal time, Delta T and time scales | $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. |
POST /v1/astronomy/convert | Coordinate conversion between sky frames | $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. |
POST /v1/astronomy/phenomena | Planetary phenomena: oppositions, conjunctions, elongations | $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. |
POST /v1/astronomy/eclipse-local | Local circumstances of solar and lunar eclipses | $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. |
POST /v1/astronomy/solunar | Solunar periods: lunar transits, moonrise and moonset | $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. |
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. |
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/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/local-time | Local time resolver (historical time zones) | $0.01 | Local time + place -> exact UT, historical UTC offset, Delta T, Local Mean Time, true solar time. |
How to pay
- Monthly plan, by card: Free ($0: an email, no card), then Indie $19, Pro $79, Scale $299 a month. One API key and a monthly call quota. No per-call charge and no overage: past the quota, calls answer 429 until the quota resets on the 1st or you upgrade.
- Prepaid credits, in USDC: Buy a pack once ($10 to $1,000) and use its token: each call spends its listed price from the balance. Credits never expire.
- Pay per call, no account: Software agents can pay each call in USDC, with no key and no sign-up (through the x402 or MPP payment protocols, on Base or Solana).
Every visitor also gets 1 free call on the $0.01-0.02 routes, without a key. Pricing.
New in 1.10.0 (2026-11-19)
- Rise, set and twilight (
POST /v1/astronomy/rise-set): Rise, transit and set of the Sun, the Moon and the planets for a place and local day, with civil, nautical and astronomical twilight, golden and blue hour. - The day's sky for a place (
POST /v1/astronomy/day): One call: the Sun, the Moon's phase and moonrise, the planets observable that night and the next eclipse, in local time. - The Moon in detail (
POST /v1/astronomy/moon): Phase, illumination, age, distance, apparent size, the next phases, perigee and apogee. - Eclipses from a place (
POST /v1/astronomy/eclipse-local): Local circumstances of solar and lunar eclipses: contacts, magnitude, obscuration, duration and the Sun's or Moon's altitude. - Planetary phenomena (
POST /v1/astronomy/phenomena): Oppositions, conjunctions, greatest elongations, perihelia and aphelia between two dates. - Celestial event calendar (
POST /v1/astronomy/events): Solar and lunar eclipses, stations, lunations and separations between two dates, 1800-2200, each to the UTC minute with a unix timestamp and a stable key. - Accuracy verified against NASA/JPL Horizons (
GET /v1/benchmark): 12,400 comparisons, 1800-2199: positions 0.0005" mean / 0.024" max (ICRF); longitude as served 0.048" mean over 1962-2026. Details
Why trust the numbers
- 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
Python client
The official client returns pandas DataFrames: pip install "astro-agents @ git+https://github.com/aidatatools-dev/astro-agents-clients#subdirectory=python" (docs, examples).
from astro_agents import Client
client = Client() # ASTRO_CREDITS_TOKEN, or 1 free call on the $0.01-0.02 routes
events = client.events("2020-01-01", "2024-12-31", include=["eclipse", "station"])
Prepaid credits: packs
For software agents: pay once in USDC, then spend call by call with a token. 1 credit = $1 (USDC); credits never expire and pay for every paid route. POST /v1/credits/topup {"pack": "probe"}.
| Pack | You pay | Credits | Bonus | Worth |
|---|---|---|---|---|
| Probe | $10.00 | 10 | +0% | 50 longitude-series calls, or 40 event-calendar years, or 1000 planetary-position calls |
| Survey | $50.00 | 60 | +20% | 300 longitude-series calls, or 240 event-calendar years, or 6000 planetary-position calls |
| Observatory | $200.00 | 260 | +30% | 1300 longitude-series calls, or 1040 event-calendar years, or 26000 planetary-position calls |
| Autopilot | $1000.00 | 1400 | +40% | 7000 longitude-series calls, or 5600 event-calendar years, or 140000 planetary-position calls |
Data only: no predictions, never a signal or forecast.
For agents
- /v1/catalog - free, live prices, schemas, examples
- Python client -
pip install "astro-agents @ git+https://github.com/aidatatools-dev/astro-agents-clients#subdirectory=python" - llms.txt / llms-full.txt / openapi.json
- MCP:
https://astro-agent.dev/mcp- A2A: agent card - x402 discovery - Accuracy benchmark vs NASA/JPL Horizons - /v1/benchmark