Time Input

Every computation endpoint requires a moment in time, specified as either an ISO 8601 datetime string or a Julian Day number.

ISO 8601 datetime (datetime parameter)

Provide a UTC datetime string:

?datetime=2024-03-20T12:00:00Z

The Z suffix indicates UTC. The API does not perform timezone conversion — all input must be in UTC.

Accepted formats:

• 2024-03-20T12:00:00Z — full precision
• 2024-03-20T12:00:00.000Z — with milliseconds
• 2024-03-20T12:00Z — without seconds

Julian Day (jd parameter)

Provide a Julian Day number in Universal Time (UT1):

?jd=2460388.0

Julian Day is a continuous count of days since January 1, 4713 BCE. It's the standard time representation in astronomical computation.

Common reference points:

Rules

• Provide exactly one of datetime or jd. If both are given, the API returns a conflicting_parameters error.
• If neither is provided, the API returns a missing_parameter error.
• The valid range covers the full Swiss Ephemeris range: approximately 5400 BCE to 5400 CE.

Converting between formats

If you have a Julian Day and need a datetime (or vice versa), the conversion is straightforward:

// JavaScript: UTC Date → Julian Day
function dateToJD(date) {
  return date.getTime() / 86400000 + 2440587.5;
}

// JavaScript: Julian Day → UTC Date
function jdToDate(jd) {
  return new Date((jd - 2440587.5) * 86400000);
}

# Python: datetime → Julian Day
from datetime import datetime, timezone
def to_jd(dt):
    return dt.timestamp() / 86400 + 2440587.5

# Python: Julian Day → datetime
def from_jd(jd):
    return datetime.fromtimestamp((jd - 2440587.5) * 86400, tz=timezone.utc)