A unified API and event database that collects, normalizes, and serves solar event data from multiple sources (HEK, CCMC, WSA, RHESSI) for use in Helioviewer.org and related tools.
- Multi-source Event Collection: Collects and normalizes solar event data from CCMC DONKI, WSA, and other sources
- Coordinate Transformation: High-performance batch coordinate transformation from HGS to HPC with caching
- RESTful API: Modern REST API with v1 and v2 endpoints for event querying
- Real-time Processing: Event collection with configurable chunk intervals for efficient data processing
- Redis Caching: Comprehensive caching layer for HTTP requests and coordinate transformations
- PostgreSQL Storage: Robust data storage with Eloquent ORM and database migrations
This project uses Docker Compose for local development with PHP 8.4, Nginx, and PostgreSQL.
- Docker
- Docker Compose
- Make (optional, for convenience commands)
-
Start the development environment:
make up
Or manually:
docker compose -f docker/docker-compose.yml up
-
Install PHP dependencies:
make composer-install
-
Run database migrations:
make migrate-run
-
Seed the database with sample data:
make seed-run
-
Access the application:
- Open http://localhost:8082 in your browser
- You should see the PHP info page
For a complete list of available commands, run:
makemake up- Start the Docker containersmake down- Stop the Docker containersmake build- Build the Docker images (with --no-cache)make shell- Open a bash shell in the PHP container (user 1000:1000)make shell-root- Open a root bash shell in the PHP container
make composer-install- Install PHP dependencies via Composermake composer-require PACKAGE=package-name- Add a new packagemake composer-dump- Regenerate Composer autoloader
make nginx-reload- Reload nginx configuration
make migrate-status- Check migration statusmake migrate-create NAME=MigrationName- Create a new migrationmake migrate-run- Run pending migrationsmake migrate-rollback- Rollback the last migrationmake seed-run- Run database seeders
make collect- Collect events for today (daily chunks)make collect 2024-01-01- Collect events for single daymake collect 2024-01-01 2024-01-31- Collect events for date range (daily chunks)make collect 2024-01-01 2024-01-31 5- Collect date range in 5-day chunksmake recents- Show the most recent events from the databasemake recents 10- Show last 10 eventsmake stats- Show database statistics grouped by source and pathmake logs- Follow application logs (tail -f storage/logs/*.log)make reset- Reset database (rollback all migrations, migrate, and seed)
The API provides several endpoints for accessing solar event data:
GET /api/v1/events/{source}/observation/{timestamp}- Get events active at specific timestamp with coordinate rotation
GET /api/v2/events/recents- Get last 100 updated events with enhanced dataGET /api/v2/events/{uuid}- Get single event by UUID with full detailsGET /api/v2/events/{uuid}/source- Get raw source data for an eventGET /api/v2/events/{source}/observation/{timestamp}- Enhanced observation endpoint
Supported Sources: CCMC, HEK, WSA, RHESSI
Timestamp Formats: ISO 8601, Y-m-d, Y-m-d H:i:s, Unix timestamps
- Nginx (
eventsapi-nginx) - Web server listening on port 8082 - PHP-FPM (
eventsapi-phpfpm) - PHP 8.4 with coordinate transformation binaries - PostgreSQL (
eventsapi-postgres) - Event database with Eloquent ORM - Redis (
eventsapi-redis) - Caching layer for HTTP and coordinate transformations
The system includes dual coordinate transformation services:
- DanielCoordinator (Primary) - Fast coordinate rotation service
- CommandLineCoordinator (Backup) - SunPy-based transformation using hgs_to_hpc binary
Both coordinators support batch processing and Redis caching for optimal performance.
PostgreSQL database configuration:
- Database:
eventsapi - User:
eventsapi - Password:
eventsapi_pass - Host:
postgres(container name) - Port:
5432
Redis configuration:
- Host:
redis(container name) - Port:
6379 - Database:
10
Database migrations are managed using Phinx with environment variable configuration.