# AuroraMap.app - Complete Documentation

> Real-time aurora australis forecast and southern lights prediction with interactive maps, KP index monitoring, and geomagnetic storm tracking for aurora enthusiasts worldwide.

## About AuroraMap.app

AuroraMap.app is a specialized aurora forecasting platform designed to provide accurate, real-time predictions for aurora australis (southern lights) visibility. The platform serves aurora enthusiasts, photographers, scientists, and tourists in the Southern Hemisphere who want to maximize their chances of witnessing this spectacular natural phenomenon.

### Key Features

**Real-time Aurora Forecasting**
- Live aurora australis predictions based on current solar wind conditions
- Hourly forecast updates using NOAA space weather data
- Geomagnetic storm alerts and notifications
- Aurora visibility probability calculations for specific locations

**Interactive Maps**
- Dynamic aurora visibility maps with prediction overlays
- Geographic coverage focusing on Southern Hemisphere aurora zones
- Real-time cloud cover integration for optimal viewing conditions
- Location-based visibility predictions with timing information

**KP Index Monitoring**
- Real-time geomagnetic activity monitoring (KP index 0-9 scale)
- Historical KP index trends and patterns
- Correlation between KP values and aurora visibility
- Alerts for elevated geomagnetic activity

**Aurora Power Index**
- Aurora power charts showing current intensity levels
- Historical aurora activity data and seasonal patterns
- Peak activity forecasting for optimal viewing windows
- Magnetic field strength measurements and solar wind parameters

## Scientific Background

**Aurora Formation**
Aurora australis occurs when charged particles from the solar wind interact with Earth's magnetosphere. These particles are channeled by Earth's magnetic field toward the polar regions, where they collide with atmospheric gases, producing the characteristic green, red, and purple lights.

**Geomagnetic Activity**
The intensity and visibility of aurora depend on several factors:
- Solar wind speed and density
- Interplanetary magnetic field orientation
- Geomagnetic storm intensity (measured by KP index)
- Local atmospheric conditions and light pollution

**Visibility Factors**
- KP index: Higher values (4+) increase aurora visibility at lower latitudes
- Moon phase: Dark skies enhance aurora visibility
- Weather conditions: Clear skies essential for observation
- Light pollution: Rural locations provide best viewing conditions

## Data Sources and Methodology

**Primary Data Sources**
- NOAA Space Weather Prediction Center (SWPC)
- ACE (Advanced Composition Explorer) satellite data
- DSCOVR (Deep Space Climate Observatory) measurements
- Ground-based magnetometer networks
- Solar wind monitoring stations

**Forecast Algorithm**
The platform uses a combination of:
1. Real-time solar wind parameters (speed, density, magnetic field)
2. Historical correlation patterns between solar activity and aurora visibility
3. Atmospheric modeling for location-specific predictions
4. Machine learning algorithms trained on decades of aurora observation data

**Update Frequency**
- Solar wind data: Every 5 minutes
- Aurora forecasts: Every 15 minutes
- KP index: Every 3 hours
- Forecast maps: Every hour

## Regional Focus Areas

**Primary Coverage Zones**
- Australia: Tasmania, Victoria, South Australia optimal viewing
- New Zealand: South Island, particularly Stewart Island region
- South America: Southern Chile, Argentina Patagonia
- Southern Africa: Tip of South Africa during major geomagnetic storms

**Latitude Considerations**
- Routine visibility: 60-70°S magnetic latitude
- Moderate activity: 55-65°S magnetic latitude
- Major storms: As low as 45-50°S magnetic latitude

## API Documentation

**Endpoints Available**
```
GET /api/current-forecast
- Returns current aurora forecast data
- Includes KP index, solar wind parameters, visibility predictions

GET /api/solar-wind
- Real-time solar wind measurements
- Speed, density, magnetic field components

GET /api/kp-index
- Current and historical KP index values
- 3-hour and daily averages

GET /api/visibility/{latitude}/{longitude}
- Location-specific aurora visibility forecast
- Probability percentages and optimal viewing times
```

**Response Format**
All API responses are in JSON format with standardized timestamp fields (UTC) and include data quality indicators and source attribution.

## Photography Guidelines

**Camera Settings**
- Manual mode with long exposure (10-30 seconds)
- Wide-angle lens (14-24mm recommended)
- ISO 1600-6400 depending on aurora intensity
- Aperture f/2.8 or wider for maximum light gathering
- Focus set to infinity

**Location Scouting**
- Find dark sky locations away from city lights
- Scout locations during daylight for safety and composition
- Consider foreground elements for compelling compositions
- Check weather forecasts for clear sky conditions

**Timing**
- Best viewing typically 1-3 hours after local midnight
- Aurora activity often peaks around equinoxes (March, September)
- Monitor real-time forecasts for sudden activity spikes
- Allow 20-30 minutes for eyes to adjust to darkness

## Historical Performance

**Forecast Accuracy**
- 85% accuracy for major geomagnetic storms (KP ≥ 6)
- 75% accuracy for moderate activity (KP 4-5)
- 60% accuracy for weak activity (KP 1-3)
- False positive rate maintained below 15%

**Notable Events**
- March 2023: Major geomagnetic storm visible from Melbourne
- October 2022: Sustained aurora activity across New Zealand
- April 2022: Rare aurora visibility from South Africa

## Technical Implementation

**Frontend Technology**
- Astro.js framework for static site generation
- Interactive maps using Leaflet.js with custom aurora overlays
- Real-time data updates via WebSocket connections
- Responsive design optimized for mobile aurora chasing

**Backend Infrastructure**
- Node.js API servers with real-time data processing
- PostgreSQL database for historical data storage
- Redis caching for frequently accessed forecasts
- Automated data ingestion from multiple space weather sources

**Performance Optimization**
- CDN delivery for global low-latency access
- Image optimization for map tiles and forecast visualizations
- Progressive web app features for offline access
- WebP format images for faster loading

## Contact and Support

**Technical Support**
Email: axxu0607@gmail.com
Response time: 24-48 hours for general inquiries

**Community**
- Follow updates on social media for major geomagnetic events
- Share aurora photography and sightings with the community
- Contribute to accuracy improvements through user feedback

**Data Attribution**
This service acknowledges the following data providers:
- NOAA Space Weather Prediction Center
- NASA Goddard Space Flight Center
- ESA Space Weather Service Network
- International Service of Geomagnetic Indices

---

*Last updated: February 2025*
*Version: 2.1.0*