Docs › Coordinate conversion between sky frames
Coordinate conversion between sky frames
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 https://astro-agent.dev/v1/astronomy/convert · $0.01 per call · MCP tool convert_coordinates
· Try it in the playground
For catalogues, planetarium and telescope software: give a direction in one frame and get it in all the others: equatorial J2000 (ICRS) and of date, ecliptic J2000 and of date, galactic, and horizontal (altitude, azimuth) when a datetime and a place are given. Geometric frame rotations of a direction (no aberration or refraction is added: use astronomy/altaz for where a body appears).
Authentication
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.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
frame | string: equatorial_j2000 | equatorial_of_date | ecliptic_j2000 | ecliptic_of_date | galactic | horizontal | yes | | The frame of the input coordinates. |
coordinates | object | yes | | The direction, with the two fields of its frame. |
coordinates.ra_hours | number | | Equatorial frames: right ascension, hours 0-24. | |
coordinates.dec | number | | Equatorial frames: declination, degrees. | |
coordinates.longitude | number | | Ecliptic and galactic frames: longitude, degrees 0-360. | |
coordinates.latitude | number | | Ecliptic and galactic frames: latitude, degrees. | |
coordinates.altitude | number | | Horizontal frame: altitude, degrees. | |
coordinates.azimuth | number | | Horizontal frame: azimuth from north, degrees 0-360. | |
datetime | string | | Needed for the of-date and horizontal frames (UTC, offset, or local time with latitude/longitude). | |
latitude | number | | Observer latitude, for the horizontal frame. | |
longitude | number | | Observer longitude, for the horizontal frame. |
Example request
curl
curl -s https://astro-agent.dev/v1/astronomy/convert \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
-H "Content-Type: application/json" \
-d '{"frame": "equatorial_j2000", "coordinates": {"ra_hours": 6.75247703, "dec": -16.71611582}, "datetime": "2026-06-21T21:00:00Z", "latitude": 48.8566, "longitude": 2.3522}'Python
import os
import requests
body = {'frame': 'equatorial_j2000',
'coordinates': {'ra_hours': 6.75247703, 'dec': -16.71611582},
'datetime': '2026-06-21T21:00:00Z',
'latitude': 48.8566,
'longitude': 2.3522}
r = requests.post("https://astro-agent.dev/v1/astronomy/convert", json=body,
headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()
for name, coords in data["result"]["frames"].items():
print(f"{name:<19}", coords)
print("result_sha256:", data["meta"]["result_sha256"])
JavaScript (Node 18+)
// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"frame": "equatorial_j2000", "coordinates": {"ra_hours": 6.75247703, "dec": -16.71611582}, "datetime": "2026-06-21T21:00:00Z", "latitude": 48.8566, "longitude": 2.3522};
const res = await fetch("https://astro-agent.dev/v1/astronomy/convert", {
method: "POST",
headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();
for (const [name, coords] of Object.entries(data.result.frames))
console.log(name.padEnd(19), JSON.stringify(coords));
console.log("result_sha256:", data.meta.result_sha256);
Example response
A real response to the request above (lists shortened to 3 items). The same request always returns
this result_sha256:
72a9aa9741c5e5d10418ef3fe913671677a58227af30839b692d1a0bf81622f5
{
"endpoint": "astronomy/convert",
"result": {
"subject": {
"frame": "equatorial_j2000",
"coordinates": {
"ra_hours": 6.752477,
"dec": -16.716116
},
"time": {
"local_input": "2026-06-21T21:00:00Z",
"time_basis": "civil",
"timezone": null,
"timezone_source": "offset_in_datetime",
"utc_offset": "+00:00",
"is_dst": null,
"utc": "2026-06-21T21:00:00Z",
"julian_day_ut": 2461213.375,
"julian_day_tt": 2461213.375801,
"delta_t_seconds": 69.142,
"time_known": true,
"local_mean_time": "2026-06-21T21:09:24",
"true_solar_time": "2026-06-21T21:07:30",
"equation_of_time_minutes": -1.8991
}
},
"settings": {
"conventions": {
"rotation": "geometric frame rotations of one direction: no aberration, light time, nutation of the input or refraction are added; use astronomy/altaz for where a body appears",
"equatorial_j2000": "ICRS (J2000 mean equator and equinox to 0.02 arcsec)",
"of_date": "true equator / true ecliptic and equinox of the given moment (IAU 2006/2000A)",
"galactic": "IAU 1958 galactic system as defined in Skyfield (galactic_frame)",
"horizontal": "altitude above the geometric horizon, azimuth from true north clockwise"
}
},
"frames": {
"equatorial_j2000": {
"ra_hours": 6.752477,
"dec": -16.716116
},
"ecliptic_j2000": {
"longitude": 104.081665,
"latitude": -39.605248
},
"galactic": {
"longitude": 227.230283,
"latitude": -8.890284
},
"equatorial_of_date": {
"ra_hours": 6.7723,
"dec": -16.743409
},
"ecliptic_of_date": {
"longitude": 104.45267,
"latitude": -39.601976
},
"horizontal": {
"altitude": -35.862897,
"azimuth": 286.685525
}
}
},
"meta": {
"engine": "astro-agents/1.9.0",
"ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
"astronomy_library": "skyfield/1.55",
"frame": "geocentric apparent positions, true ecliptic and equinox of date (IAU 2006/2000A)",
"deterministic": true,
"llm_used": false,
"input_sha256": "128aa2f25abb5fa86c9c2a53135026a9f508366f223cc7392612251da04ec1e8",
"result_sha256": "72a9aa9741c5e5d10418ef3fe913671677a58227af30839b692d1a0bf81622f5",
"reproducibility": "result_sha256 = SHA-256 of the result serialized as JSON with sorted keys, no whitespace, UTF-8, floats rounded to 6 decimals. Same input + same engine version => same hash."
}
}
Response fields
| Field | Type | Description |
|---|---|---|
result.subject | object | The input frame and coordinates, and the resolved moment when given. |
result.settings | object | Every convention: the frames and what the rotation does not include. |
result.frames | object | equatorial_j2000 {ra_hours, dec}, ecliptic_j2000 and galactic {longitude, latitude}; with a moment, equatorial_of_date and ecliptic_of_date; with a moment and a place, horizontal {altitude, azimuth}. |
endpoint | string | The route that computed it. |
meta.input_sha256 | string | SHA-256 of the canonical request. |
meta.result_sha256 | string | SHA-256 of the canonical result: POST /v1/verify recomputes it. |
meta.engine_version / meta.ephemeris | string | Engine release and ephemeris (NASA/JPL DE440). |
Errors
400 for an invalid input (never charged), 401 / 403 for a key problem, 402 to pay, 429 for a quota or rate limit: see the error reference.