---
title: "Venus greatest elongations"
method: POST
path: "/ephemeris/venus-star-points/elongations"
tags: ["venus-cycles"]
---

# Venus greatest elongations

`POST /ephemeris/venus-star-points/elongations`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/venus-star-points/elongations`
- 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`

Find all Venus greatest elongations in a date range. 🤖 AI-optimized output available — add `format=llm` to reduce payload ~60%.

## Query parameters

- `format` string, nullable

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- VenusRangeRequest: Request for computing Venus events over a time range.
  - `beams_orb` number: Orb for under beams (default 17 degrees)
  - `combust_orb` number: Orb for combustion (default 8.5 degrees)
  - `end_date` string, required: ISO-8601 end date or datetime. A clock time must carry its own zone ('Z' or ±HH:MM); a zone-less clock time is rejected with 400 ambiguous_datetime. A date-only value resolves to 12:00 UTC.
  - `start_date` string, required: ISO-8601 start date or datetime. A clock time must carry its own zone ('Z' or ±HH:MM); a zone-less clock time is rejected with 400 ambiguous_datetime. A date-only value resolves to 12:00 UTC.

## Response `200`

Successful Response

- VenusElongationsResponse: Success response containing Venus greatest elongations over a range.
  - `calculation_metadata` CalculationMetadata, required: 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
  - `elongations` VenusElongation[], required: List of greatest elongations found in range
    - `elongation_type` 'greatest_eastern' | 'greatest_western', required: Direction of elongation
    - `julian_day` number, double, required: Julian Day of the event
    - `longitude` number, required: Zodiac longitude of Venus at max elongation
    - `separation` number, required: Maximum angular separation from the Sun in degrees
    - `sign` string, required: Zodiac sign name
    - `timestamp` string, required: ISO-8601 timestamp
    - `visibility` 'morning_star' | 'evening_star', required: Venus visibility phase
  - `success` boolean: Status of the calculation

## Other responses

- `400`: Bad Request - Input validation failed
- `422`: Unprocessable Entity - Invalid input format
- `500`: Internal Server Error - Calculation failed

---

[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)