ephemeris

Check planet retrograde status

Lightweight endpoint for determining whether a planet is retrograde at a specific time. Returns motion type (direct/retrograde/stationary) and speed data.

post/ephemeris/retrograde-status

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/ephemeris/retrograde-status
  • Auth: one of:
    • HTTP bearer
    • API key in header X-OpenEphemeris-API-Key
    • API key in header X-API-Key
    • API key in header X-Service-Key

Query parameters

output_modestring nullable

Deprecated: use preset+format. Accepts full|simple|llm.

formatstring

Headers

authorizationstring nullable
X-API-Keystring nullable
X-OpenEphemeris-API-Keystring nullable
apikeystring nullable

Request body

planet_idinteger required

SE-compatible planet ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 12=Mean Lilith, 13=Osculating Lilith, 40=Interpolated Lilith, 15=Chiron, 16=Pholus, 17-20=Ceres/Pallas/Juno/Vesta). Lunar nodes: id 10 (north_node_mean, named "North Node (Mean)") is the classical mean node (the IERS/Meeus mean-node polynomial, Swiss Ephemeris SE_MEAN_NODE): smooth and always retrograde. Id 11 (north_node_true, named "North Node (True)") is the osculating true node in the true ecliptic of date, computed from DE440 Moon state vectors (SE_TRUE_NODE) — the node Human Design software uses and the one /human-design/chart derives gates from: expect a +/-1.7 deg oscillation about the mean node, a variable longitude_speed, and occasional direct motion. Until 2026-09-26 id 10 served the true node (OE-BUG-2026-017). South Node has no id: add 180 deg to either node.

Example request

{
  "date_time": {
    "iso": "2025-12-11T12:00:00Z"
  },
  "planet_id": 2
}

Response

Retrograde status determined successfully

is_retrogradeboolean required

True if planet is in retrograde motion

longitude_speednumber required

Longitude speed in degrees per day

motion_typestring required

Motion classification: direct, retrograde, or stationary

planet_idinteger required

SE-compatible planet ID

planet_namestring required

Planet name

speed_thresholdnumber

Threshold for stationary classification (degrees/day)

successboolean

Calculation success status

Example response

{
  "motion_type": "direct"
}

Changes

No recorded changes to this operation across all 1 revision of this API.