← Back to docs
endpoints ◀ ▶
POST astra/planet/summary/

Altitude, azimuth, distance, and rise/set for all planets at a given datetime.

Astra Planets

Overview

Returns a consolidated snapshot of all planets (Mercury through Pluto, excluding Earth) as seen from a given location and datetime. For each planet the response includes its current altitude and azimuth, distance from Earth, distance from the Sun, and rise/set events for the day. This is the most data-rich astra endpoint and is intended for dashboards or sky-tonight views where the user wants a complete picture of the visible sky in a single request.


Request parameters

Name Type In Required Description Example
date1 Date Body Yes The start date (or single query date) for the computation. Accepted formats: YYYY-MM-DD for date-only fields, ISO 8601 datetime string (YYYY-MM-DDTHH:MM) for datetime fields.
lat Float Body Yes Observer latitude in decimal degrees. Valid range: -90.0 (South Pole) to 90.0 (North Pole). Used to compute the observer's position on Earth's surface for all sky calculations.
lon Float Body Yes Observer longitude in decimal degrees. Valid range: -180.0 to 180.0. Negative values are west of the Prime Meridian, positive values are east.
timezone_slug Choice Body Optional Slug of a timezone record used to localise event datetimes in the response (e.g. america-new-york). When omitted, the timezone is derived automatically from the supplied coordinates. Obtain valid timezone slugs from the timezone list endpoint.

Response fields

Name Type Nullable Description Example
results Array — Array of planet summaries, one entry per non-Earth planet.
results[].altitude_azimuth Object — Altitude and azimuth of the planet as seen from the observer at the requested datetime.
results[].altitude_azimuth.altitude Float — Altitude above the horizon in degrees. Negative means below the horizon. -12.4
results[].altitude_azimuth.azimuth Float — Azimuth measured clockwise from true north in degrees (0–360). 112.3
results[].altitude_azimuth.formatted_altitude String — Altitude formatted as a degree string (e.g. -12.4°). -12.4°
results[].altitude_azimuth.formatted_azimuth String — Azimuth with compass direction (e.g. 112.3° ESE). 112.3° ESE
results[].altitude_azimuth.is_visible Boolean — True if the planet is currently above the horizon. false
results[].distance_to_earth Object — Distance from this planet to Earth at the requested datetime.
results[].distance_to_earth.distance_km Integer — Distance to Earth in kilometres. 78337600
results[].distance_to_earth.formatted_distance_km String — Distance to Earth formatted with comma separators. 78,337,600
results[].distance_to_sun Object — Distance from this planet to the Sun at the requested datetime.
results[].distance_to_sun.distance_km Integer — Distance to the Sun in kilometres. 227936640
results[].distance_to_sun.formatted_distance_km String — Distance to the Sun formatted with comma separators. 227,936,640
results[].planet_name String — Common name of the planet (e.g. Mars, Jupiter). Mars
results[].planet_symbol String — Unicode astronomical symbol for the planet (e.g. ♂). ♂
results[].rising_setting Object — Rise and set events for this planet over the next 24-hour window from the requested datetime.
results[].rising_setting.count Integer — Number of rise/set events found in the 24-hour window. 2
results[].rising_setting.events Array — List of rise and set events for this planet, each with the same structure as sky event endpoints.