---
title: "Relocated Natal Angle Crossing Search"
method: POST
path: "/electional/natal-angle-crossings"
tags: ["electional"]
---

# Relocated Natal Angle Crossing Search

`POST /electional/natal-angle-crossings`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/electional/natal-angle-crossings`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Find the moments a transiting body is on a relocated natal angle (AC, DC, MC, or IC) at a geographic point P — "when is this body on MY relocated angle here". A relocated natal angle is a fixed zodiacal (ecliptic-longitude) degree, computed once from the natal instant at P via the same house calculation POST /ephemeris/relocation uses — not a horizon circle that sweeps with time, which is what GET /electional/angle-crossings answers for a bare geographic point instead.

Each result is an orb window: enter (body enters orb_deg of the angle), exact (the crossing moment), and leave (body exits orb_deg). A retrograde triple pass over the same angle produces three separate windows, one per pass, each with its own enter/exact/leave/retrograde — never a single window with multiple exacts. Ranges are capped at 366 days and are rejected rather than silently truncated.

**Pricing (by requested span, decided before any compute):** up to 1 month (31 days) = 5, up to 3 months (92 days) = 8, up to 6 months (183 days) = 10, up to 1 year (366 days) = 12 credits. The 366-day range limit applies on every plan. A span above your plan's limit is rejected with 400 `search_span_limit` naming the limit and the bracket that fits — nothing is charged. Any 4xx/5xx outcome is refunded, including a 429 compute_overload shed; rate-limit 429s are refused before anything is charged. Results are capped by `max_results` (reported as `truncated` in the summary).

## Query parameters

- `format` string

## Request body

- NatalAngleCrossingsRequest: Request payload for a relocated-natal-angle transit search.
  - `angles` string: Comma-separated angles: AC, DC, MC, IC. ASC/DSC are accepted as aliases. Defaults to all four. Vertex is not a valid value here.
  - `bodies` string: Comma-separated body names. Defaults to the classical seven (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn). Same vocabulary and aliases as GET /electional/angle-crossings.
  - `end` string, required: End of the search range, same datetime rules as start. A range over 366 days is rejected (400 `search_span_limit` for metered callers, 422 otherwise) rather than silently clamped.
  - `house_system` 'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W': Supported house systems.
  - `max_results` integer: Maximum number of windows to return.
  - `natal` NatalChartRequest, required: Request for natal chart calculation.
    - `configuration` NatalConfig: Declarative configuration for natal calculations.
      - `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.
      - `aspect_backing_discs` boolean, nullable: Wheel rendering only. When true (default), each aspect glyph sits on a small backing disc so it stays legible over crossing lines. Set false to draw bare glyphs. Honoured by /visualization/chart-wheel and /visualization/bi-wheel; rejected with 422 elsewhere.
      - `aspect_orbs` object: Caller-supplied orb allowances in degrees for the aspect lines drawn on the wheel, keyed by aspect name (conjunction, opposition, trine, square, sextile, and the minors quincunx, semisextile, semisquare, sesquiquadrate, quintile, biquintile). Same shape and semantics as ChartConfiguration.aspect_orbs: overrides the default table for the aspects named; aspects not named keep their defaults, and naming a minor is what turns it on. Setting an orb to 0 turns that aspect off entirely. An unknown aspect name is rejected with 422. Honoured by /visualization/chart-wheel and /visualization/bi-wheel (planet-to-planet lines; the include_angle_aspects lines keep their own table) and by /ephemeris/relocation (its aspect grid). /acg/midpoints, /ephemeris/natal/batch and /electional/natal-angle-crossings compute no aspect grid and reject the field with 422 rather than ignore it.
      - `asteroid_groups` AsteroidGroupEnum[]: Optional thematic asteroid groups to include alongside base object_set
      - `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.
      - `custom_objects` string[], nullable: Explicit body/point slugs to include, additive on top of object_set (and the entire set when object_set='custom'). Ephemeris bodies: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, north_node, true_node, lilith, lilith_true, chiron, pholus, lilith_interpolated, 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, anti_vertex, south_node, part_of_fortune, equatorial_ascendant (alias east_point), equatorial_descendant. Unknown slugs are ignored.
      - `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.
      - `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.
      - `show_aspect_glyphs` boolean, nullable: Wheel rendering only. When true (default), an aspect glyph is drawn at the midpoint of each aspect line. Set false to draw the lines alone. Honoured by /visualization/chart-wheel and /visualization/bi-wheel; rejected with 422 elsewhere.
      - `zodiac_type` 'tropical' | 'sidereal': Supported zodiac frameworks.
    - `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
  - `orb_deg` number, double: Orb, in degrees, used to compute each window's enter/leave bounds around the exact crossing. Defaults to 1.0.
  - `relocation_lat` number: Query point P latitude in decimal degrees (positive north). Required — omitting it is rejected, never defaulted to 0.
  - `relocation_lon` number: Query point P longitude in decimal degrees (positive east). Required — omitting it is rejected, never defaulted to 0.
  - `start` string, required: Start of the search range. ISO 8601 zoned datetime; a naive clock time is rejected rather than guessed at, and a bare date resolves to 12:00 UTC. Required — there is no sensible default window for a natal-specific search.

## Response `200`

Chronological relocated-natal-angle crossing windows

- NatalAngleCrossingsResponse
  - `search_summary` object, required: Echo of the resolved search plus provenance. calculation_mode is "Zodiacal (Relocated Natal Angles)" — the relocated angle is a fixed ecliptic-longitude degree for the whole search, distinct from GET /electional/angle-crossings' in-mundo geometry; the two calculation_mode strings never collide. When truncated is true the window list is NOT a complete chronological slice of the range — truncated_at_body, truncated_at_angle and omitted_bodies name what was left unsearched.
  - `windows` NatalAngleCrossingWindow[], required: Chronological orb-window passes across all requested bodies and angles.
    - `angle` 'AC' | 'DC' | 'MC' | 'IC', required: The relocated natal angle this pass crosses.
    - `body` string, required: Canonical transiting body name, e.g. Mars.
    - `enter` string, nullable: Moment the body enters orb_deg of the angle, UTC RFC 3339. Null when the local boundary search found no entry within its bounded horizon (e.g. a station keeps the body inside orb for an extended stretch) — omitted rather than guessed.
    - `exact` string, required: Exact crossing moment, UTC RFC 3339.
    - `leave` string, nullable: Moment the body leaves orb_deg of the angle, UTC RFC 3339. Same omission rule as enter.
    - `relocated_angle_deg` number, double, required: Fixed ecliptic longitude of the relocated natal angle for this search (same value /ephemeris/relocation returns for this natal + point).
    - `retrograde` boolean, required: True when the body is moving retrograde at the exact moment. A retrograde triple pass over the same angle produces three separate windows, one per pass — never a single window with multiple exacts.

## Other responses

- `422`: Validation 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)