electional

Find Electional Window

Search a date range for the highest-scoring astrological timing windows. Evaluates moments in 1-hour steps, applies optional constraints (VOC avoidance, retrograde avoidance, lunar phase filter), and returns the top N ranked windows.

Pricing (by requested span, decided before any compute): up to 30 days (30 days) = 5, up to 60 days (60 days) = 8, up to 120 days (120 days) = 12 credits. Plan limits: Pro 30 days, Startup 60 days, Scale and above 120 days. An omitted end_date defaults to 30 days out and is clamped to your limit rather than rejected. 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. At most 20 windows are returned (max_results).

get/electional/find-window

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/electional/find-window
  • 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

start_datestring

Start of search range (ISO 8601 or YYYY-MM-DD). Defaults to today.

end_datestring

End of search range. Defaults to 30 days after start.

latitudenumber

Observer latitude (decimal degrees). With longitude, this determines chart sect at each step of the scan, so windows that straddle sunrise or sunset are scored under the sect actually in force. Omit either coordinate, or send an out-of-range pair, and every step falls back to diurnal — search_summary.sect_basis reports which branch ran.

longitudenumber

Observer longitude (decimal degrees). Required alongside latitude for sect: whether the Sun is above the horizon is a local fact and neither coordinate settles it alone.

max_resultsinteger

Maximum number of windows to return (1-20).

avoid_vocboolean

Exclude void-of-course Moon periods.

lunar_phasestring

Preferred lunar phase: waxing, waning, new, full, or any.

avoid_retrogradestring

Comma-separated planet names to exclude when retrograde, e.g. Mercury,Mars.

formatstring

Output format: json (default) or llm.

Response

Window search results

search_summaryobject required

Changes

No recorded changes to this operation across all 1 revision of this API.