World Events Astrology

Track World Events With the Mundane Astrology API

One endpoint searches eight families of sky event across a five-year window: ingresses, stations, lunations, eclipses and Jupiter-Saturn conjunctions.

No birth chart. No natal data. Just the sky.

~20ms

Fastest Query (4 Ingresses)

Event Families

5 yrs

Max Search Window

Saros-tagged

Solar & Lunar Eclipses

Used by 2,800+ developers and astrologers

Ptolemy, Lilly & Barbault-sourced doctrine

Swiss Ephemeris precision

You need three separate calculations just for a year-ahead calendar: quarter ingresses from one service, lunations from another, eclipses from a third, then you merge and sort them yourself
Tracking outer-planet ingresses and stations over multiple years means writing your own ephemeris scan, and getting the sampling interval wrong either misses events or burns compute on redundant checks
Jupiter-Saturn conjunctions need historical context. Knowing a conjunction happened is easy. Knowing whether it changed triplicity from the previous one means hand-tracking a sequence going back decades
Eclipse data usually ships with only one Saros numbering, and if your audience uses the other one, you are stuck manually cross-referencing tables
None of this data says what it is not. A raw ephemeris scan cannot tell your UI that an in-progress retrograde was clipped by the search window instead of genuinely starting on day one

Build your world-events calendar with

POST a date window and the event types you want to /mundane/events/search. Ingresses, lunations and eclipses come back merged into one chronological list, no client-side sorting required
Outer-planet ingress and station scans over up to five years run server-side with per-body sampling already tuned, so a five-planet, five-year request costs about 400 ephemeris samples instead of a six-figure count
Every jupiter_saturn_conjunction event carries its own triplicity plus the previous conjunction's, with an is_triplicity_change flag computed by scanning back past your window automatically
Every eclipse names its Saros numbering explicitly (van den Bergh/NASA) so you never confuse it with the Jansky/Brady system your users might already know
Retrograde periods flag start_clipped and end_clipped separately, so your UI can say 'already in progress' instead of drawing a false start date

What the /mundane/events/search Endpoint Actually Does

Numbers from the endpoint itself, not marketing rounding

~20ms

Fastest Query (4 Cardinal Ingresses)

5 years (1,826 days)

Max Search Window

Event Types in One Call

~400 samples

5-Planet, 5-Year Ingress Scan

What Ships in the Mundane Events Search Endpoint

Eight event families, precise filters, and data that states its own limits

sign_ingress

Any body crossing any 30° sign boundary, tracked at full precision across years.

cardinal_ingress

The Sun opening a season. A separate doctrine from sign_ingress, defined only on the Sun.

station

A retrograde or direct turn, returned as a single instant.

retrograde_period

The same turns paired into a start/end interval, with clipped-period flags.

lunation

New, Full, and (optionally) first/last quarter Moons.

solar_eclipse & lunar_eclipse

Full Saros series, magnitude, and visibility-region data on every eclipse.

jupiter_saturn_conjunction

The historically-tracked Great Conjunction pair, with triplicity history.

Required event_types filter

Non-empty list; mix any of the eight families in a single request.

bodies parameter

Constrains sign_ingress, station, and retrograde_period to specific planets; defaults to the seven classical planets.

to_signs filter

Filters sign_ingress by the sign entered, never the sign left.

cardinal_points filter

Choose Aries, Cancer, Libra, Capricorn, or leave unset for all four.

lunation_phases filter

Defaults to New and Full Moon only; add first_quarter or last_quarter to widen it.

Five-year search window

date_from and date_to accept any span up to 1,826 days.

Saros series and member number

van den Bergh / NASA numbering, named explicitly in saros_numbering.

Stated magnitude convention

magnitude_kind marks nasa_solar vs. lunar_umbral so the two are never compared as equal.

Point-of-greatest-eclipse region

visibility_regions is a coarse label, not the full eclipse path.

Jupiter-Saturn triplicity history

Every conjunction carries its own element and the previous conjunction's.

is_triplicity_change flag

Computed by scanning back past your search window automatically.

datetime_is field

Names which of an eclipse's several defensible instants (greatest eclipse) was published.

is_chart: false on every event

These are moments, not charts; no houses, angles, or rulers are attached.

start_clipped / end_clipped

Marks retrograde periods already running at the edge of your search window.

nearest_syzygy_utc / phase

Cardinal ingresses carry the nearest New or Full Moon when lunation is also requested.

precision_seconds on every event

A number instead of an unsourced 'exact,' so you know the solver's tolerance.

Cost pre-check

Refuses an over-broad request in milliseconds with the sample count, instead of holding a worker.

warnings[UNKNOWN_FIELD]

Unrecognized request fields return 200 with a named warning, never a silent drop.

Discriminated union response

Each event's shape follows its event_type; no field is nullable-by-construction.

~20ms to ~2s response times

Fast for a simple ingress query, still sub-2-second for a five-year, five-body scan.

One flat events[] array

Sorted ascending by datetime_utc, ready to render as a timeline.

Swiss Ephemeris precision

Geocentric apparent frame, tropical zodiac only.

Full SDK support

JavaScript, Python, PHP, Ruby, Swift, Kotlin, plus plain REST.

Standard v3 response envelope

Same warnings and pagination behavior as every other endpoint on the platform.

What Is the Mundane Astrology API? A Guide to World-Events Search

How /mundane/events/search finds sky events without a birth chart

Mundane astrology reads the sky for the world instead of for a person. Where natal astrology casts a chart for someone's birth, mundane astrology tracks moments that belong to everyone: an equinox, an eclipse, a Great Conjunction. There is no subject, no birth time, and no house system tied to a specific location. The /mundane/events/search endpoint is built around that distinction. POST a date window and the event types you want, and it returns eight families of sky event: sign ingresses (any body crossing any 30-degree boundary), cardinal ingresses (the Sun opening a season), stations and retrograde periods, lunations, solar and lunar eclipses, and Jupiter-Saturn conjunctions. Every event comes back as is_chart: false, because these are moments, not charts. Erecting a mundane chart for a specific event needs a place on Earth, since the angles depend on latitude; this endpoint searches time, not place. That also means the API does not rank events by house or angle. The research on that question is genuinely mixed: Barbault's study of 404 ingress and lunation charts against war outbreaks found Mars angular 80 times against an expected 91, a null result the endpoint respects by not inventing a score. What it does do is search a five-year window in one call, sort every result chronologically, and tag each event with enough context (Saros series, triplicity, clipped-period flags) that you can build a calendar, a scheduler trigger, or a research dataset without cross-referencing three other endpoints.

Eclipse data is delegated to the same eclipse service the rest of the platform uses, not recomputed separately, so figures cannot drift between endpoints.

Every eclipse names its Saros numbering explicitly as van_den_Bergh, the NASA convention, because astrologers who track Saros families sometimes use the Jansky/Brady numbering instead, which can label the identical eclipse differently.

magnitude_kind states whether a magnitude value is nasa_solar or lunar_umbral, since the two conventions are not comparable and lunar_umbral is 0.0 for every penumbral eclipse by definition.

Jupiter-Saturn conjunctions run on Swiss Ephemeris positions and report triplicity, previous_triplicity, and is_triplicity_change, a literal element-changed flag rather than a doctrinal 'Great Mutation' judgment.

Every value states its own convention, so nothing is silently mixed

1 min read

What does the API deliberately not do, and why?

No houses, angles, rulers, or significance scores: every event returns is_chart: false, because a moment needs a place on Earth before it can become a chart, and this endpoint searches time only.

Tropical zodiac only: a sidereal solar ingress is a different event called a sankranti, and there is no equinox at 0-degree sidereal Aries, so the endpoint refuses sidereal requests rather than silently approximating one.

No mutation verdict beyond is_triplicity_change, since the tradition's Great Mutations are dated, contested single events, not every element change.

And unknown request fields never vanish quietly: the schema allows extra keys, and an unrecognized one returns HTTP 200 with a warnings[UNKNOWN_FIELD] entry naming it, so a typo in a field name is never indistinguishable from the option simply not existing.

No fabricated significance scores; if the endpoint does not know, it says so

1 min read

Who builds with the Mundane Astrology API?

Astrologer-entrepreneurs building mundane and financial-astrology tools use it to generate year-ahead calendars and flag triplicity shifts without hand-tracking conjunction history.

Content platforms and news or commentary sites pull the next eclipse or Great Conjunction into an article's context box without cross-referencing Saros tables themselves.

Researchers query multi-year windows of retrograde_period or jupiter_saturn_conjunction data to study cadence, Saros distribution, or element-shift frequency at scale.

Scheduler and notification systems fire a job the moment a station, ingress, or eclipse lands, filtering on one event_types list instead of merging three feeds.

This is deliberately not a personal-horoscope product; there is no subject field anywhere in the request.

Built for calendars, schedulers, and research datasets, not horoscope feeds

1 min read

Use Cases

Financial & Mundane Astrology Platforms

Build year-ahead calendars of ingresses, lunations and eclipses for subscriber-facing forecasts, with Jupiter-Saturn triplicity shifts flagged automatically.

News & Commentary Sites

Pull the next eclipse or Great Conjunction into an article's context box without hand-tracking Saros numbers or triplicity history.

Scheduler & Notification Systems

Fire a push notification or cron job the moment a station, ingress or eclipse lands, using one event_types filter instead of merging three feeds.

Academic & Independent Research

Pull five-year windows of retrograde_period or jupiter_saturn_conjunction data to study cadence, Saros distribution, or element-shift frequency at scale.

Astrologer Content Creators

Generate the quarter's cardinal ingress plus its nearest syzygy in one call for a seasonal reading, without separately querying a lunation endpoint.

Multi-Year Forecast Tools

Track outer-planet ingresses and stations for Jupiter through Pluto across a five-year horizon, the slow spine of any long-range mundane forecast.

Technical Specifications

Flagship Endpoint	POST /api/v3/mundane/events/search
Operation ID	mundane_events_search
Event Families	8: sign_ingress, cardinal_ingress, station, retrograde_period, lunation, solar_eclipse, lunar_eclipse, jupiter_saturn_conjunction
Max Search Window	5 years (1,826 days)
Fastest Response	~20ms (four cardinal ingresses)
Slowest Response	~2s (five years of ingresses, five bodies)
Default Bodies	Seven classical planets when bodies is omitted
Ingress Sign Filter	to_signs filters the sign entered (to_sign), never from_sign
Cardinal Point Filter	cardinal_points narrows to Ari / Can / Lib / Cap; default is all four
Lunation Phase Filter	lunation_phases; default is New and Full Moon only
Zodiac Frame	Tropical only (options.zodiac_type = Tropic)
Response Shape	Discriminated union on event_type, one flat events[] array
Chart Data	None. Every event returns is_chart: false
Ephemeris	Swiss Ephemeris, geocentric apparent
Saros Numbering	van den Bergh / NASA, named explicitly in saros_numbering
Eclipse Magnitude	magnitude_kind distinguishes nasa_solar from lunar_umbral
Retrograde Flags	start_clipped / end_clipped mark periods cut by the search window
Cost Pre-Check	Over-broad requests refused in milliseconds with the sample count
Unknown Fields	extra='allow'; returns 200 with warnings[UNKNOWN_FIELD], never silently dropped
Output Format	JSON, events sorted ascending by datetime_utc

Mundane Astrology API vs. Hand-Wiring Three Endpoints

Feature	Astrology API	Others
Ingresses + Lunations + Eclipses	One endpoint, one sorted list	Three separate calls, manual merge
Outer-Planet Multi-Year Scan	~400 samples for 5 planets over 5 years	You write and tune your own ephemeris scan
Jupiter-Saturn Triplicity History	previous_triplicity + is_triplicity_change computed automatically	You hand-track the conjunction sequence
Saros Numbering Clarity	van den Bergh / NASA stated explicitly	Numbering system often unstated
Retrograde In Progress	start_clipped / end_clipped flags	False start dates or dropped periods
Cardinal Year-Opening Doctrine	cardinal_points parameter, you choose Aries/Cap/Libra	One doctrine hard-coded
Unknown Request Fields	200 + warnings[UNKNOWN_FIELD]	Silently ignored or hard error
Response Time	~20ms for a simple ingress query	1-3 seconds
Price	$11/month for 1,000 requests	$99-299/month
Free Tier	50 requests/month, always free	50-100 or none

Related Astrology APIs

Transit Astrology API

Personal planetary timing for an individual chart, the natal counterpart to mundane's chart-free world events

Natal Chart API

Cast the birth chart a mundane forecast might layer against for personalized commentary

Horary Astrology API

Chart-based judgment for a single question, cast for the moment it is asked rather than a world event

Cazimi & Combust API

Planetary condition data that complements ingress and conjunction timing

Arabic Parts API

97+ traditional lots for deeper mundane and natal chart analysis

API Documentation

Complete technical reference

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

Mundane Astrology API FAQ

What happens if I send a field the API does not recognize?

Pricing

How much does the Mundane Astrology API cost?

Pricing

Is there a free tier for testing mundane event searches?

Complete Your World-Events Stack

Mundane Astrology API works best alongside our chart-based tools. Add

New: /mundane/events/search Ships 8 Event Families in One Call

Search the Sky. Not Three Separate APIs.

POST a date window. Get ingresses, stations, lunations, eclipses, and Great Conjunctions back as one sorted list, in under 2 seconds even across five years.

~20ms

Fastest Query

Event Families

5 yrs

Max Window

Start Free Now

30-day money-back guarantee

Free migration assistance

No setup fees

"We replaced three separate ingress, lunation, and eclipse calls with one /mundane/events/search request. Our year-ahead calendar feature shipped in a day instead of a sprint."

Elena R.

Founder, SkyCycles

Ship Your World-Events Calendar Today

Integration is typically under an hour. Every event family ships in the free tier.

What Is the Mundane Astrology API? A Guide to World-Events Search

How /mundane/events/search finds sky events without a birth chart

Use Cases

Financial & Mundane Astrology Platforms

Build year-ahead calendars of ingresses, lunations and eclipses for subscriber-facing forecasts, with Jupiter-Saturn triplicity shifts flagged automatically.

News & Commentary Sites

Pull the next eclipse or Great Conjunction into an article's context box without hand-tracking Saros numbers or triplicity history.

Scheduler & Notification Systems

Fire a push notification or cron job the moment a station, ingress or eclipse lands, using one event_types filter instead of merging three feeds.

Academic & Independent Research

Pull five-year windows of retrograde_period or jupiter_saturn_conjunction data to study cadence, Saros distribution, or element-shift frequency at scale.

Astrologer Content Creators

Generate the quarter's cardinal ingress plus its nearest syzygy in one call for a seasonal reading, without separately querying a lunation endpoint.

Multi-Year Forecast Tools

Track outer-planet ingresses and stations for Jupiter through Pluto across a five-year horizon, the slow spine of any long-range mundane forecast.

Technical Specifications

Flagship Endpoint	POST /api/v3/mundane/events/search
Operation ID	mundane_events_search
Event Families	8: sign_ingress, cardinal_ingress, station, retrograde_period, lunation, solar_eclipse, lunar_eclipse, jupiter_saturn_conjunction
Max Search Window	5 years (1,826 days)
Fastest Response	~20ms (four cardinal ingresses)
Slowest Response	~2s (five years of ingresses, five bodies)
Default Bodies	Seven classical planets when bodies is omitted
Ingress Sign Filter	to_signs filters the sign entered (to_sign), never from_sign
Cardinal Point Filter	cardinal_points narrows to Ari / Can / Lib / Cap; default is all four
Lunation Phase Filter	lunation_phases; default is New and Full Moon only
Zodiac Frame	Tropical only (options.zodiac_type = Tropic)
Response Shape	Discriminated union on event_type, one flat events[] array
Chart Data	None. Every event returns is_chart: false
Ephemeris	Swiss Ephemeris, geocentric apparent
Saros Numbering	van den Bergh / NASA, named explicitly in saros_numbering
Eclipse Magnitude	magnitude_kind distinguishes nasa_solar from lunar_umbral
Retrograde Flags	start_clipped / end_clipped mark periods cut by the search window
Cost Pre-Check	Over-broad requests refused in milliseconds with the sample count
Unknown Fields	extra='allow'; returns 200 with warnings[UNKNOWN_FIELD], never silently dropped
Output Format	JSON, events sorted ascending by datetime_utc

Mundane Astrology API vs. Hand-Wiring Three Endpoints

Feature	Astrology API	Others
Ingresses + Lunations + Eclipses	One endpoint, one sorted list	Three separate calls, manual merge
Outer-Planet Multi-Year Scan	~400 samples for 5 planets over 5 years	You write and tune your own ephemeris scan
Jupiter-Saturn Triplicity History	previous_triplicity + is_triplicity_change computed automatically	You hand-track the conjunction sequence
Saros Numbering Clarity	van den Bergh / NASA stated explicitly	Numbering system often unstated
Retrograde In Progress	start_clipped / end_clipped flags	False start dates or dropped periods
Cardinal Year-Opening Doctrine	cardinal_points parameter, you choose Aries/Cap/Libra	One doctrine hard-coded
Unknown Request Fields	200 + warnings[UNKNOWN_FIELD]	Silently ignored or hard error
Response Time	~20ms for a simple ingress query	1-3 seconds
Price	$11/month for 1,000 requests	$99-299/month
Free Tier	50 requests/month, always free	50-100 or none

Track World Events With the Mundane Astrology API

Building a Mundane Astrology Calendar From Scratch Is Three APIs Glued Together

One Endpoint, Eight Event Families, Already Sorted

What the /mundane/events/search Endpoint Actually Does

What Ships in the Mundane Events Search Endpoint

sign_ingress

cardinal_ingress

station

retrograde_period

lunation

solar_eclipse & lunar_eclipse

jupiter_saturn_conjunction

Required event_types filter

bodies parameter

to_signs filter

cardinal_points filter

lunation_phases filter

Five-year search window

Saros series and member number

Stated magnitude convention

Point-of-greatest-eclipse region

Jupiter-Saturn triplicity history

is_triplicity_change flag

datetime_is field

is_chart: false on every event

start_clipped / end_clipped

nearest_syzygy_utc / phase

precision_seconds on every event

Cost pre-check

warnings[UNKNOWN_FIELD]

Discriminated union response

~20ms to ~2s response times

One flat events[] array

Swiss Ephemeris precision

Full SDK support

Standard v3 response envelope

What Is the Mundane Astrology API? A Guide to World-Events Search

How does the /mundane/events/search endpoint work?

What are the eight mundane event families?

Why does cardinal_points let you choose which sign opens the mundane year?

How accurate are the eclipse and conjunction calculations?

What does the API deliberately not do, and why?

Who builds with the Mundane Astrology API?

Use Cases

Financial & Mundane Astrology Platforms

News & Commentary Sites

Scheduler & Notification Systems

Academic & Independent Research

Astrologer Content Creators

Multi-Year Forecast Tools

Technical Specifications

Mundane Astrology API vs. Hand-Wiring Three Endpoints

Related Astrology APIs

Transit Astrology API

Natal Chart API

Horary Astrology API

Cazimi & Combust API

Arabic Parts API

API Documentation

References & Standards

Simple, Transparent Pricing

Always Free

Pro

Pro Plus

Ultra

Business

Enterprise

Mundane Astrology API FAQ

What is the Mundane Astrology API?

How is mundane astrology different from natal astrology?

What zodiac system does the API use?

What are the eight event types I can search for?

What is the difference between sign_ingress and cardinal_ingress?

How long a date window can I search?

Why does cardinal_points let me pick which sign opens the mundane year?

What does the nearest_syzygy field on a cardinal ingress mean?

Does the API tell me if a Jupiter-Saturn conjunction changed triplicity?

What Saros numbering do eclipses use?

Why is eclipse magnitude sometimes 0.0?

Can I build a year-ahead astrology calendar with this?