Angle Crossing Search
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).
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
Query parameters
Query point latitude in decimal degrees (positive north).
Query point longitude in decimal degrees (positive east).
Start of the search range. ISO 8601 date or zoned datetime; a naive clock time is rejected rather than guessed at, and a bare date resolves to 12:00 UTC. Defaults to the start of the current UTC day.
End of the search range, same datetime rules as start. Defaults to 24 hours after start. A range over 366 days is rejected (400 search_span_limit for metered callers, 422 otherwise) rather than silently clamped.
Comma-separated body names. Defaults to the classical seven (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn). Accepts any standard ACG body plus the usual aliases (Rahu, Ketu, NorthNode). Vertex is not searchable here — it is derived from a natal birthplace.
Comma-separated angles: AC, DC, MC, IC. ASC/DSC are accepted as aliases. Defaults to all four.
Apply atmospheric refraction to the AC/DC horizon, matching the option of the same name on the ACG endpoints. Defaults to false (geometric horizon), so results align with default ACG lines.
Optional natal instant. When given, the bodies that /acg/ccg mode=ccg_hybrid secondary-progresses — Sun, Moon, Mercury, Venus, Mars and the lunar nodes — are progressed from it (day-for-a-year, the same formula and body set that endpoint draws with) while every other body stays a transit, so a returned moment sits on the PROGRESSED line the hybrid transit map paints rather than the transit line. Same datetime rules as start: a naive clock time is rejected, a bare date resolves to 12:00 UTC. Crossings of progressed bodies carry progressed: true, and search_summary.progression names the mode, the natal instant and the bodies progressed. Omit for the pure transit search.
Maximum number of crossing events to return. Defaults to 500 (a lean first page); may be raised to the 5000 ceiling. When the cap truncates the sweep, the response says so via truncated / truncated_at_body / truncated_at_angle / omitted_bodies rather than returning a list that looks complete.
Output format: json (default) or llm.
Response
Chronological angle-crossing events
Changes
No recorded changes to this operation across all 1 revision of this API.