---
title: "Calculate transit chart (full chart snapshot)"
method: POST
path: "/predictive/transit-chart"
tags: ["predictive"]
---

# Calculate transit chart (full chart snapshot)

`POST /predictive/transit-chart`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/predictive/transit-chart`
- 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`

Return a full chart payload for a given moment (transit chart). Includes all supported bodies: Sun–Pluto (core) plus Chiron, Mean/True North & South Nodes, Mean/True Lilith (Black Moon), and Ceres (extended bodies — gracefully omitted when ephemeris kernels are unavailable). Also returns houses/angles, aspects (major; minor opt-in), and a `body_categories` map for UI rendering. This is a chart snapshot endpoint (not a transit event search). 🤖 AI-optimized output: add `format=llm` to reduce payload ~70%.

## Query parameters

- `output_mode` string, nullable
- `format` string: Response format: json | llm. Controls response projection only.

## Request body

- NatalChartEnhancedRequest: Request for enhanced natal chart with additional calculations.
  - `configuration` NatalEnhancedConfig: Extended configuration for enhanced natal outputs.
    - `additional_objects` string[]: Explicit body slugs to compute in addition to the base roster (10 classical planets, mean+true nodes, Chiron, Pholus, Ceres/Pallas/Juno/Vesta, and the sb441-n16 minor-asteroid set). Ephemeris body slugs: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, north_node, true_node, lilith, lilith_true, lilith_interpolated, chiron, pholus, eris, sedna, makemake, haumea, quaoar, orcus, ixion, varuna, cupido, hades, zeus, kronos, apollon, admetos, vulkanus, poseidon, eros, sappho, lilith_asteroid, nessus, chariklo, amor, betulia, icarus, apollo, adonis, phaethon, astraea, hebe, flora, metis, parthenope, victoria, egeria, irene, massalia, isis, anubis, odysseus, tolosa, medusa, ambrosia, aletheia, thule, polyxo, myrrha, valentine, hercynia, nestor, siva, atlantis, aphrodite, prometheus, epimetheus, shaposhnikov, lick, huya, ceres, pallas, juno, vesta, hygiea, eunomia, psyche, europa_asteroid, cybele, sylvia, thisbe, camilla, iris, davida, euphrosyne, interamnia. Angle-derived points (vertex, part_of_fortune, etc.) are not supported by this field. Unknown slugs are ignored.
    - `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.
    - `asteroid_groups` AsteroidGroupEnum[]: Optional thematic asteroid groups to include, additive on top of the base roster: major (Ceres/Pallas/Juno/Vesta), centaur (Chiron/Pholus), main_belt (the 12 sb441-n16 minor asteroids), tno (the 8 trans-Neptunian objects: Eris, Sedna, Makemake, Haumea, Quaoar, Orcus, Ixion, Varuna). muse is accepted but not yet computed (no kernel loaded).
    - `ayanamsa` '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.
    - `coordinate_frame` 'ecliptic' | 'equatorial' | 'horizontal': Reference frame for reported coordinates.
    - `coordinate_system` 'geocentric' | 'topocentric' | 'heliocentric' | 'barycentric': Coordinate system used for calculations.
    - `dignities` DignityConfig: Essential/accidental dignity settings.
      - `system` 'lilly_like_standard' | 'modern_balanced' | 'sidereal_variant': Supported dignity scoring systems.
    - `fixed_star_options` FixedStarConfig: Configuration for fixed star calculations.
      - `catalog_version` 'bright_mag3' | 'bright_mag5' | 'royal_stars' | 'parans_key': Fixed star catalog snapshots.
      - `include` boolean: Toggle fixed star conjunction calculations
      - `magnitude_limit` number: Maximum magnitude (lower = brighter)
      - `orb` number: Orb in degrees for fixed star hits
      - `stars` string[]: Optional whitelist of fixed stars to evaluate
    - `house_system` 'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W': Supported house systems.
    - `lots` LotsConfig: Arabic part / lot configuration.
      - `exclude` string[]: Blacklist of lot identifiers to drop
      - `include` string[]: Whitelist of lot identifiers (overrides include_all)
      - `include_all` boolean: Include every lot from the selected suite
      - `suite` 'fortune_suite_canonical' | 'hermetic_core' | 'mercury_sect' | 'custom': Predefined sets of Arabic parts/lots.
    - `node_source` 'true_osculating' | 'mean' | 'mean_apsides': Node/apsides calculation modes (SE §2.2).
    - `object_set` 'traditional_7' | 'modern_10' | 'modern_plus_chiron' | 'asteroids_major' | 'full' | 'custom': Standardized celestial object bundles.
    - `zodiac_type` 'tropical' | 'sidereal': Supported zodiac frameworks.
  - `enhanced_options` EnhancedCalculationOptions: Options for enhanced natal chart calculations.
    - `aspect_patterns` boolean: Identify aspect patterns
    - `element_balance` boolean: Calculate elemental balance
    - `elongations` boolean: Compute Sun-relative elongation metrics for major bodies (separation, signed delta, east/west).
    - `harmonic_numbers` integer[]: Harmonic numbers to calculate (default: [4, 5, 7, 9])
    - `hemisphere_emphasis` boolean: Analyze hemisphere emphasis
    - `hermetic_lots_selection` string[]: Optional list of Hermetic lot identifiers to calculate (aliases accepted: arabic_parts_selection). If omitted, defaults to the canonical selection.
    - `human_design_gates` boolean: Compute Human Design / I Ching gate + line mappings from ecliptic longitude.
    - `include_fixed_stars` boolean: DEPRECATED. Fixed-star computation is configured via configuration.fixed_star_options.include. This field is accepted for backward compatibility and may be removed in a future release.
    - `include_harmonics` boolean: Include harmonic chart positions
    - `include_hermetic_lots` boolean: Calculate Hermetic lots
    - `include_midpoints` boolean: Calculate midpoints between planet pairs
    - `lunar_phase` boolean: Compute lunar phase (name, illumination, phase angle, waxing/waning, and days-to-new/full).
    - `sect_determination` boolean: Perform sect determination
    - `solar_relationships` boolean: Compute solar relationship / visibility classifications (e.g., cazimi/combust/under-beams) and Mercury/Venus morning/evening star context.
    - `void_of_course` boolean: Compute Void-of-Course Moon status and window (bounded search within current sign).
  - `include_all_traditional_parts` boolean: DEPRECATED. Prefer request body `options.include_all_traditional_parts` where applicable. This top-level field is accepted for backward compatibility and may be removed in a future release.
  - `include_aspects` boolean: DEPRECATED. Prefer request body `options.include_aspects`. This field is accepted for backward compatibility and may be removed in a future release.
  - `include_dignities` boolean: DEPRECATED. Prefer request body `options.include_dignities`. This top-level field is accepted for backward compatibility and may be removed in a future release.
  - `include_hermetic_lots` boolean: DEPRECATED. Prefer request body `enhanced_options.include_hermetic_lots` (or `options.include_hermetic_lots`). This top-level field is accepted for backward compatibility and may be removed in a future release.
  - `include_visual` boolean, nullable: When true, a high-fidelity chart wheel SVG/PNG is embedded in the response alongside the data payload. Adds 2 credits to the request cost.
  - `options` ResponseOptions: Options for customizing API response content and format.
    - `declination_orb` number: Orb in degrees for declination-based aspects
    - `include_angle_aspects` boolean: Include aspects between planets and the four chart angles (Ascendant, Descendant, Midheaven, Imum Coeli). Angle aspects use tighter orbs than planet-planet aspects and are flagged with `involves_angle` in the response. Defaults to false: these hits are location-dependent (a relocated chart keeps every planet-planet aspect and changes every angle aspect), so they are opt-in rather than silently added to the existing aspect list.
    - `include_aspects` boolean: Include aspect calculations
    - `include_declination_aspects` boolean: Include declination-based aspects
    - `include_declination_values` boolean: Include per-planet declination and right-ascension values (and topocentric variants when applicable). This is a payload shaping control and may be tier-gated.
    - `include_dignities` boolean: Include dignities (essential + accidental when available)
    - `include_fixed_stars` boolean: DEPRECATED. Fixed-star computation is configured via configuration.fixed_star_options.include. This field will be removed in a future release.
    - `include_hermetic_lots` boolean: Include Hermetic lot payload (aliases accepted: include_arabic_parts)
    - `include_minor_aspects` boolean: Include minor aspects (e.g., quincunx, semisquare, quintile). When False (default), only major aspects are computed.
    - `include_out_of_bounds` boolean: Include out-of-bounds flags for planets
  - `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
  - `transit_datetime` DateTimeInput: 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
  - `visual_config` VisualRenderConfig: Optional rendering preferences for inline chart visuals.
    - `format` 'svg' | 'png': Output encoding: "svg" (default) or "png". PNG requires resvg on the server.
    - `layout` 'graph' | 'mandala': Bodygraph composition: "graph" (default) is the classic layout; "mandala" nests the same diagram inside concentric rings. Ignored for wheel renders. Honored on natal and overlay (transit, connection) bodygraph paths.
    - `size` integer: Canvas pixel dimension. Range [200, 4000]. Default 800.
    - `theme` 'light' | 'dark': Colour palette: "light" (default) or "dark".

## Response `200`

Successful Response

- EnhancedChartSuccessResponse: Standardized envelope for enhanced chart responses.
  - `data` NatalChartEnhancedResponse, required: Enhanced natal chart response with additional calculations. Adjusted to match test expectations: aspects as a list, optional aspect_matrix, permissive calculation_metadata, and chart_type echo.
    - `angles` AnglesResponse, required: Chart angles data in response.
      - `ascendant` number, required: Ascendant longitude in degrees
      - `descendant` number, required: Descendant longitude in degrees
      - `imum_coeli` number, required: Imum Coeli longitude in degrees
      - `midheaven` number, required: Midheaven longitude in degrees
    - `arabic_parts` ArabicPartsResponse: Canonical Arabic parts payload for enhanced responses.
      - `arabic_parts` object, required: Arabic parts keyed by registry name
      - `calculation_time_ms` number, required: Computation time in milliseconds
      - `formulas_used` string[], required: Ordered list of formulas executed
      - `hermetic_lot_names` string[]: Sorted subset of arabic part keys that map to canonical Hermetic lots
      - `sect_determination` object, required: Sect analysis metadata used for formula selection
      - `total_parts_calculated` integer, required: Number of parts returned
    - `aspect_matrix` AspectMatrixResponse: Complete aspect matrix for all planetary pairs. Relaxed to allow additional performance fields provided by enhanced calculator.
      - `aspect_counts` object: Count by aspect type
      - `aspects` AspectResponse[]: All aspects found
        - `angle` number, required: Aspect angle in degrees
        - `applying` boolean, required: Is aspect applying
        - `aspect` string, required: Aspect name
        - `object1` string, required: First object name
        - `object2` string, required: Second object name
        - `orb` number, required: Orb in degrees
      - `calculation_time_ms` number: Calculation time in ms
      - `major_aspects` integer: Major aspect count
      - `matrix` object: Matrix format of aspects
      - `minor_aspects` integer: Minor aspect count
      - `orb_config_used` string: Orb configuration used
      - `patterns` AspectPattern[]: Identified aspect patterns
        - `aspects` string[], required: Aspects forming the pattern
        - `complete` boolean, required: Is pattern complete
        - `orb_tolerance` number, required: Maximum orb in pattern
        - `pattern_type` string, required: Pattern type (T-square, Grand Trine, etc.)
        - `planets` string[], required: Planets involved
        - `strength` number, required: Pattern strength (0-1)
      - `total_aspects` integer: Total number of aspects
    - `aspect_patterns` AspectPattern[]: Detected aspect patterns (Grand Trine, T-Square, Yod, Kite, Stellium, Grand Cross)
      - `aspects` string[], required: Aspects forming the pattern
      - `complete` boolean, required: Is pattern complete
      - `orb_tolerance` number, required: Maximum orb in pattern
      - `pattern_type` string, required: Pattern type (T-square, Grand Trine, etc.)
      - `planets` string[], required: Planets involved
      - `strength` number, required: Pattern strength (0-1)
    - `aspects` EnhancedAspectResponse[]: Enhanced aspects list
      - `aspect_quality` string: Quality assessment derived from dignities or contextual analysis
      - `aspect_type` string, required: Aspect type (e.g., Conjunction, Square)
      - `classification` string, required: Aspect classification (major or minor)
      - `dignity_interaction` string: Summary of the essential dignity interaction between the planets
      - `exact_angle` number, required: Exact angle associated with the aspect type
      - `involves_angle` boolean: True when one side of this aspect is a chart angle (Ascendant/Descendant/Midheaven/Imum Coeli) rather than a body. Angle aspects depend on birth location and local sidereal time, so they change under relocation while planet-planet aspects do not — consumers that relocate charts must recompute or relabel these.
      - `is_applying` boolean: True if the aspect is applying, False if separating, None when undetermined
      - `mutual_reception` boolean: Whether the two planets are in mutual reception
      - `orb` number, required: Absolute distance from the exact angle in degrees
      - `orb_allowance` number: Maximum allowed orb for this aspect and planet pair in degrees
      - `orb_percentage` number, required: Percentage of the allowed orb that is used (0-100)
      - `phase_angle` number, required: Current angular separation between the bodies in degrees
      - `planet1` string, required: First planet involved in the aspect
      - `planet2` string, required: Second planet involved in the aspect
      - `speed_ratio` number: Ratio of the slower planet's absolute speed to the faster one's (0-1)
      - `strength` number, required: Aspect strength scaled between 0.0 and 1.0
    - `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
    - `chart_type` string: Chart type identifier
    - `declination_aspects` DeclinationAspect[]: Declination-based aspects
      - `applying` boolean, required: Whether aspect is applying
      - `body1` string, required: First body name
      - `body2` string, required: Second body name
      - `declination1` number, required: First body declination
      - `declination2` number, required: Second body declination
      - `orb` number, required: Orb difference in degrees
      - `type` string, required: Aspect type
    - `element_balance` object: Elemental balance
    - `elongations` object: Sun-relative elongations (per-body separation and signed east/west delta) (opt-in).
    - `fixed_stars` FixedStarsResponse: Container for fixed star positions and conjunctions.
      - `conjunctions` FixedStarConjunctionResponse[], required: Star-planet conjunctions
        - `exact` boolean, required: Whether orb is below exact threshold
        - `interpretation_hint` string: Quick interpretation keyword
        - `orb` number, required: Orb in degrees
        - `planet` string, required: Planet name
        - `planet_longitude` number, required: Planet longitude in degrees
        - `star` string, required: Fixed star name
        - `star_longitude` number, required: Star longitude in degrees
      - `metadata` FixedStarsMetadata, required: Metadata describing fixed star calculation.
        - `available_catalog` boolean, required: Whether built-in star catalog was available
        - `calculation_duration_ms` number: Computation time in milliseconds
        - `calculation_time` string: ISO8601 timestamp of calculation
        - `error` string: Optional error description if calculation degraded
        - `magnitude_limit` number: Magnitude limit applied
        - `missing_stars` string[]: Stars requested but unavailable
        - `orb_used` number: Orb used for conjunction detection
        - `requested_star_count` integer, required: Number of stars requested
        - `selected_stars_count` integer, required: Count of Foundation 24 stars returned
        - `total_stars_calculated` integer, required: Number of stars calculated
      - `positions` FixedStarPositionResponse[], required: Calculated star positions
        - `constellation` string: Constellation
        - `distance_light_years` number: Distance in light years
        - `julian_day` number, double: Julian Day of calculation
        - `latitude` number, required: Latitude in degrees
        - `longitude` number, required: Current longitude in degrees
        - `magnitude` number: Apparent magnitude
        - `name` string, required: Fixed star name
        - `sign_longitude` number: Longitude within sign
        - `sign_name` string: Zodiac sign
        - `sign_symbol` string: Zodiac sign symbol
        - `spectral_class` string: Spectral classification
        - `traditional_name` string: Traditional name
    - `harmonics` object: Harmonic chart positions keyed by harmonic number
    - `hemisphere_emphasis` object: Hemisphere weights
    - `houses` HousesResponse, required: House system data in response.
      - `cusps` number[], required: House cusp longitudes in degrees
      - `system` string, required: House system code
    - `human_design_gates` object: Human Design / I Ching gate + line mappings from ecliptic longitude (math-only; includes mapping version) (opt-in).
    - `lunar_phase` object: Lunar phase context (phase name, illumination, phase angle, waxing/waning, days-to-new/full) (opt-in).
    - `midpoints` object[]: Calculated midpoints between planet pairs
    - `omitted_bodies` OmittedBody[], nullable: Bodies that were requested (or are in the chosen object_set/asteroid_groups) but not computed because the chart date is outside the span of their own JPL kernel. Absent when nothing was omitted. Each entry carries the body's valid_from/valid_to. Applies to the bodies that have a per-body kernel (the centaurs, trans-Neptunian objects and extended asteroids: 1600-2200 CE); the planets, nodes and sb441 main-belt asteroids cover 1550-2650 and a date outside that is rejected outright.
      - `detail` string: Human-readable explanation.
      - `id` string, required: Canonical body id (see GET /catalogs/bodies).
      - `name` string, required: Body name.
      - `reason` string, required: Why it was omitted. `outside_kernel_window`: the instant is outside the span of this body's own JPL kernel (valid_from..valid_to). Only bodies with a per-body kernel (the centaurs, trans-Neptunian objects and extended asteroids) have such a window; the planets, nodes and the sb441 main-belt asteroids cover the full 1550-2650 range.
      - `valid_from` string: First date the body is computed (YYYY-MM-DD).
      - `valid_to` string: Last date the body is computed (YYYY-MM-DD).
    - `patterns_by_type` object: Patterns organized by type for easier filtering
    - `planets` object, required: Planetary positions keyed by name
    - `sect_determination` SectDeterminationResponse: Sect determination analysis.
      - `benefics_in_sect` string[], required: Benefics in proper sect
      - `is_day_chart` boolean, required: Is this a day chart
      - `malefics_in_sect` string[], required: Malefics in proper sect
      - `sect` string, required: Chart sect (diurnal/nocturnal)
      - `sect_conditions` object, required: Detailed sect conditions
      - `sect_light` string, required: Sect light (Sun for day, Moon for night)
      - `sun_above_horizon` boolean, required: Is Sun above horizon
    - `solar_relationships` object: Solar relationship / visibility classifications (e.g., cazimi/combust/under-beams) and Mercury/Venus morning/evening star context.
    - `subject` SubjectResponse, required: Normalized subject data in response.
      - `altitude` number, required: Altitude in meters
      - `datetime` string, required: ISO format datetime
      - `julian_day` number, double, required: Julian Day Number
      - `latitude` number, required: Latitude in decimal degrees
      - `longitude` number, required: Longitude in decimal degrees
      - `name` string, required: Subject name
      - `timezone_name` string: Timezone name if available
      - `utc_offset` number: UTC offset in hours
    - `success` boolean: Response success status
    - `visual` VisualResult: Embedded diagram payload returned alongside chart data when include_visual=true.
      - `content_type` string, required: MIME type of the data payload.
      - `credits_charged` integer, required: Additional credits consumed to render the visual: 2, or 0 on a re-render that presented a valid render_token.
      - `data` string, required: Raw SVG string (format=svg) or standard base64-encoded PNG bytes (format=png, no data: URI prefix).
      - `format` string, required: Output format: "svg" or "png".
      - `render_token` string: Short-lived (15 min) token for re-rendering this same chart. Send it back in the X-OE-Render-Token header (or a top-level render_token body field) with a request for the same chart inputs — e.g. the same birth data in a different theme or layout — and that request is not charged again. Bound to your account and to the chart-defining inputs; any other request is charged normally.
      - `type` string, required: Diagram kind: "wheel" or "bodygraph".
    - `void_of_course` object: Void-of-Course Moon context (status, start/end window, last major aspect, sign context) (opt-in).
  - `metadata` EnhancedResponseMetadata: Standardized metadata for enhanced envelope responses.
    - `calculation_time_ms` number: Observed calculation time including enrichment steps (milliseconds)
    - `calculation_time_seconds` number: Observed calculation time expressed in seconds for readability
    - `processing_time_ms` number: End-to-end processing time reported by the orchestrator (milliseconds)
  - `output_mode` string: Output projection mode (full | simple | llm)
  - `schema_version` string: Schema version for the selected output mode (e.g., full_v1, simple_v1, llm)
  - `success` boolean: Response success status

## Other responses

- `400`: Bad Request - Input validation failed
- `422`: Unprocessable Entity - Invalid input format
- `429`: Rate Limit Exceeded - Too many requests
- `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)