---
title: "Calculate Solar Return Timing"
method: POST
path: "/predictive/returns/solar"
tags: ["predictive"]
---

# Calculate Solar Return Timing

`POST /predictive/returns/solar`

## Request

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

Calculate the nearest solar return timing (Sun returns to its natal longitude) near a target datetime.

## Query parameters

- `output_mode` string, nullable
- `format` string: Response format: json | llm.
- `include_aspects` boolean, nullable
- `include_hermetic_lots` boolean, nullable

## Request body

- AppApiModelsPredictiveSchemasSolarReturnRequest: Solar return timing request (body fixed to Sun).
  - `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` LocationInput: Geographic location with coordinates, elevation, and optional timezone.
    - `elevation` number: Elevation above sea level 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')
    - `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')
    - `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
  - `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).
  - `house_system` 'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W': Supported house systems.
  - `include_visual` boolean: If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.
  - `location` LocationInput: Geographic location with coordinates, elevation, and optional timezone.
    - `elevation` number: Elevation above sea level 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')
    - `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')
    - `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
  - `return_location` LocationInput: Geographic location with coordinates, elevation, and optional timezone.
    - `elevation` number: Elevation above sea level 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')
    - `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')
    - `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
  - `search_window_days` integer: Days to search symmetrically around target datetime (defaults depend on body)
  - `target_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
  - `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

- SolarReturnResponse: Response payload for solar return calculations.
  - `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
  - `chart` NatalChartResponse: Complete natal chart response (legacy contract).
    - `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
    - `aspects` AspectResponse[], required: Aspect list
      - `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` string, required: Calculation time (ISO)
    - `chart_type` string: Chart type identifier
    - `declination_aspects` DeclinationAspect[]: Parallel and contraparallel declination 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
    - `houses` HousesResponse, required: House system data in response.
      - `cusps` number[], required: House cusp longitudes in degrees
      - `system` string, required: House system code
    - `planets` object, required: Planetary positions keyed by name
    - `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
    - `summary` object, required: Summary metadata dictionary
  - `exact_datetime` string, date-time, required: Exact return datetime (UTC)
  - `location` ReturnLocation, required: Normalized location details echoed in return responses.
    - `elevation` number: Elevation above sea level 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` number, required: Latitude in decimal degrees
    - `longitude` number, required: Longitude in decimal degrees
    - `timezone` string: IANA timezone identifier
  - `metadata` PredictiveMetadata, required: Metadata for predictive calculation responses.
    - `accuracy_statement` string: Accuracy information
    - `cache_status` string: Cache hit/miss status
    - `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
    - `calculation_type` string, required: Type of calculation performed
    - `nasa_validated` boolean: NASA validation status
    - `performance_note` string: Performance information
    - `processing_time_ms` number, required: Processing time in milliseconds
    - `search_range_years` number: Years searched
  - `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, required: Request 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".

## Other responses

- `400`: Bad Request - Input validation failed
- `404`: Return not found within the specified search window (increase search_window_days)
- `422`: Unprocessable Entity - Invalid input
- `429`: Rate Limit Exceeded - Too many requests
- `500`: Internal Server 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)