Docs › Altitude and azimuth of every body from a place

Altitude and azimuth of every body from a place

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 https://astro-agent.dev/v1/astronomy/altaz · $0.01 per call · MCP tool altitude_azimuth · Try it in the playground

For sky maps, telescope pointing, AR and observation apps: each body's apparent altitude and azimuth (with refraction, or airless), whether it is above the horizon, its topocentric right ascension and declination, distance (and the Moon's in km), angular distance from the Sun, illuminated fraction and visual magnitude (planets), plus the sky state (day, civil / nautical / astronomical twilight, night). Matches NASA/JPL Horizons to under a second of arc.

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
datetimestringyesThe moment: UTC ('2026-06-21T21:00:00Z'), with an explicit offset, or local civil time at the place ('2026-06-21T23:00', time zone resolved from the coordinates).
latitudenumberyesDecimal degrees, north positive.
longitudenumberyesDecimal degrees, east positive.
elevation_mnumber0Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled).
timezonestringIANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules).
bodiesarray of string (sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto)Bodies to locate. Default: all ten.
optionsobjectRefraction settings.
options.refractionbooleantrueApply atmospheric refraction to the altitude (true) or give the geometric, airless altitude (false).
options.temperature_cnumber10Air temperature for refraction, deg C.
options.pressure_hpanumber | string"standard"Air pressure for refraction, hPa, or 'standard' (from the elevation).

Example request

curl

curl -s https://astro-agent.dev/v1/astronomy/altaz \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime": "2026-06-21T23:00", "latitude": 48.8566, "longitude": 2.3522}'

Python

import os
import requests

body = {'datetime': '2026-06-21T23:00', 'latitude': 48.8566, 'longitude': 2.3522}
r = requests.post("https://astro-agent.dev/v1/astronomy/altaz", 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()

print("Sky:", data["result"]["sky"]["state"])
for b in data["result"]["bodies"]:
    print(f'{b["body"]:<8} alt {b["altitude"]:7.2f}  az {b["azimuth"]:7.2f} {b["compass"]:<4}'
          f'{"up" if b["above_horizon"] else "below"}')
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 = {"datetime": "2026-06-21T23:00", "latitude": 48.8566, "longitude": 2.3522};
const res = await fetch("https://astro-agent.dev/v1/astronomy/altaz", {
  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();

console.log("Sky:", data.result.sky.state);
for (const b of data.result.bodies)
  console.log(b.body.padEnd(8), "alt", b.altitude.toFixed(2), "az", b.azimuth.toFixed(2), b.compass);
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:

327247d4dfc3cdcabced238a5e343166028ea7888f3ca1d3f343dfe63745a46c

{
  "endpoint": "astronomy/altaz",
  "result": {
    "subject": {
      "location": {
        "latitude": 48.8566,
        "longitude": 2.3522,
        "elevation_m": 0.0
      },
      "timezone": "Europe/Paris",
      "timezone_source": "resolved_from_coordinates",
      "time": {
        "local_input": "2026-06-21T23:00",
        "time_basis": "civil",
        "timezone": "Europe/Paris",
        "timezone_source": "input",
        "utc_offset": "+02:00",
        "is_dst": true,
        "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": {
      "bodies": [
        "sun",
        "moon",
        "mercury"
      ],
      "refraction": true,
      "conventions": {
        "observer": "WGS84 ellipsoid; elevation above it optional (no terrain, no horizon dip)",
        "altitude": "apparent altitude of the centre above the horizon, degrees; with refraction (Bennett, Skyfield) for the given or standard temperature and pressure, or geometric (airless) with refraction=false",
        "azimuth": "degrees from true north, clockwise (90 = east)",
        "equatorial": "topocentric apparent right ascension and declination, true equator and equinox of date",
        "magnitude": "visual magnitude of the planets (Mallama & Hilton 2018, Skyfield); none for the Sun, Moon, Pluto",
        "sky": "day (Sun above -0.8333), civil (to -6), nautical (to -12), astronomical (to -18) twilight, night"
      },
      "temperature_c": 10.0,
      "pressure_hpa": "standard"
    },
    "sky": {
      "sun_altitude": -8.1132,
      "state": "nautical_twilight"
    },
    "bodies": [
      {
        "body": "sun",
        "altitude": -8.1132,
        "azimuth": 320.6912,
        "compass": "NW",
        "above_horizon": false,
        "right_ascension_hours": 6.0363,
        "declination": 23.43487,
        "distance_au": 1.016231
      },
      {
        "body": "moon",
        "altitude": 23.2432,
        "azimuth": 234.8484,
        "compass": "SW",
        "above_horizon": true,
        "right_ascension_hours": 11.907832,
        "declination": -2.94853,
        "distance_au": 0.002578,
        "distance_km": 385677.5,
        "elongation": 89.545,
        "illuminated_fraction": 0.4973,
        "magnitude": null
      },
      {
        "body": "mercury",
        "altitude": 2.8276,
        "azimuth": 299.7956,
        "compass": "WNW",
        "above_horizon": true,
        "right_ascension_hours": 7.717847,
        "declination": 21.13076,
        "distance_au": 0.725017,
        "elongation": 23.424,
        "illuminated_fraction": 0.2716,
        "magnitude": 1.0
      }
    ]
  },
  "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": "76865d8c0c118b4653f3f61b5abaf6babbf75aeab3d62e38e451b9326b5814d4",
    "result_sha256": "327247d4dfc3cdcabced238a5e343166028ea7888f3ca1d3f343dfe63745a46c",
    "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 place, its time zone, and the resolved moment ('time': local input, UTC, offset, Julian days, Delta T).
result.settingsobjectThe bodies, whether refraction is applied (with temperature and pressure) and every convention.
result.skyobjectThe Sun's altitude and the sky state: day, civil_twilight, nautical_twilight, astronomical_twilight or night.
result.bodiesarrayOne row per body: altitude, azimuth, compass point, above_horizon, right_ascension_hours, declination, distance_au (and distance_km for the Moon), elongation from the Sun, illuminated_fraction and magnitude (planets).
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).

CSV

Add ?format=csv to get the table of the result as CSV (gzip when your client sends Accept-Encoding: gzip): POST https://astro-agent.dev/v1/astronomy/altaz?format=csv. Same price and quota as JSON; the X-Result-SHA256 header is the hash of the JSON result the CSV is a view of. Long ranges in one file: bulk export.

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.