View source for Astro Events API Guide

= Astro Events API Guide =
This page documents the structured API for querying astrological event data
from the FusionGirl wiki. Designed for '''AI agent consumption'''.

== Quick Start ==
All astrological transit events are stored in the '''AstroEvents''' [[Extension:Cargo|Cargo]] table
and queryable via the MediaWiki API.

=== Base URL ===
<pre>
https://wiki.fusiongirl.app/api.php?action=cargoquery&format=json
</pre>

=== Example Queries ===

==== All Conjunctions in 2026 ====
<pre>
GET /api.php?action=cargoquery
    &tables=AstroEvents
    &fields=event_date,planet1,planet2,sign1,sign2,interpretation
    &where=year=2026 AND aspect='Conjunction'
    &order_by=event_date
    &format=json
</pre>

==== Jupiter transits (any aspect) ====
<pre>
GET /api.php?action=cargoquery
    &tables=AstroEvents
    &fields=event_date,planet1,planet2,aspect,sign1,sign2
    &where=planet1='Jupiter' OR planet2='Jupiter'
    &order_by=event_date
    &format=json
</pre>

==== Events in Scorpio ====
<pre>
GET /api.php?action=cargoquery
    &tables=AstroEvents
    &fields=event_date,planet1,planet2,aspect,sign1,sign2
    &where=sign1='Scorpio' OR sign2='Scorpio'
    &order_by=event_date
    &format=json
</pre>

==== Retrograde events ====
<pre>
GET /api.php?action=cargoquery
    &tables=AstroEvents
    &fields=event_date,planet1,planet2,aspect,sign1,sign2
    &where=retrograde1='Yes' OR retrograde2='Yes'
    &order_by=event_date
    &format=json
</pre>

==== Count events by aspect type ====
<pre>
GET /api.php?action=cargoquery
    &tables=AstroEvents
    &fields=aspect,COUNT(*)=count
    &group_by=aspect
    &order_by=count DESC
    &format=json
</pre>

==== iCalendar export (subscribe in any calendar app) ====
<pre>
GET /index.php?title=Special:CargoExport
    &tables=AstroEvents
    &fields=event_date,planet1,planet2,aspect,sign1,sign2,interpretation
    &order_by=event_date
    &format=icalendar
</pre>

==== JSON export ====
<pre>
GET /index.php?title=Special:CargoExport
    &tables=AstroEvents
    &fields=event_date,planet1,planet2,aspect,sign1,sign2,interpretation
    &order_by=event_date
    &format=json
</pre>

== Available Fields ==
{| class="wikitable"
|-
! Field !! Type !! Description !! Example
|-
| event_date || Datetime || UTC datetime of exact aspect || 2026-03-08 03:42:00
|-
| planet1 || String || First celestial body || Jupiter
|-
| planet2 || String || Second celestial body || Saturn
|-
| aspect || String || Aspect type || Conjunction
|-
| sign1 || String || Zodiac sign of planet1 || Aquarius
|-
| sign2 || String || Zodiac sign of planet2 || Scorpio
|-
| element1 || String || Element of sign1 || Air
|-
| element2 || String || Element of sign2 || Water
|-
| modality1 || String || Modality of sign1 || Fixed
|-
| modality2 || String || Modality of sign2 || Fixed
|-
| degree1 || Float || Ecliptic degree of planet1 || 311.43
|-
| degree2 || Float || Ecliptic degree of planet2 || 221.43
|-
| retrograde1 || Boolean || Planet1 retrograde || Yes/No
|-
| retrograde2 || Boolean || Planet2 retrograde || Yes/No
|-
| interpretation || Wikitext || Natural-language interpretation || Fusion of energies...
|-
| source_file || String || Source ICS file || planetary_aspect_events_2026.ics
|-
| year || Integer || Event year || 2026
|}

== WHERE Clause Operators ==
Cargo supports standard SQL-like operators in the <code>where</code> parameter:
* <code>=</code>, <code>!=</code>, <code><</code>, <code>></code>, <code><=</code>, <code>>=</code>
* <code>LIKE '%pattern%'</code>
* <code>IN ('val1','val2')</code>
* <code>AND</code>, <code>OR</code>
* <code>BETWEEN</code>
* <code>IS NULL</code>, <code>IS NOT NULL</code>

== Rate Limits ==
The API has no authentication requirement for read-only queries.
Please limit requests to a reasonable rate (≤1 req/sec for bulk operations).

== Data Coverage ==
* '''Source:''' planetaryAspectEventsCalendar ICS files
* '''Years:''' 2024–2033 (expandable to 2056)
* '''Events:''' ~400+ events per year
* '''Aspects:''' Conjunction, Opposition, Trine, Square, Sextile, Quincunx, and minor aspects

== See Also ==
* [[Astro Events Calendar]] — interactive calendar view
* [[Astrological Timeline 2025–2033]] — narrative timeline pages
* [[Template:AstroEvent]] — Cargo schema definition

[[Category:API Documentation]]
[[Category:AI Agent Resources]]
[[Category:FusionGirl Documentation]]