---
title: "Calculate Sign Ingresses"
method: POST
path: "/predictive/transits/sign-ingresses"
tags: ["predictive"]
---

# Calculate Sign Ingresses

`POST /predictive/transits/sign-ingresses`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/predictive/transits/sign-ingresses`
- 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 planetary sign ingresses (when planets change zodiac signs).
    
    **Features:**
    - Sub-minute precision for ingress timing
    - Retrograde status detection
    - All traditional and modern planets
    - Batch processing for multiple planets
    
    **Performance:** <200ms for batch ingress calculations

## Request body

- SignIngressRequest: Request schema for sign ingress calculation.
  - `end_date` string, date-time: Search range end date (default: +1 year)
  - `planet_names` string[]: Specific planets (validated in route)
  - `start_date` string, date-time, required: Search range start date
  - `target_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces': Zodiac signs for ingress calculations.

## Response `200`

Successful Response

- SignIngressResponse: Response schema for sign ingress calculation.
  - `calculation_metadata` CalculationMetadata: Metadata about chart calculations. Relaxed to allow minimal fields used by tests while remaining forward-compatible.
    - `ascendant_on_left` boolean, nullable: When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.
    - `ayanamsa` union: Sidereal ayanamsa selection
      - 'lahiri' | 'fagan_bradley' | 'krishnamurti' | 'raman' | 'yukteshwar': Supported sidereal ayanamsa options. All five are computed from the same IAU 2006 general-precession model, so each is epoch-dependent rather than a frozen constant; they differ by up to ~2.3 degrees, which is enough to move a body across a sign boundary. Defaults to lahiri when zodiac_type is sidereal and no system is named.
      - string
    - `calculation_time` number: Legacy calculation time in seconds
    - `calculation_time_ms` number: Processing time at the orchestrator layer in milliseconds
    - `calculation_time_utc` string, date-time: UTC timestamp when the calculation executed
    - `coordinate_reference_frame` string: Coordinate frame the positions are expressed in. The engine computes apparent places referred to the true equator/equinox of date and converts them to the true ecliptic of date, so this reads geocentric_true_ecliptic_of_date.
    - `coordinate_system` union: Coordinate system used (geocentric/topocentric)
      - 'geocentric' | 'topocentric' | 'heliocentric' | 'barycentric': Coordinate system used for calculations.
      - string
    - `delta_t_seconds` number: Delta T (TT - UT1) applied during calculation, in seconds
    - `delta_t_source` union: Source of Delta T values (computation engine, IERS, approximation)
      - 'nasa_jpl' | 'iers' | 'approximation_model': Source of ΔT values used in calculations.
      - string
    - `ephemeris_source` string: Primary ephemeris source (e.g., SuperNOVAS / Calceph)
    - `ephemeris_version` string: Version of the ephemeris data files
    - `fixed_star_catalog` union: Fixed star catalog or subset identifier
      - 'bright_mag3' | 'bright_mag5' | 'royal_stars' | 'parans_key': Fixed star catalog snapshots.
      - string
    - `house_system` union: House system actually used during calculation
      - 'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W': Supported house systems.
      - string
    - `include_fixed_stars` boolean: Whether fixed stars were included
    - `julian_day` number, double: Julian Day Number representing the calculation instant
    - `missing_objects` object: Objects that could not be calculated along with reasons
    - `node_source` union: Lunar node/apsides mode requested (true osculating, mean, apsides)
      - 'true_osculating' | 'mean' | 'mean_apsides': Node/apsides calculation modes (SE §2.2).
      - string
    - `object_set` union: Named object set or preset powering the calculation
      - 'traditional_7' | 'modern_10' | 'modern_plus_chiron' | 'asteroids_major' | 'full' | 'custom': Standardized celestial object bundles.
      - string
    - `orb_system_used` string: Aspect orb system applied
    - `precision_level` string: Legacy precision descriptor
    - `precision_summary` PrecisionSummary: Structured precision report for calculation metadata.
      - `max_position_error_arcseconds` number: Maximum validated positional error in arcseconds
      - `max_timing_error_seconds` number: Maximum validated timing error in seconds
      - `notes` string: Additional human-readable context for the precision summary
      - `reference_profile` string: Reference dataset or validation profile used for the comparison
    - `processing_time_ms` number: End-to-end processing time in milliseconds
    - `server_version` string: Build identifier of the engine that produced this response. Moves on every deploy, so it is the signal for resolution-LOGIC changes — the class of change that can move a historical offset without touching overlay data (and therefore without moving tz_overlay_version). Poll both.
    - `sidereal_time` number: Local sidereal time in hours
    - `technique_id` string: High-level technique identifier (e.g., natal, synastry, composite, overlay)
    - `technique_label` string: Human-readable technique label
    - `technique_method` string: Method name within a technique (e.g., davidson, midpoint)
    - `technique_version` string: Technique implementation version (for future-proofing)
    - `time_scale` union: Time scale used for internal calculations (UTC, TT, TDB)
      - 'UTC' | 'TT' | 'TDB': Time scale used for reporting results.
      - string
    - `tz_overlay_hash` string: Content hash of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied (tz_rule_source starts with 'overlay:').
    - `tz_overlay_version` integer: Monotonic version of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied. Tracks overlay DATA only — pair with server_version to also catch resolution-logic changes.
    - `tz_precision` 'statutory' | 'documented' | 'inferred': Sourcing grade of the overlay row that produced the offset: 'statutory' (operative text of a session law or statute verified), 'documented' (contemporary reporting), or 'inferred' (deduced from legal context; verify before relying on it near the row's edges). Stamped only when an overlay row applied.
    - `tz_rule_citation` string: Primary-source citation for the overlay row that produced the offset — statute reference, ICC/agency order number, or documented press/almanac source. Stamped only when an overlay row applied.
    - `zodiac_type` union: Zodiac framework applied (tropical/sidereal)
      - 'tropical' | 'sidereal': Supported zodiac frameworks.
      - string
  - `ingresses` object, required: Ingresses grouped by planet name
  - `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
  - `success` boolean, required: Request success status
  - `total_count` integer, required: Total number of ingresses found

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