ephemeris

Get single planet position

Lightweight endpoint for retrieving a single planet's position at a specific time. Supports both geocentric (default) and topocentric (with latitude/longitude) calculations.

post/ephemeris/planet-position

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/ephemeris/planet-position
  • 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

latitudenumber

Observer latitude in decimal degrees (omit for geocentric calculation)

longitudenumber

Observer longitude in decimal degrees (omit for geocentric calculation)

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"
  },
  "latitude": 40.7128,
  "longitude": -74.006,
  "planet_id": 0
}

Response

Planet position calculated successfully

successboolean

Calculation success status

Example response

{
  "calculation_metadata": {
    "technique_id": "natal",
    "technique_label": "Composite (Davison)",
    "technique_method": "davidson",
    "technique_version": "v1"
  },
  "planet": {
    "accidental_dignities": {
      "tags": [
        "angular"
      ]
    },
    "essential_dignities": {
      "exaltation_score": 4,
      "face_score": 1,
      "rulership_score": 5,
      "term_score": 2,
      "triplicity_score": 3
    },
    "motion_type": "direct"
  }
}

Changes

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