---
title: "Find Electional Window"
method: GET
path: "/electional/find-window"
tags: ["electional"]
---

# Find Electional Window

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

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`).

## Query parameters

- `start_date` string
- `end_date` string
- `latitude` number
- `longitude` number
- `max_results` integer
- `avoid_voc` boolean
- `lunar_phase` string
- `avoid_retrograde` string
- `format` string

## Response `200`

Window search results

- ElectionalWindowResponse
  - `search_summary` object, required
  - `windows` ElectionalWindow[], required
    - `cautions` string[], nullable
    - `duration_minutes` number, required
    - `end_time` string, required
    - `key_factors` string[], nullable
    - `rank` integer, required
    - `rating` string, required
    - `score` integer, required
    - `start_time` string, required

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