--- title: "Compute Venus Star Points" method: POST path: "/ephemeris/venus-star-points" tags: ["venus-cycles"] --- # Compute Venus Star Points `POST /ephemeris/venus-star-points` ## Request - Base URL: `https://api.openephemeris.com` - URL: `https://api.openephemeris.com/ephemeris/venus-star-points` - 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` Compute Sun-Venus conjunction events for a birth. natal_conjunction is the last conjunction before birth (the natal rule of Arielle Guttman's technique), with its type (inferior/superior) and Morning/Evening Star phase. star_points lists the five conjunctions nearest in time to birth, whichever side they fall on. Each event carries zodiac dignity, the phase Venus enters afterwards, and combustion status. Times are exact to about one second. 🤖 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 - VenusStarPointsRequest: Request for computing Venus Star Points around a birth date. - `beams_orb` number: Orb for under beams (default 17 degrees) - `combust_orb` number: Orb for combustion (default 8.5 degrees) - `exact_threshold` number: Threshold for 'exact' flag in degrees (default 1 arc min) - `subject` SubjectRequest, required: Subject identity and birth data used to compute a chart. - `birth_datetime` 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 - `birth_location` BirthLocation, required: Location context for birth data: coordinates plus timezone. - `city` string: City name - `country` string: Country - `elevation` number: Elevation in meters. Accepted and echoed back unchanged; it does not affect planetary positions, which are computed geocentrically. Elevation changes results only where it is taken as the `elev` query parameter: /eclipse/solar/local (local circumstances) and /time/solar-event plus /ephemeris/agro/* (horizon rise/set times). - `latitude` CoordinateInput, required: Flexible coordinate input supporting multiple formats. - `components` object: Separate degree components with direction - `decimal` number: Decimal degrees (-90 to 90 for lat, -180 to 180 for lon) - `dms` string: Degrees, minutes, seconds string (e.g., '40°42'46"N') - `location_name` string: Birthplace display name (e.g. "Dallas, TX"). Never affects calculations — coordinates and timezone are the only location facts the engine reads. Echoed back verbatim where the response carries an echo block: as subject.location_name on chart routes that echo a subject (natal, draconic, progressed, synastry, natal-transits, overlay, natal/batch items, predictive transit-chart), inside search_summary on /electional/natal-angle-crossings, metadata on /acg/midpoints, and natal on /human-design/transit-chart. Omitted from the response when not sent. - `longitude` CoordinateInput, required: Flexible coordinate input supporting multiple formats. - `components` object: Separate degree components with direction - `decimal` number: Decimal degrees (-90 to 90 for lat, -180 to 180 for lon) - `dms` string: Degrees, minutes, seconds string (e.g., '40°42'46"N') - `region` string: State/region - `timezone` TimezoneInput, required: 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 - `gender` string: Gender (optional) - `name` string, required: Subject name - `notes` string: Additional notes ## Response `200` Venus Star Points calculated successfully - VenusStarPointsResponse: Success response containing Venus Star Points and metadata. - `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 - `natal_conjunction` ConjunctionEvent, required: Details of a Venus-Sun conjunction event (Venus Star Point). - `combust` boolean, required: True if Venus is combust the Sun - `conjunction_type` 'inferior' | 'superior', required: Which kind of Sun-Venus conjunction this is. inferior: Venus passes between Earth and the Sun (Venus retrograde). superior: Venus passes behind the Sun (Venus direct). Found from the direction the geocentric elongation crosses zero. - `decan` integer, required: Decan (1-3) of the zodiac sign - `element` string, required: Zodiac element (Fire, Earth, Air, Water) - `exact` boolean, required: True if orb is within the exact threshold (usually < 1 arc minute) - `julian_day` number, double, required: Julian Day of the exact conjunction - `modality` string, required: Zodiac modality (Cardinal, Fixed, Mutable) - `orb` number, required: Degree separation between Venus and Sun - `planet_longitude` number, required: Longitude of Venus at the time of conjunction - `sign` string, required: Zodiac sign name - `star_longitude` number, required: Longitude of the Star Point (Sun position) - `sun_dignity` string, required: Sun's essential dignity at this position - `timestamp` string, required: ISO-8601 timestamp of the conjunction - `under_beams` boolean, required: True if Venus is under the Sun's beams - `venus_dignity` string, required: Venus's essential dignity at this position - `visibility` 'morning_star' | 'evening_star', required: The phase Venus enters after this conjunction: morning_star after an inferior conjunction, evening_star after a superior one. (At the exact conjunction Venus is cazimi; that is implied by orb and exact.) - `star_points` ConjunctionEvent[], required: The five Sun-Venus conjunctions nearest in time to birth (not a fixed before/after split). For the natal point use natal_conjunction. - `combust` boolean, required: True if Venus is combust the Sun - `conjunction_type` 'inferior' | 'superior', required: Which kind of Sun-Venus conjunction this is. inferior: Venus passes between Earth and the Sun (Venus retrograde). superior: Venus passes behind the Sun (Venus direct). Found from the direction the geocentric elongation crosses zero. - `decan` integer, required: Decan (1-3) of the zodiac sign - `element` string, required: Zodiac element (Fire, Earth, Air, Water) - `exact` boolean, required: True if orb is within the exact threshold (usually < 1 arc minute) - `julian_day` number, double, required: Julian Day of the exact conjunction - `modality` string, required: Zodiac modality (Cardinal, Fixed, Mutable) - `orb` number, required: Degree separation between Venus and Sun - `planet_longitude` number, required: Longitude of Venus at the time of conjunction - `sign` string, required: Zodiac sign name - `star_longitude` number, required: Longitude of the Star Point (Sun position) - `sun_dignity` string, required: Sun's essential dignity at this position - `timestamp` string, required: ISO-8601 timestamp of the conjunction - `under_beams` boolean, required: True if Venus is under the Sun's beams - `venus_dignity` string, required: Venus's essential dignity at this position - `visibility` 'morning_star' | 'evening_star', required: The phase Venus enters after this conjunction: morning_star after an inferior conjunction, evening_star after a superior one. (At the exact conjunction Venus is cazimi; that is implied by orb and exact.) - `success` boolean: Status of the calculation ## Other responses - `400`: Invalid input validation - `422`: Unprocessable Entity - Invalid input format - `500`: 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)