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.

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 (10,000 calls a month on the core routes, 100 a month 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/western/positions$0.01Planetary positions for any date and time (ephemeris): tropical or sidereal longitude, latitude, speed and retrograde flag of the Sun, Moon, Mercury..Pluto, nodes and Lilith.
Sky today: retrogrades, Moon phase, next eventsPOST /v1/western/sky$0.01The sky today (no location needed): planet positions, retrogrades and Moon phase now, plus the exact UTC times of the next ingresses, stations (Mercury retrograde), new and full moons and aspects.
Angles between bodies (aspects, parallels)POST /v1/western/aspects$0.02Aspects (with orb, exactness, applying/separating) for a moment, or for any longitudes you supply.
Celestial event calendar (eclipses, stations, ingresses)POST /v1/finance/events$0.25Eclipse and Mercury retrograde calendar: every solar and lunar eclipse, station (retrograde/direct), ingress, new and full moon, aspect, parallel and out-of-bounds between two dates (1800-2200), to the minute.
Planetary longitude series (geocentric + heliocentric)POST /v1/finance/planetary-lines$0.20Planetary longitudes (geocentric and heliocentric) at a moment or as a longitude time series at chosen intervals, with angular offsets and multi-body averages.
Sky similarity search (matching skies)POST /v1/finance/analogues$0.25Find 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/time/resolve$0.01Local time + place -> exact UT, historical UTC offset, Delta T, Local Mean Time, true solar time.

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, orbs) 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 · Catalog (JSON) · OpenAPI · llms.txt · MCP server: https://astro-agent.dev/mcp