Eclipse API: Build Solar and Lunar Eclipse Features for Your App (2026 Data)

Your users are asking: "When's the next eclipse? Will it affect me?"

Eclipses drive massive engagement. Co-Star sends 50 million push notifications during eclipse season. The Pattern sees 3x daily active users. Astrology apps that track eclipses convert better than those that don't.

But calculating eclipses is hard. You need NASA ephemeris data, Saros cycle tracking, zodiac positions, and personalized natal chart analysis. Building this from scratch takes months.

Or you can add it in 30 minutes with an API.

TL;DR - What You Need to Know

Eclipse calculations require:

• Swiss Ephemeris data (NASA-level precision)
• Saros series tracking (18-year cycles)
• Zodiac position calculations
• Natal chart aspect analysis
• Multi-language interpretations

Building from scratch: 3-6 months. Using an API: 30 minutes.

• For astrologers: Automate eclipse season prep for thousands of clients
• For app builders: Eclipse notifications drive 3x engagement
• For entrepreneurs: Users search "eclipse 2026" 500K+ times per month
• Saros cycles: Eclipses repeat every 18 years 11 days - same family, similar themes

Why Eclipses Matter for Astrology Apps

Eclipses aren't just cool astronomical events. They're the biggest engagement drivers in astrology.

Here's the data:

• "Solar eclipse 2026" - 500K+ monthly searches (peaks at millions during events)
• "Eclipse meaning astrology" - 150K+ monthly searches
• "Will eclipse affect me" - 90K+ monthly searches

• Push notifications during eclipses: 3-5x higher open rates
• Eclipse-related content: 2x longer session duration
• Users who check eclipse features: 40% higher retention

Your users want to know:

1. When's the next eclipse?
2. What sign is it in?
3. How will it affect MY chart?

An Eclipse API answers all three.

Understanding Eclipse Types

Before diving into the API, let's clarify what we're calculating.

Solar Eclipses

The Moon passes between Earth and Sun. There are four types:

Lunar Eclipses

Earth passes between Sun and Moon. Three types:

Astrological Impact Levels

The API classifies each eclipse's impact:

The Saros Cycle: Eclipse Families

Here's something most apps miss: eclipses come in families.

The Saros cycle is 6,585.32 days (about 18 years, 11 days, 8 hours). Eclipses in the same Saros series share similar themes and occur at nearly the same zodiac degree.

Babylonian astronomers discovered the Saros cycle around the 7th-8th century BCE. They kept meticulous astronomical records on clay tablets for centuries, eventually recognizing this repeating pattern. The name "saros" was applied by Edmond Halley in 1686.

The cycle works because it harmonizes three lunar periods: 223 synodic months, 239 anomalistic months, and 242 draconic months all equal approximately the same duration. Each Saros series typically lasts 12-13 centuries and contains 70+ eclipses.

Because the Saros isn't exactly 18 years, each subsequent eclipse shifts approximately 120 degrees westward. This means a Saros series returns to the same geographic region every 3 cycles (about 54 years) - called an "exeligmos" or "turn of the wheel."

When an eclipse happens, you can tell users:

• "This eclipse belongs to Saros 121, which started in 944 CE"
• "The last eclipse in this family was September 2007"
• "Saros 121 themes: social innovation, collective change, progressive reform"

This depth separates serious astrology apps from basic calendar tools.

Eclipse API Endpoints

The API provides three main endpoints for eclipse calculations.

1. Get Upcoming Eclipses

Returns the next N eclipses with complete astronomical and astrological data.

1const response = await fetch('https://api.astrology-api.io/v3/eclipses/upcoming?count=5', {
2  headers: { 'X-Api-Key': 'your-api-key' }
3});
4
5const data = await response.json();
6// Returns next 5 eclipses with full details

• NASA format eclipse ID (e.g., "2026Feb17P")
• Exact date and time (UTC)
• Eclipse type (solar_partial, lunar_total, etc.)
• Saros series number and member number
• Zodiac position (sign, degree, minute)
• Magnitude (how much of Sun/Moon is covered)
• Duration in minutes (for lunar eclipses)
• Visibility regions
• Astrological impact level
• Keywords for the eclipse

2. Check Natal Chart Impact

The real value: personalized eclipse analysis.

1const response = await fetch('https://api.astrology-api.io/v3/eclipses/natal-check', {
2  method: 'POST',
3  headers: {
4    'X-Api-Key': 'your-api-key',
5    'Content-Type': 'application/json'
6  },
7  body: JSON.stringify({
8    birth_date: '1990-05-15',
9    birth_time: '14:30',
10    birth_location: 'New York, NY',
11    orb: 3  // degrees of orb for aspects
12  })
13});

• Which natal planets the eclipse aspects
• Which houses are activated
• Aspect type (conjunction, opposition, square, trine, sextile)
• Strength of the impact
• Personalized interpretation

3. Get Eclipse Interpretation

Full astrological interpretation in 12+ languages.

1const response = await fetch('https://api.astrology-api.io/v3/eclipses/interpretation', {
2  method: 'POST',
3  headers: {
4    'X-Api-Key': 'your-api-key',
5    'Content-Type': 'application/json'
6  },
7  body: JSON.stringify({
8    eclipse_id: '2026Feb17P',
9    language: 'en'  // Also: es, ru, zh, hi, fr, de, pt, it, tr, uk, ar
10  })
11});

Actual API Response Example

1{
2  "eclipses": [
3    {
4      "eclipse_id": "SE2026Feb17A",
5      "date": "2026-02-17T12:13:06Z",
6      "type": "solar_annular",
7      "zodiac_position": {
8        "sign": "Aquarius",
9        "degree": 28,
10        "minute": 45,
11        "exact_degree": 28.75
12      },
13      "saros": {
14        "series": 121,
15        "member": 62,
16        "total_eclipses_in_series": 71,
17        "started": "0944-01-25",
18        "ends": "2206-04-13",
19        "theme": "Social innovation, collective evolution"
20      },
21      "magnitude": 0.9631,
22      "duration_minutes": null,
23      "visibility": ["Antarctica", "South America", "Africa"],
24      "astrological_impact": "strong",
25      "keywords": ["innovation", "community", "sudden change", "freedom"],
26      "calculated_at": "2026-01-06T10:00:00Z",
27      "ephemeris_source": "Swiss Ephemeris DE431"
28    }
29  ],
30  "calculation_time_ms": 47,
31  "precision": "0.001 arcsecond"
32}

According to our API calculations, the February 2026 annular eclipse falls at exactly 28 degrees 45 minutes Aquarius - the anaretic (29th) degree zone, which traditional astrologers consider a point of culmination and urgency.

2026 Eclipse Calendar: Complete Data

Here's what the API returns for 2026 eclipses.

February 17, 2026 - Annular Solar Eclipse

• Type: Solar Annular ("Ring of Fire")
• Zodiac: Aquarius 28 degrees 45 minutes
• Saros: 121 (member 62)
• Visibility: Antarctica, South America, Southern Africa
• Magnitude: 0.963

The Moon will be near its farthest point from Earth, creating the famous "ring of fire" effect where the Sun's edge remains visible around the Moon's silhouette.

This eclipse falls at the anaretic degree (29th degree, rounded). In traditional astrology, this is the "degree of fate" - representing culmination, urgency, and karmic completion.

Aquarius themes: innovation, freedom, community, progressive change.

Saros 121 themes: social innovation, collective evolution, humanitarian advancement.

"This Solar Eclipse in Aquarius brings innovation and humanitarian ideals to the forefront. Join with others who share your vision for positive change. Technology and progressive ideas are highlighted."

March 3, 2026 - Total Lunar Eclipse

• Type: Lunar Total
• Zodiac: Virgo 12 degrees 52 minutes
• Saros: 123 (member 56)
• Duration: 58 minutes
• Visibility: Americas, Europe, Africa

Lunar eclipses bring emotional revelations. Virgo lunar eclipses highlight:

• Health and daily routines
• Work and service
• Analysis and discernment
• Perfectionism that needs releasing

"This Lunar Eclipse in Virgo brings emotional clarity through analysis and practical service. Health matters or daily routines may require attention. Perfectionist tendencies need balance with self-acceptance."

August 12, 2026 - Total Solar Eclipse

• Type: Solar Total
• Zodiac: Leo 20 degrees 2 minutes
• Saros: 126 (member 47)
• Duration: 2 minutes 18 seconds (maximum)
• Visibility: Greenland, Iceland, Spain, Portugal, Russia

This will be the first total solar eclipse visible from mainland Europe since August 11, 1999 - a 27-year gap. For Iceland, it's the first since 1954, with the next not occurring until 2196.

Best viewing locations in Spain include León, Burgos, Valladolid, and Valencia - cities showing 68-78% average August sunshine. The eclipse occurs about 1 hour before sunset, with the Sun approximately 10 degrees above the horizon.

Leo solar eclipses ignite:

• Creative self-expression
• Heart-centered leadership
• Recognition and confidence
• Joy and authenticity

Saros 126 themes: creative transformation, authentic expression, confidence building.

August 28, 2026 - Partial Lunar Eclipse

• Type: Lunar Partial
• Zodiac: Pisces 5 degrees
• Saros: 128 (member 52)
• Visibility: Americas, Europe, Africa, Asia

Pisces lunar eclipses heighten:

• Spiritual sensitivity
• Compassion and empathy
• Intuitive gifts
• Release of illusions

Building Eclipse Features: Real Examples

Here's how to actually use this in your app.

Example 1: Eclipse Notification System

1async function checkUpcomingEclipses() {
2  const eclipses = await getUpcomingEclipses(3);
3
4  for (const eclipse of eclipses) {
5    const daysUntil = daysBetween(new Date(), new Date(eclipse.date));
6
7    if (daysUntil === 7) {
8      sendNotification({
9        title: `${eclipse.type} Eclipse in 1 Week`,
10        body: `${eclipse.zodiac_position.sign} eclipse on ${formatDate(eclipse.date)}. ${eclipse.keywords.slice(0, 3).join(', ')}.`,
11        data: { eclipse_id: eclipse.eclipse_id }
12      });
13    }
14  }
15}

Example 2: Personal Eclipse Impact

1async function getMyEclipseImpact(userId) {
2  const user = await getUser(userId);
3  const birthData = user.birth_data;
4
5  const impact = await checkNatalImpact({
6    birth_date: birthData.date,
7    birth_time: birthData.time,
8    birth_location: birthData.location,
9    orb: 3
10  });
11
12  return {
13    affected_planets: impact.natal_activations,
14    houses_activated: impact.houses,
15    interpretation: impact.personalized_reading,
16    intensity: impact.overall_impact
17  };
18}

Example 3: Eclipse Calendar View

1async function buildEclipseCalendar(year) {
2  const eclipses = await getUpcomingEclipses(10);
3
4  return eclipses
5    .filter(e => new Date(e.date).getFullYear() === year)
6    .map(eclipse => ({
7      id: eclipse.eclipse_id,
8      date: eclipse.date,
9      type: formatEclipseType(eclipse.type),
10      sign: eclipse.zodiac_position.sign,
11      degree: `${eclipse.zodiac_position.degree} degrees ${eclipse.zodiac_position.minute}'`,
12      saros: `Saros ${eclipse.saros_series}`,
13      impact: eclipse.astrological_impact,
14      keywords: eclipse.keywords
15    }));
16}

Eclipse and Natal Charts: The Deep Integration

The most valuable eclipse feature is natal chart analysis.

Natal Impact API Response Example

1{
2  "eclipse": {
3    "eclipse_id": "SE2026Aug12T",
4    "date": "2026-08-12T17:47:00Z",
5    "type": "solar_total",
6    "zodiac_position": {
7      "sign": "Leo",
8      "degree": 20,
9      "minute": 2
10    }
11  },
12  "natal_activations": [
13    {
14      "natal_planet": "Sun",
15      "natal_position": "Leo 18°45'",
16      "aspect": "conjunction",
17      "orb": 1.28,
18      "strength": "very_strong",
19      "interpretation": "This eclipse directly activates your core identity. Expect significant shifts in self-expression, confidence, and life direction over the next 6 months."
20    },
21    {
22      "natal_planet": "Mercury",
23      "natal_position": "Leo 22°10'",
24      "aspect": "conjunction",
25      "orb": 2.13,
26      "strength": "strong",
27      "interpretation": "Communication and thinking patterns undergo transformation. New ideas emerge that reshape your perspective."
28    }
29  ],
30  "houses_activated": [5, 11],
31  "overall_impact": "major",
32  "effect_duration": "6 months",
33  "calculation_time_ms": 89
34}

According to our calculations, when an eclipse falls within 1 degree of a natal planet (like the Sun conjunction above with 1.28 degrees orb), the effects are classified as "very strong" - typically correlating with memorable life events.

When an eclipse aspects your natal planets, something happens. The closer the aspect, the more intense.

Aspect Orbs (How Close is Close?)

House Activations

Eclipses activate houses in your chart based on where they fall:

1{
2  "house_activations": {
3    "1": "Personal identity and self-image transformation",
4    "2": "Values, finances, and self-worth shifts",
5    "3": "Communication, learning, and sibling dynamics",
6    "4": "Home, family, and emotional foundations",
7    "5": "Creativity, romance, and self-expression",
8    "6": "Health, work, and daily routines",
9    "7": "Partnerships and one-on-one relationships",
10    "8": "Shared resources, transformation, intimacy",
11    "9": "Higher learning, travel, philosophy",
12    "10": "Career, public image, authority",
13    "11": "Friends, groups, hopes and wishes",
14    "12": "Spirituality, endings, subconscious"
15  }
16}

A Critical View: The Eclipse Fear Industry

Let's be honest about something: modern astrology apps have turned eclipses into anxiety machines.

Co-Star sends 50 million push notifications during eclipse season. The Pattern teases "major life changes coming." Instagram astrologers warn about "eclipse portals" that will "destroy your relationships."

NASA is clear: there is no physical relationship between eclipses and your health, mood, or relationships. Astrology is not science. The Saros cycle is real astronomy - Babylonian astronomers discovered it through careful observation. But the "themes" of Saros series? Those are later cultural additions. There's no causal mechanism, no controlled studies, no evidence beyond anecdote and confirmation bias.

When apps send push notifications designed to spike anxiety - "Your chart is being ACTIVATED" - they're not helping users. They're manufacturing engagement through fear. The same psychological dark patterns we criticize in social media.

If you build eclipse features, build them responsibly. Educate users about the astronomy. Share the awe. But don't manufacture fear for engagement metrics.

What Science Actually Says About Eclipse Effects

For balanced coverage, here's what research has found:

NASA states there is "no physical relationship between a total solar eclipse and your health." Studies at psychiatric hospitals found no significant changes in patient behavior during eclipses. A 2018 review found no real association between eclipses and psychiatric disorders.

However, research from Johns Hopkins University analyzing 28 million Twitter posts during the 2017 eclipse found that people within the path of totality showed:

• More language expressing awe and unity
• Greater prosocial and affiliative behavior
• More humble and collective language

fMRI studies show that awe-inspiring experiences (like eclipses) dampen the brain's default mode network, reducing rumination and self-focus while increasing engagement and immersion - similar to flow states.

Real Use Cases

For Astrologers Going Digital

You've been manually tracking eclipses for years. Now you want to automate eclipse season prep for hundreds of clients.

Time saved: 20+ hours per eclipse season.

For Dating Apps

"Are we eclipse-compatible?" Users want to know if upcoming eclipses will affect their relationship.

For Wellness Apps

Eclipses correlate with energy shifts. Users track sleep, mood, and productivity changes.

For Content Platforms

Eclipse content goes viral. Publishers need accurate data fast.

Key Facts: Eclipse API at a Glance

FAQ

How accurate are the eclipse calculations?

The API uses Swiss Ephemeris, the same data NASA uses. Positions are accurate to 0.001 arc-second - that's professional astronomical precision. According to our benchmark tests, calculations complete in under 100ms.

How far in advance can I get eclipse data?

Currently returns eclipses through 2030. The Saros cycle allows accurate prediction centuries in advance.

What's the difference between solar and lunar eclipse interpretations?

Solar eclipses emphasize new beginnings, external events, conscious intentions. Lunar eclipses emphasize emotional processing, internal revelations, releasing patterns.

How do I know if an eclipse will affect someone's chart?

Use the natal-check endpoint with their birth data. The API calculates which natal planets are aspected by the eclipse within your specified orb.

Why does Saros series matter?

Eclipses in the same Saros family share similar themes and effects. If you experienced a major life event during Saros 121 eclipse in 2007, the 2026 Saros 121 eclipse may trigger related themes.

What about eclipse shadows and visibility?

The API returns visibility regions. While some astrologers believe you must see the eclipse for it to affect you, most modern astrologers consider eclipses globally relevant regardless of visibility.

How long do eclipse effects last?

Traditional rule: solar eclipses affect you for as many months as the eclipse lasts minutes. A 4-minute total solar eclipse = 4 months of influence. Lunar eclipses typically have shorter, more immediate effects.

Can I get eclipse data for past eclipses?

Yes. The API can retrieve historical eclipse data for research, validation, or showing users past eclipse patterns.

Conclusion

Eclipses drive engagement. Your users are searching for eclipse content. Apps that provide eclipse features see 3x engagement during eclipse season.

The calculations are complex: NASA ephemeris data, Saros tracking, zodiac positions, natal aspects. Building from scratch takes months.

Or you can add eclipse features in 30 minutes.

The next eclipse is coming. Will your app be ready?