---
title: "Angle Crossing Search"
method: GET
path: "/electional/angle-crossings"
tags: ["electional"]
---

# Angle Crossing Search

`GET /electional/angle-crossings`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/electional/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 at which bodies cross the Ascendant, Descendant, Midheaven, or Imum Coeli at a geographic point — the time-inverse of astrocartography. Where /acg/power-lines answers "what is angular here at time T", this answers "at what T is this body angular here".

Crossing times are solved on the same in-mundo (equatorial RA/Dec) geometry the ACG line engine draws, so casting the map at a returned moment places the corresponding line through the query point. Circumpolar cases — where a body never rises or never sets at that latitude — return no event rather than an error. Ranges are capped at 366 days and are rejected rather than silently truncated.

**Cost budget:** each body × angle × day is one closed-form root solve (~2 ms of compute). A single request may spend at most 15,000 units (bodies × angles × days); requests over budget are rejected with a 422 naming the arithmetic — reduce bodies, angles, or the date range and issue additional requests. The default body set (7) across all four angles supports a full 366-day range (7 × 4 × 366 = 10,248); 10 bodies × 4 angles × 366 days (14,640) is the widest full-year sweep. For long broad sweeps, slice the range into consecutive start/end windows — results are deterministic, so slices compose exactly.

**Concurrency & backpressure:** heavy endpoints (this one, /acg/*, heatmaps, /electional/find-window and station-tracker) share a per-machine pool of 4 compute slots. When all slots are busy a request waits up to 5 s for admission and is then shed with **429 + Retry-After: 5** (problem type problems/compute_overload) — honor Retry-After with bounded backoff. Admitted work is bounded by a 25 s compute deadline.

**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

- `latitude` number, double, required
- `longitude` number, double, required
- `start` string
- `end` string
- `bodies` string
- `angles` string
- `refraction_correction` boolean
- `natal_datetime` string
- `max_results` integer
- `format` string

## Response `200`

Chronological angle-crossing events

- ElectionalAngleCrossingsResponse
  - `crossings` ElectionalAngleCrossing[], required: Chronological crossing events across all requested bodies and angles.
    - `angle` 'AC' | 'DC' | 'MC' | 'IC', required: The angle the body reaches at this moment.
    - `body` string, required: Canonical body name, e.g. Mercury.
    - `body_dec` number, double: Declination in degrees at the crossing.
    - `body_longitude` number, double, required: Ecliptic longitude at the crossing.
    - `body_ra` number, double: Right ascension in hours at the crossing.
    - `daylight` boolean: True when the Sun is above the horizon.
    - `iso_time` string, required: Crossing moment, UTC, RFC 3339.
    - `jd` number, double, required: Crossing moment as a Julian Day.
    - `progressed` boolean: True when the body's position was secondary-progressed from natal_datetime (the ccg_hybrid set) rather than taken as a transit. Absent on a pure transit search.
    - `sun_altitude_deg` number, double: Sun's altitude at the query point at the crossing moment. Negative is night. Returned in place of a bare visibility flag so callers can apply their own twilight threshold.
  - `search_summary` object, required: Echo of the resolved search plus provenance. calculation_mode reports the geometry convention and matches /acg/power-lines exactly. When truncated is true the event list is NOT a complete chronological slice of the range — the sweep stopped part-way, so truncated_at_body, truncated_at_angle and omitted_bodies name what was left unsearched.

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