What is electional astrology and how does this API automate it?

Electional astrology is choosing the best astrological moment to begin something important. Traditionally, astrologers spend 1-4 hours checking hundreds of candidate moments against weighted criteria. Our API automates the entire process: send an activity and date range, get back 0-100 scored windows with factor breakdowns and NL rationale in under 2 seconds. Three endpoints: /search for date ranges, /evaluate for single moments, /glossary for activity taxonomy.

What makes this different from Vedic muhurta APIs like Prokerala or KundliAPI?

Two fundamental differences. First, we do Western electional astrology (tropical zodiac, Placidus houses, traditional planetary dignities) while Prokerala/KundliAPI do Vedic muhurta (sidereal, Choghadiya, Tithi). Second, they return binary Auspicious/Inauspicious or flat date lists. We return 0-100 numeric scores with 31-factor breakdowns, calendar heatmaps, and NL rationale text. Nobody else offers factor receipts.

How much does the Electional Astrology API cost?

Free tier: 50 requests/month. Starter: $11/month for 1,000 requests. Professional: $37/month for 55,000 requests. Business: $99/month for 220,000 requests. Enterprise: $399+/month for unlimited. Compare to desktop electional software at $300-700 one-time, or professional electional consultations at $300-800 each.

How fast is the electional search for large date ranges?

A 90-day search completes in under 2 seconds at p95. A 367-day (max) search takes about 4-5 seconds. Single-moment /evaluate responds in under 300ms. Performance comes from the two-pass architecture: fast day-level heatmap first, then precision drill-down into top days only. Redis cache provides 430x speedup on repeated requests.

Which 12 activities does the electional API support?

Wedding, surgery, business_launch, contracts, real_estate, travel, legal, agriculture, building, investment, creative_launch, relocation. Each has professionally calibrated factor weights (summing to 100) and activity-specific hard-stop rules. Surgery requires body_area parameter. Agriculture integrates lunar mansions. Wedding includes Venus Rx and Saturn return advisory.

How does the surgery Hippocratic safety rule work?

When activity is 'surgery', you must provide extra_params.body_area (one of 15 areas: head, face, neck, throat, arms, chest, heart, stomach, back, kidneys, reproductive, thighs, knees, calves, feet). The API enforces the traditional rule: the Moon must not be in the zodiac sign ruling that body area. For emergencies, set emergency_mode: true to override hard stops with mandatory advisory text.

What is the calendar heatmap and how do I use it?

The heatmap is a day-by-day score summary for the entire search range. Each day gets a composite score (computed at noon) and a grade bucket (excellent/good/fair/poor/blocked). Render it as a color-coded calendar in your UI. Users see at a glance which weeks are favorable, then drill into specific days for detailed window recommendations.

What are factor receipts and why do they matter?

Each scored window includes a full factor-by-factor breakdown: 31 individual factor evaluations showing the factor name, satisfaction level (0.0-1.0), observation text, weight contribution, and status. This is like a receipt for the score. Professional astrologers can verify and defend every recommendation to their clients. No competitor provides this level of transparency.

How do I integrate the Electional API into my app?

Standard REST API. POST to /api/v3/electional/search with activity, date_range, and location. Response is JSON with heatmap, top_windows, excluded_ranges. For single-moment: POST to /evaluate. For UI dropdowns: GET /glossary/activities. SDKs for JavaScript, Python, PHP, Ruby. Most developers integrate the basic flow in under 1 hour.

Can I use this with AI agents and LLMs?

Yes, designed for it. The MCP find_best_time tool is already registered for AI agent integration with Claude, ChatGPT, and custom agents. Set summary_mode: true for compact output that fits chat context windows (top 3 windows + 1-line rationale). The /glossary/activities endpoint provides activity synonyms for LLM intent classification.

What is personal advisory and how does natal chart input work?

If you provide a natal_chart (birth data) in the request, two things happen: (1) a natal modifier adjusts universal scores by up to plus/minus 20% based on transits to natal planets, and (2) the PersonalAdvisory detector surfaces major personal transits (Saturn return, outer-planet hard aspects) even when the universal score is high. This prevents recommending a universally good date that is personally terrible.

What hard stops does the electional engine check?

23 dedicated hard-stop checkers evaluate: solar and lunar eclipses (asymmetric windows), Mercury/Venus/Mars retrograde periods, void-of-course Moon, combust planets, Moon-sign body-area conflicts (surgery), and activity-specific conditions. Hard-stopped moments are excluded entirely from results with explanations in the excluded_ranges array.

How accurate are the astronomical calculations?

Swiss Ephemeris JPL DE431 data with precision to 0.001 arc seconds. Same data source used by NASA. Planetary positions, aspects, lunar phases, eclipses, retrogrades, and ingresses are all computed from this gold-standard ephemeris. Three rounds of validation by working astrologers confirmed all factors return correct results.

Can I filter search results by time of day or day of week?

Yes. The filters parameter accepts hours_from and hours_to (e.g., 9-21 for daytime only), days_of_week (e.g., ['fri', 'sat', 'sun'] for weekend weddings), and exclude_dates for specific dates to skip. This dramatically narrows the search space and improves relevance.

What programming languages work with the Electional API?

Any language with HTTP support. Official SDKs for JavaScript/Node.js, Python, PHP, and Ruby. The API returns standard JSON. Most developers integrate with fetch/axios in frontend apps or requests/httpx in backend services. Full OpenAPI spec available for auto-generating clients in any language.

Is there a free tier for the Electional API?

Yes, 50 free requests every month. That is enough to test the full search and evaluate flow, explore all 12 activity presets, and prototype your integration before committing to a paid plan. The free tier includes all features - no feature gating.

How does the wedding preset handle Venus retrograde?

The wedding preset includes Venus retrograde as a hard stop - any moment during Venus Rx is excluded from results with an explanation. It also applies Saturn return advisory if the natal chart shows a Saturn return within the search range, and VOC Moon exclusion for ceremony timing. Venus dignity and lunar phase are among the highest-weighted factors.

Can I use the API for business launch timing?

Yes, the business_launch preset is one of 12 supported activities. It prioritizes Mercury conditions (avoiding retrograde and combust), Jupiter aspects for growth, Moon phase (waxing preferred), and 10th house strength. Hard stops include Mercury Rx, eclipses, and VOC Moon. The contracts preset is a separate option optimized specifically for signing agreements.

Electional Astrology

Find the Best Time for Anything. Scored 0-100.

First Western electional astrology REST API with numeric scoring.

Calendar heatmap, 12 activity presets, factor breakdown with receipts, NL rationale. No competitor offers this. Confirmed empty market.

View Documentation

0-100

Numeric Scoring

Activity Presets

Factor Evaluators

<2s

90-Day Search

First Western electional REST API

Swiss Ephemeris precision

MCP-ready for AI agents

Desktop-only tools (Solar Fire, Janus): no API, no scoring, 1990s UI
Web tools (Astro-Seek): black-box scoring, 90-day max, no export
Vedic APIs (Prokerala, KundliAPI): binary Auspicious/Inauspicious only, no Western
KundliAPI returns flat date lists with no scores, no heatmaps, no rationales
No existing API returns factor breakdowns, NL rationale, or calendar heatmaps

Transform with

0-100 numeric scoring with transparent factor-by-factor receipts
Calendar heatmap for visual date-range scanning at a glance
12 activity presets: wedding, surgery, business, contracts, travel, and more
Natural language rationale per window: "why this time is good"
MCP-callable find_best_time tool for AI agents and LLM integration

Electional API Performance

Built for production, validated by astrologers

0-100

Scoring Range

Activity Presets

31 + 23

Factors + Hard Stops

<2 seconds

90-Day Search

<300ms

Single Evaluate

293 tests

Test Coverage

Complete Electional Astrology Features

31 factors, 23 hard stops, 12 presets, 3 endpoints

Date-Range Search

Single-Moment Evaluate

12 Activity Presets

Scoring Engine

AI & LLM Integration

What Is Electional Astrology API? Complete Developer Guide

The first REST API for finding astrologically optimal times - with actual scores

What is electional astrology? It is the ancient practice of choosing the best moment to start something important - a wedding, surgery, business launch, contract signing. Professional astrologers charge $300-$800 per electional consultation, spending 1-4 hours manually checking hundreds of candidate moments. Our Electional Astrology API is the first REST endpoint that automates this entire process with structured JSON output. You send an activity and date range, you get back a 0-100 score for every candidate moment, a calendar heatmap showing good vs bad days at a glance, a factor-by-factor breakdown showing exactly why each score is what it is, and natural language rationale text ready to display to users. No other API provider offers Western electional scoring - we checked Solar Fire, Janus, AstroApp, Prokerala, AstrologyAPI.com, KundliAPI, VedicRishi. All confirmed gap. The Vedic stack returns binary muhurta classifications, not numeric scores. This is a genuinely empty market.

How does the Electional Astrology API work?

Three endpoints power the entire system.

POST /search accepts an activity (like 'wedding'), a date range (up to 367 days), and a location.

It runs a two-pass search: first a fast day-level heatmap pass scoring every day at noon, then a precision pass drilling into the top days at configurable granularity (down to 1-minute windows).

The result is a calendar heatmap with color-graded days, ranked top windows with individual scores, excluded date ranges (eclipses, retrogrades, etc.) with explanations, and NL rationale per window.

POST /evaluate scores a single specific moment - perfect for 'is this date good?' checks.

GET /glossary/activities returns the 12 supported activities with synonyms for LLM intent matching and UI dropdowns.

Two-pass search: heatmap first, then precision drill-down into top days

1 min read

What makes this electional API unique?

Five things no competitor offers: (1) 0-100 numeric scoring with saturation curves - not binary yes/no, not vague 'good/bad'.

(2) Calendar heatmap - visual day-by-day grading for an entire date range.

(3) Factor-by-factor breakdown ('receipts') - every score comes with 31 individual factor evaluations showing satisfaction level, observation, and contribution to the final score.

Professional astrologers can defend every recommendation.

(4) Natural language rationale - machine-generated English explanations per window, ready to display to users or feed to LLMs.

(5) Activity-based presets with tuned weights - a wedding election prioritizes Venus conditions differently than a surgery election.

Each of the 12 presets has professionally calibrated weights that sum to 100.

Only API with numeric scoring + heatmap + factor receipts + NL rationale

1 min read

Which activities does the Electional API support?

12 presets at launch: wedding, surgery, business_launch, contracts, real_estate, travel, legal, agriculture, building, investment, creative_launch, relocation.

Each preset defines its own factor weights and hard-stop rules.

Surgery has unique Hippocratic safety: it requires a body_area parameter (15 areas: head, face, neck, throat, arms, chest, heart, stomach, back, kidneys, reproductive, thighs, knees, calves, feet) and enforces the traditional Moon-in-sign rule where the Moon must not be in the sign ruling the body part being operated on.

Wedding includes Venus retrograde avoidance, Saturn return advisory, and VOC Moon exclusion.

Agriculture integrates lunar mansions.

Each activity is documented in the /glossary/activities endpoint.

12 activity presets with activity-specific safety rules and factor weights

1 min read

How does the scoring engine work under the hood?

Each preset defines 31 factors with individual weights that sum to 100.

For each candidate moment, every factor evaluator returns a satisfaction score (0.0-1.0), an observation string, and optional details.

These raw satisfactions pass through saturation curves (configurable per preset) before weighted aggregation into a final 0-100 score.

Hard stops are checked separately by 23 dedicated checkers: eclipses, retrograde planets, void-of-course Moon, combust planets, and activity-specific conditions.

A hard-stopped moment gets excluded entirely with an explanation.

If a natal chart is provided, a natal modifier (clamped at plus or minus 20%) adjusts the universal score, and the PersonalAdvisory detector surfaces major transits like Saturn return even when the universal score is high.

31 factors with saturation curves + 23 hard-stop checkers per moment

1 min read

How do I integrate the Electional API?

Standard REST.

Send a POST to /api/v3/electional/search with your activity, date range, and location.

Get back JSON with heatmap, top_windows, excluded_ranges, and summary.

For single-moment checks, POST to /evaluate.

For UI dropdowns or LLM intent matching, GET /glossary/activities returns all 12 activities with synonyms.

Optional parameters: natal_chart for personalized scoring, filters for time-of-day and day-of-week restrictions, summary_mode for compact LLM-friendly output, emergency_mode for surgery when the procedure cannot wait.

The API is designed to be MCP-callable - the find_best_time tool is already registered for AI agent integration.

3 endpoints, MCP-ready, LLM-friendly summary_mode

1 min read

Who uses the Electional Astrology API?

Four primary segments: (1) Astrology app developers building timing features - the heatmap and scored windows are ready-to-render UI data.

(2) Wedding and event platforms adding astrological date recommendations - the wedding preset handles Venus Rx, eclipses, VOC Moon, and Saturn return automatically.

(3) AI agent builders using MCP tools - the find_best_time tool works out of the box with OpenAI/Anthropic function calling.

(4) Professional astrologers scaling their practice - instead of 1-4 hours per consultation, get instant scored results with factor receipts to review and present to clients.

The API handles the computation; the astrologer provides the expertise and personal touch.

1 min read

Use Cases

Wedding & Event Planning Apps

Recommend optimal wedding dates with Venus/Moon analysis, Saturn return advisory, eclipse avoidance. Factor receipts explain every recommendation.

AI Agent Integration (MCP)

MCP find_best_time tool for ChatGPT, Claude, and custom AI agents. Summary mode returns compact JSON for chat context windows.

Surgery Scheduling Tools

Hippocratic safety with 15 body areas. Moon-sign rule enforcement. Emergency mode override with mandatory advisory text.

Business Launch Platforms

Mercury retrograde avoidance, VOC Moon exclusion, Jupiter aspect optimization for business timing.

Professional Astrologer Dashboards

Factor-by-factor receipts let astrologers verify and present scored results to clients. 1-4 hours of work in under 2 seconds.

Real Estate & Legal Timing

Contract signing, property purchase, court filing optimization with activity-specific presets.

Technical Specifications

Endpoints	3 (search, evaluate, glossary)
Scoring Range	0-100 numeric with saturation curves
Activity Presets	12 (wedding, surgery, business, contracts, etc.)
Factor Evaluators	31 per-factor evaluations per moment
Hard-Stop Checkers	23 dedicated exclusion checkers
Search Range	Up to 367 days per request
Search Speed	<2s for 90-day search (p95)
Evaluate Speed	<300ms single-moment scoring
Granularity	1-minute to 60-minute configurable
Surgery Safety	Hippocratic body-area Moon-sign rule (15 areas)
Personal Advisory	Saturn return, outer-planet hard transits to natal
Output	Heatmap + ranked windows + excluded ranges + NL rationale
MCP Integration	find_best_time tool registered
Ephemeris	Swiss Ephemeris JPL DE431
Cache	Redis per-event-loop pool, 24h TTL, 430x warm speedup

Electional API vs Competitors

Feature	Astrology API	Others
Western Electional Scoring	0-100 numeric	None (Solar Fire: Boolean, Vedic: binary)
Calendar Heatmap	Day-by-day graded	Not available
Factor Breakdown	31 factors with receipts	Not available
NL Rationale	Per-window English text	Not available
Activity Presets	12 with tuned weights	KundliAPI: 9 (Vedic only, no scores)
API Access	REST JSON API	Desktop only or Vedic-only API
Search Range	Up to 367 days	90 days max (web tools)
Surgery Safety	Hippocratic 15-area rule	Not available
MCP/LLM Ready	Built-in tool + summary_mode	Not available
Price	From $11/month	$300-700/month (desktop software)

Related Astrology APIs

Transit API

Real-time planetary transits powering the electional factor evaluators

Planetary Hours API

Traditional planetary hours - one of the 31 electional factors

Horary API

Question-based astrology sharing the same computational engine

Natal Chart API

Birth charts for personalized electional scoring

API Documentation

Complete endpoint reference with request/response examples

References & Standards

Swiss Ephemeris (DE431-based) — astronomical calculations source
NASA JPL Planetary Ephemerides — underlying ephemeris dataset
International Astronomical Union (IAU) — body designation and nomenclature standards
IANA Time Zone Database — timezone & DST resolution

Simple, Transparent Pricing

Start free, scale as you grow. No hidden fees, no surprises.

Always Free

Start Free

Perfect for learning, testing, and small personal projects

50 API calls/month

Basic natal charts

5 house systems

Community support

Pro

$11/month

For small apps and personal projects

All basic endpoints
12 house systems
Email support

Best Value

Pro Plus

$21/month

For growing apps and medium traffic

All enhanced endpoints
18 house systems
AI interpretations
Priority email support

Ultra

$37/month

For professional astrology applications

Credit math ↓

All premium endpoints
23 house systems
Advanced AI interpretations
Priority support

High Volume Plans

For enterprise-scale applications

Business

$99/month

For high-volume applications

Credit math ↓

ALL endpoints
White-label ready
Custom AI fine-tuning
Phone support

UNLIMITED

Enterprise

$399+per month

Unlimited requests with dedicated infrastructure

Dedicated server infrastructure
Sub-300ms guaranteed
24/7 dedicated support
99.99% uptime SLA

All plans include comprehensive documentation and SDKs

Questions? Talk to our team

Frequently Asked Questions About Electional Astrology API

Technical answers for developers building timing features

Complete Your Astrology Timing Stack

Electional API works best combined with our other timing and calculation tools.

Transit API Planetary Hours Horary API Natal Chart API Lunation API

Start Finding

First Western electional astrology REST API. 0-100 scoring, 12 presets, factor receipts. No competitor has this.

Start Free View Documentation

50 free requests/month

Swiss Ephemeris precision

No setup fees

Free tier includes all features

Find the Best Time for Anything. Scored 0-100.

No Western Electional API Exists

First Purpose-Built Electional REST API

Electional API Performance

Complete Electional Astrology Features

Date-Range Search

Single-Moment Evaluate

12 Activity Presets

Scoring Engine

AI & LLM Integration

What Is Electional Astrology API? Complete Developer Guide

How does the Electional Astrology API work?

What makes this electional API unique?

Which activities does the Electional API support?

How does the scoring engine work under the hood?

How do I integrate the Electional API?

Who uses the Electional Astrology API?

Use Cases

Wedding & Event Planning Apps

AI Agent Integration (MCP)

Surgery Scheduling Tools

Business Launch Platforms

Professional Astrologer Dashboards

Real Estate & Legal Timing

Technical Specifications

Electional API vs Competitors

Related Astrology APIs

Transit API

Planetary Hours API

Horary API

Natal Chart API

API Documentation

References & Standards

Simple, Transparent Pricing

Always Free

Pro

Pro Plus

Ultra

High Volume Plans

Business

Enterprise

Frequently Asked Questions About Electional Astrology API

What is electional astrology and how does this API automate it?

What makes this different from Vedic muhurta APIs like Prokerala or KundliAPI?

How much does the Electional Astrology API cost?

How fast is the electional search for large date ranges?

Which 12 activities does the electional API support?

How does the surgery Hippocratic safety rule work?

What is the calendar heatmap and how do I use it?

What are factor receipts and why do they matter?

How do I integrate the Electional API into my app?

Can I use this with AI agents and LLMs?

What is personal advisory and how does natal chart input work?

What hard stops does the electional engine check?

How accurate are the astronomical calculations?

Can I filter search results by time of day or day of week?

What programming languages work with the Electional API?

Is there a free tier for the Electional API?

How does the wedding preset handle Venus retrograde?

Can I use the API for business launch timing?

Complete Your Astrology Timing Stack

Start Finding

No Western Electional API Exists

First Purpose-Built Electional REST API

Electional API Performance

Complete Electional Astrology Features

Date-Range Search

Single-Moment Evaluate

12 Activity Presets

Scoring Engine

AI & LLM Integration

What Is Electional Astrology API? Complete Developer Guide

How does the Electional Astrology API work?

What makes this electional API unique?

Which activities does the Electional API support?

How does the scoring engine work under the hood?

How do I integrate the Electional API?

Who uses the Electional Astrology API?

Use Cases

Wedding & Event Planning Apps