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

ParameterTypeRequiredDefaultDescription
framestring: equatorial_j2000 | equatorial_of_date | ecliptic_j2000 | ecliptic_of_date | galactic | horizontalyesThe frame of the input coordinates.
coordinatesobjectyesThe direction, with the two fields of its frame.
coordinates.ra_hoursnumberEquatorial frames: right ascension, hours 0-24.
coordinates.decnumberEquatorial frames: declination, degrees.
coordinates.longitudenumberEcliptic and galactic frames: longitude, degrees 0-360.
coordinates.latitudenumberEcliptic and galactic frames: latitude, degrees.
coordinates.altitudenumberHorizontal frame: altitude, degrees.
coordinates.azimuthnumberHorizontal frame: azimuth from north, degrees 0-360.
datetimestringNeeded for the of-date and horizontal frames (UTC, offset, or local time with latitude/longitude).
latitudenumberObserver latitude, for the horizontal frame.
longitudenumberObserver 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

FieldTypeDescription
result.subjectobjectThe input frame and coordinates, and the resolved moment when given.
result.settingsobjectEvery convention: the frames and what the rotation does not include.
result.framesobjectequatorial_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}.
endpointstringThe route that computed it.
meta.input_sha256stringSHA-256 of the canonical request.
meta.result_sha256stringSHA-256 of the canonical result: POST /v1/verify recomputes it.
meta.engine_version / meta.ephemerisstringEngine 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.