Planet positions API
Give a moment; get every body's ecliptic longitude and latitude, daily speed, retrograde flag and distance, geocentric or heliocentric. From a place, the altaz route gives altitude, azimuth and compass point; the convert route turns one direction into equatorial, ecliptic or galactic coordinates.
Get a free key Try it in the playground API reference
What you get
- Sun, Moon, Mercury to Pluto in one call, geocentric or heliocentric
- Ecliptic longitude and latitude, daily speed, retrograde flag, distance in AU
- Altitude, azimuth and compass point from a place (altaz)
- Time series of longitudes, 1 hour to 1 week steps (longitude-series)
Example
curl -X POST https://astro-agent.dev/v1/astronomy/positions -H 'Content-Type: application/json' \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" -d '{"datetime":"2026-11-20T00:00:00Z"}'
A real answer to this request (excerpt). The same request always returns the same
result_sha256, which POST https://astro-agent.dev/v1/verify recomputes for free:
{
"endpoint": "astronomy/positions",
"result": {
"settings": {
"longitude_reference": "ecliptic longitude from the true equinox of date (0-360 degrees)"
},
"points": [
{
"point": "sun",
"name": "Sun",
"longitude": 237.670657,
"latitude": 0.000143,
"speed_longitude": 1.008878,
"retrograde": false,
"distance_au": 0.988211
},
{
"point": "moon",
"name": "Moon",
"longitude": 356.776302,
"latitude": 2.647516,
"speed_longitude": 13.120563,
"retrograde": false,
"distance_au": 0.002567
},
{
"point": "mercury",
"name": "Mercury",
"longitude": 218.233728,
"latitude": 2.391075,
"speed_longitude": 0.914665,
"retrograde": false,
"distance_au": 0.975353
}
]
},
"meta": {
"result_sha256": "92fb9b2a6afd0ec7f5a95ecc2e365fb93ddd6037a4122c63ab8377edd00caacc"
}
}
Routes and prices
| Route | Name | Price per call | What it returns |
|---|---|---|---|
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/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/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/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. |
The same routes are MCP tools on https://astro-agent.dev/mcp.
Limits
- Dates from 1800 to 2200; range routes take up to a year per call.
- Without a key: 1 free call on the $0.01-0.02 routes, then HTTP 402 with a pay-per-call offer (USDC, x402).
- Free key (an email, no card): 10,000 calls a month, 30 a minute, personal, research and evaluation use only. Paid plans from $19 a month by card, for commercial use: see pricing.
- Past the quota, calls answer 429 until the 1st of the month: nothing is charged beyond the plan.
Alternatives
NASA/JPL Horizons is free and is the reference we benchmark against (see the benchmark). Use it for one-off research queries; Astro Agents returns every body in one JSON call for an application.
Checked on the providers' own pages on 2026-11-20. Their terms may have changed since.
When Astro Agents fits
- One call for all bodies, in clean JSON, inside an app or an agent
- Accuracy you can check: benchmarked against Horizons, every result hashed
- MCP tools for AI agents