Distance between two celestial bodies at a given datetime.

---

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