--- title: "Get single planet position" method: POST path: "/ephemeris/planet-position" tags: ["ephemeris"] --- # Get single planet position `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` Lightweight endpoint for retrieving a single planet's position at a specific time. Supports both geocentric (default) and topocentric (with latitude/longitude) calculations. ## Query parameters - `output_mode` string, nullable - `format` string ## Headers - `authorization` string, nullable - `X-API-Key` string, nullable - `X-OpenEphemeris-API-Key` string, nullable - `apikey` string, nullable ## Request body - PlanetPositionRequest: Parameters for calculating the exact astronomical position of a single celestial body at a specific moment in time. - `date_time` DateTimeInput, required: Date/time input in ISO-8601, component, or Julian day form. A value that states a clock time must also state its zone, either as a suffix on the string or via the `timezone` field below. - `components` object: Date/time components (year, month, day, and optionally hour, minute, second). If hour/minute are present, pass `timezone` alongside them; without it the request is rejected with 400 ambiguous_datetime. Omit the clock entirely and the date resolves to 12:00 UTC. - `iso` string: ISO-8601 datetime (supported range 1550–2650 CE, JPL DE440). If it states a clock time it must carry its zone: either a 'Z'/±HH:MM suffix on the string ("1987-07-15T09:01:00-05:00"), or a `timezone` passed alongside it. A zone-less clock time is rejected with 400 ambiguous_datetime — it is not read as UTC. A date-only value ("1987-07-15") has no clock to be ambiguous about and resolves to 12:00 UTC. - `julian_day` number, double: Julian Day Number (always UTC-based, so it needs no zone) - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets. - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user. - `iana_name` string: IANA timezone name - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used. - `utc_offset` number: UTC offset in hours - `latitude` number: Observer latitude in decimal degrees (omit for geocentric calculation) - `longitude` number: Observer longitude in decimal degrees (omit for geocentric calculation) - `planet_id` integer, 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. ## Response `200` Planet position calculated successfully - PlanetPositionResponse: Response from planet position calculation. - `calculation_metadata` CalculationMetadata: Metadata about chart calculations. Relaxed to allow minimal fields used by tests while remaining forward-compatible. - `ascendant_on_left` boolean, nullable: When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead. - `ayanamsa` union: Sidereal ayanamsa selection - 'lahiri' | 'fagan_bradley' | 'krishnamurti' | 'raman' | 'yukteshwar': Supported sidereal ayanamsa options. All five are computed from the same IAU 2006 general-precession model, so each is epoch-dependent rather than a frozen constant; they differ by up to ~2.3 degrees, which is enough to move a body across a sign boundary. Defaults to lahiri when zodiac_type is sidereal and no system is named. - string - `calculation_time` number: Legacy calculation time in seconds - `calculation_time_ms` number: Processing time at the orchestrator layer in milliseconds - `calculation_time_utc` string, date-time: UTC timestamp when the calculation executed - `coordinate_reference_frame` string: Coordinate frame the positions are expressed in. The engine computes apparent places referred to the true equator/equinox of date and converts them to the true ecliptic of date, so this reads geocentric_true_ecliptic_of_date. - `coordinate_system` union: Coordinate system used (geocentric/topocentric) - 'geocentric' | 'topocentric' | 'heliocentric' | 'barycentric': Coordinate system used for calculations. - string - `delta_t_seconds` number: Delta T (TT - UT1) applied during calculation, in seconds - `delta_t_source` union: Source of Delta T values (computation engine, IERS, approximation) - 'nasa_jpl' | 'iers' | 'approximation_model': Source of ΔT values used in calculations. - string - `ephemeris_source` string: Primary ephemeris source (e.g., SuperNOVAS / Calceph) - `ephemeris_version` string: Version of the ephemeris data files - `fixed_star_catalog` union: Fixed star catalog or subset identifier - 'bright_mag3' | 'bright_mag5' | 'royal_stars' | 'parans_key': Fixed star catalog snapshots. - string - `house_system` union: House system actually used during calculation - 'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W': Supported house systems. - string - `include_fixed_stars` boolean: Whether fixed stars were included - `julian_day` number, double: Julian Day Number representing the calculation instant - `missing_objects` object: Objects that could not be calculated along with reasons - `node_source` union: Lunar node/apsides mode requested (true osculating, mean, apsides) - 'true_osculating' | 'mean' | 'mean_apsides': Node/apsides calculation modes (SE §2.2). - string - `object_set` union: Named object set or preset powering the calculation - 'traditional_7' | 'modern_10' | 'modern_plus_chiron' | 'asteroids_major' | 'full' | 'custom': Standardized celestial object bundles. - string - `orb_system_used` string: Aspect orb system applied - `precision_level` string: Legacy precision descriptor - `precision_summary` PrecisionSummary: Structured precision report for calculation metadata. - `max_position_error_arcseconds` number: Maximum validated positional error in arcseconds - `max_timing_error_seconds` number: Maximum validated timing error in seconds - `notes` string: Additional human-readable context for the precision summary - `reference_profile` string: Reference dataset or validation profile used for the comparison - `processing_time_ms` number: End-to-end processing time in milliseconds - `server_version` string: Build identifier of the engine that produced this response. Moves on every deploy, so it is the signal for resolution-LOGIC changes — the class of change that can move a historical offset without touching overlay data (and therefore without moving tz_overlay_version). Poll both. - `sidereal_time` number: Local sidereal time in hours - `technique_id` string: High-level technique identifier (e.g., natal, synastry, composite, overlay) - `technique_label` string: Human-readable technique label - `technique_method` string: Method name within a technique (e.g., davidson, midpoint) - `technique_version` string: Technique implementation version (for future-proofing) - `time_scale` union: Time scale used for internal calculations (UTC, TT, TDB) - 'UTC' | 'TT' | 'TDB': Time scale used for reporting results. - string - `tz_overlay_hash` string: Content hash of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied (tz_rule_source starts with 'overlay:'). - `tz_overlay_version` integer: Monotonic version of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied. Tracks overlay DATA only — pair with server_version to also catch resolution-logic changes. - `tz_precision` 'statutory' | 'documented' | 'inferred': Sourcing grade of the overlay row that produced the offset: 'statutory' (operative text of a session law or statute verified), 'documented' (contemporary reporting), or 'inferred' (deduced from legal context; verify before relying on it near the row's edges). Stamped only when an overlay row applied. - `tz_rule_citation` string: Primary-source citation for the overlay row that produced the offset — statute reference, ICC/agency order number, or documented press/almanac source. Stamped only when an overlay row applied. - `zodiac_type` union: Zodiac framework applied (tropical/sidereal) - 'tropical' | 'sidereal': Supported zodiac frameworks. - string - `planet` PlanetResponse, required: Planet position data in response. - `accidental_dignities` AccidentalDignityInfo: Accidental dignity information for a body (tags-only). - `tags` string[]: Accidental dignity tags (planets-only). - `declination` number: Declination in degrees - `distance` number, required: Distance from Earth - `element` string: Element (Fire, Earth, Air, Water) - `essential_dignities` EssentialDignityInfo: Essential dignity information for a planet. - `debilities_held` string[]: List of debilities present - `detriment` boolean, required: Planet is in detriment - `dignities_held` string[]: List of dignities present - `dignity_score` number, required: Aggregate essential dignity score - `domicile` boolean, required: Planet holds domicile (rulership) - `effective_score` number, required: Final dignity score after motion modifiers are applied. - `exaltation` boolean, required: Planet holds exaltation - `exaltation_score` integer: Score contribution from exaltation - `face` string: Face (decan) ruler holding dignity - `face_score` integer: Score contribution from decan (face) dignity - `fall` boolean, required: Planet is in fall - `motion_modifier` number: Score modifier applied due to motion state. Negative values weaken the raw dignity score. - `motion_state` string: Motion state used for dignity adjustments (direct, retrograde, stationary, unknown) - `planet` string, required: Planet name - `ruler` boolean, required: Backward-compatible alias for domicile field. - `rulership_score` integer: Score contribution from domicile (rulership) dignity - `sign` string, required: Current sign - `strength` string, required: Dignity strength category - `term` string: Egyptian term ruler holding dignity - `term_score` integer: Score contribution from Egyptian terms - `triplicity` string: Triplicity mode where planet has dignity (day/night) - `triplicity_score` integer: Score contribution from triplicity rulers - `warnings` string[]: Non-fatal warnings encountered while deriving dignity metadata. - `house_number` integer: House number (1-12) - `is_retrograde` boolean: Whether planet is in retrograde motion (longitude_speed < 0) - `latitude` number, required: Ecliptic latitude in degrees - `longitude` number, required: Ecliptic longitude in degrees - `longitude_speed` number: Longitude speed in degrees/day - `modality` string: Modality (Cardinal, Fixed, Mutable) - `motion_type` string: Motion classification: direct, retrograde, stationary, or unknown - `name` string, required: Planet name - `on_cusp` boolean: True when longitude is within cusp tolerance and planet is treated as entering the next house - `out_of_bounds` boolean: Planet exceeds solar declination bounds - `right_ascension` number: Geocentric right ascension in degrees - `sign_longitude` number: Longitude within sign - `sign_name` string: Zodiac sign name - `sign_symbol` string: Zodiac sign symbol - `topocentric_declination` number: Topocentric declination in degrees (when applicable) - `topocentric_right_ascension` number: Topocentric right ascension in degrees (when applicable) - `success` boolean: Calculation success status ## Other responses - `400`: Invalid input (e.g., unknown planet_id) - `422`: Validation Error - `500`: Calculation error --- [API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)