← Back to docs
endpoints ◀ ▶
POST astra/body/distance/

Distance between two celestial bodies at a given datetime.

Astra Bodies

Overview

Returns the distance in kilometres between any two supported celestial bodies as observed from a given location and datetime. Both the start and end bodies are specified by their Skyfield key from the astra/bodies/ endpoint. Computed using Skyfield's high-precision ephemeris (DE421), which accounts for the light-travel time and the observer's position on Earth's surface. Useful for applications that track planetary conjunctions, oppositions, or Earth-Moon distance over time.


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.
end Choice Body Yes The destination celestial body for a distance computation. Must be one of the Skyfield keys returned by /astra/bodies/ (e.g. EARTH, SUN, VENUS). Case-sensitive.
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.
start Choice Body Yes The origin celestial body for a distance computation. Must be one of the Skyfield keys returned by /astra/bodies/ (e.g. MARS, MOON). Case-sensitive.
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
date1 Datetime — Observation datetime echoed from the request. 2025-06-21T14:00:00
distance_km Integer — Distance between the two bodies in kilometres, rounded to the nearest integer. 78337600
end String — Skyfield key of the destination body. VENUS
formatted_distance_km String — Distance formatted with comma separators for readability. 78,337,600
lat Float — Observer latitude echoed from the request. 48.428333
lon Float — Observer longitude echoed from the request. -123.364722
start String — Skyfield key of the origin body. MARS
tz String — Resolved IANA timezone name. America/Vancouver