Electional Astrology API: Automated Timing for Weddings, Surgery, Business

An electional consultation runs $300-$800. The astrologer spends 1-4 hours checking candidate moments by hand: Is Venus retrograde? Is the Moon void of course? What sign is rising? What about eclipses?

Nobody else has built this. We checked.

What is electional astrology?

Electional astrology is picking the right time to start something. A wedding. A business. A surgery. A contract signing.

Professional astrologers have done this work manually for centuries. They cast charts for hundreds of possible moments, weigh dozens of factors, and narrow it down. It works. It's also slow and expensive.

The problem: desktop software from the 1990s

The tools electional astrologers use today are old. Solar Fire runs on Windows. Janus 6 looks like it was built when Clinton was president. Neither has an API. Neither scores anything. You get a chart, and you interpret it yourself.

Web tools like Astro-Seek give you a basic electional search, but it caps at 90 days, uses a black-box scoring system, and doesn't explain its results. You can't export anything. You can't integrate it.

If you're a developer building an astrology app, a wedding planning platform, or an AI agent that answers "when should I launch my business?" you have nothing to call.

We checked every astrology API. None has electional scoring.

This isn't speculation. We pulled OpenAPI specs, tested endpoints, and read documentation for every significant astrology API provider. Here's what we found:

Zero Western electional scoring APIs. The Vedic stack does muhurta, but that's a different system (sidereal zodiac, different criteria). And even the Vedic APIs return binary yes/no answers or unscored date lists.

The market is empty.

What does the Electional API actually do?

Three endpoints:

• A calendar heatmap with color-graded day scores
• Ranked top windows with individual 0-100 scores
• Excluded date ranges (eclipses, retrogrades) with explanations
• Natural language rationale per window

How does the scoring engine work?

Think of it like a weighted rubric. Each activity preset defines 31 factors with individual weights that sum to 100. For every candidate moment, each factor evaluator returns:

• A satisfaction score (0.0 to 1.0)
• An observation ("Moon in Cancer, domicile")
• A contribution to the final score

These raw values pass through saturation curves before weighted aggregation into the final 0-100 score. It's like grading a test where different questions have different point values.

Separately, 23 hard-stop checkers look for deal-breakers: eclipses, retrograde planets, void-of-course Moon, combust planets. A hard-stopped moment gets excluded entirely, with an explanation.

Here's the part professional astrologers care about: every recommendation comes with receipts. You can see exactly which factors pushed the score up and which dragged it down. Good luck getting that from Solar Fire.

How do you pick the best wedding date with astrology?

Wedding timing is the most common electional use case. Here's a real API request:

1{
2  "activity": "wedding",
3  "date_range": {
4    "start_date": {"year": 2026, "month": 6, "day": 1},
5    "end_date": {"year": 2026, "month": 8, "day": 31}
6  },
7  "location": {
8    "year": 2026, "month": 6, "day": 1, "hour": 12, "minute": 0,
9    "city": "New York", "country_code": "US"
10  },
11  "natal_chart": {
12    "name": "Anna",
13    "birth_data": {
14      "year": 1990, "month": 7, "day": 15, "hour": 14, "minute": 30,
15      "city": "New York", "country_code": "US"
16    }
17  },
18  "filters": {
19    "hours_from": 9,
20    "hours_to": 21,
21    "days_of_week": ["fri", "sat", "sun"]
22  },
23  "top_n_windows": 10
24}

The wedding preset automatically handles:

• Venus retrograde: hard stop. No wedding dates during Venus Rx.
• Void-of-course Moon: excluded. The Moon must be applying to aspects.
• Eclipses: excluded with asymmetric windows (solar eclipses get wider exclusion than lunar).
• Saturn return advisory: if the natal chart shows a Saturn return within the search range, you get a personal advisory even when the universal score is high.

The response includes a heatmap showing every day in June through August, ranked windows for the best weekend times, and a natural language rationale. Something like: "Strong Moon in Cancer (domicile), Venus direct in Taurus, no hard stops active. Jupiter trine to natal Venus adds personal support."

Building a wedding planning app? The heatmap is ready to render as a calendar UI. The scored windows are ready to display as a ranked list.

What is the Hippocratic rule for surgery timing?

This one has a safety requirement the API enforces.

The traditional rule (going back to Hippocrates, repeated by medieval astrologers like Culpeper) says: don't operate on a body part when the Moon is in the zodiac sign that rules it. Moon in Aries? Don't touch the head. Moon in Capricorn? Skip knee surgery.

1{
2  "activity": "surgery",
3  "date_range": {
4    "start_date": {"year": 2026, "month": 7, "day": 1},
5    "end_date": {"year": 2026, "month": 7, "day": 21}
6  },
7  "location": {
8    "year": 2026, "month": 7, "day": 1, "hour": 12, "minute": 0,
9    "city": "London", "country_code": "GB"
10  },
11  "extra_params": { "body_area": "knees" },
12  "filters": { "hours_from": 7, "hours_to": 11 },
13  "emergency_mode": false
14}

15 body areas are supported: head, face, neck, throat, arms, chest, heart, stomach, back, kidneys, reproductive, thighs, knees, calves, feet.

Does Mercury retrograde actually matter for contracts?

• Mercury conditions (retrograde = hard stop, combust = caution)
• Jupiter aspects for growth
• Moon phase (waxing preferred for new ventures)
• 10th house strength

All 12 activities: wedding, surgery, business_launch, contracts, real_estate, travel, legal, agriculture, building, investment, creative_launch, relocation.

How do you scan a whole year in under 2 seconds?

Scanning 90 days at 5-minute granularity means evaluating ~26,000 candidate moments. That's a lot of chart computation.

Pass 1 (heatmap): Score every day at noon. This gives a rough day-level grade, enough to identify which days are promising and which are blocked. Fast, because it's one computation per day.

Pass 2 (precision): Take the top N days from the heatmap and drill into each at the requested granularity. Weddings default to 15-minute windows, agriculture uses 1-hour. Score each candidate moment fully.

The results collapse adjacent high-scoring moments into windows with start/end times, durations, and a single representative score. Ties within 1 point go to the earlier window. Deterministic, not random.

Redis cache provides 430x speedup on repeat requests. Same request payload = same cache key = instant response.

Can AI agents call this API?

If you're building an AI assistant that answers timing questions, this is the backend.

How much does this cost compared to alternatives?

Desktop electional software costs $129-$299 as a one-time purchase. No API. No export. No scoring.

Professional electional consultations run $300-$800 each. The practitioner spends 1-4 hours.

Our API starts at $11/month for 1,000 requests. A single /search call replaces hours of manual work. The factor breakdown gives practitioners the same data they'd compute by hand. They review and refine instead of calculating from scratch.

Free tier: 50 requests/month. Enough to test every endpoint and preset.

Getting started

Three steps:

1. Sign up at astrology-api.io and get your API key
2. POST to /api/v3/electional/search with an activity and date range
3. Render the heatmap and scored windows in your app

The response is structured JSON. Heatmap days have grades. Windows have scores, factors, cautions, and rationale text. Everything you need to build a timing feature, no astrology knowledge required.