🛰️ Orbit Tracker Backend

A production-ready Django backend for 3D satellite orbit visualization with comprehensive N2YO API integration, real-time tracking, and advanced satellite data management.

✨ Features

🚀 Core Functionality

• Real-time satellite tracking with WebSocket support
• 3D orbit visualization data endpoints
• Advanced filtering by category, country, activity status
• Historical playback with custom time windows
• TLE (Two-Line Element) data management and updates
• Satellite position prediction using SGP4 propagation

🌐 N2YO API Integration

• Comprehensive satellite data fetching from N2YO.com
• 58+ satellite categories (GPS, Starlink, ISS, Amateur Radio, etc.)
• Bulk import capabilities with concurrent processing
• Smart rate limiting and API quota management
• Automatic TLE updates via background tasks
• Category-based organization and filtering

🔧 Technical Features

• SQLite with WAL mode for high concurrency
• Celery background jobs with Redis or local fallback
• File-based caching for performance optimization
• REST API with Django REST Framework
• WebSocket real-time updates via Django Channels
• OpenAPI/Swagger documentation at /api/docs/
• Docker support for easy deployment

🚀 Quick Start

Prerequisites

• Python 3.11+
• pipenv (recommended) or pip
• Redis (optional, for Celery)

Installation

1. Clone the repository

   git clone https://github.com/yourusername/orbit-tracker-backend.git
   cd orbit-tracker-backend

2. Install dependencies

   pipenv install --dev
   pipenv shell

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your settings

4. Initialize database

   python manage.py migrate
   python manage.py seed_categories

5. Get N2YO API key (optional but recommended)

   • Register at N2YO.com
   • Get your API key from profile page
   • Add to .env: N2YO_API_KEY=your_api_key_here

6. Start the server

   python manage.py runserver

Visit http://localhost:8000/api/docs/ for interactive API documentation.

📡 Satellite Data Management

Fetch Satellites from N2YO

# Sync all satellite categories
python manage.py sync_categories --sync-categories

# Fetch GPS satellites with TLE data
python manage.py fetch_all_satellites --categories 20 --fetch-tle

# Fetch multiple categories (GPS, Starlink, Amateur Radio)
python manage.py fetch_all_satellites --categories 20 52 18 --fetch-tle

# Bulk import with high performance
python manage.py bulk_import_satellites --workers 3 --chunk-size 1000 --update-tle

# Fetch specific category satellites
python manage.py sync_categories --fetch-by-category "Amateur radio" "GPS"

Monitor API Usage

# Check N2YO API status
python manage.py n2yo_manager status

# Test all API endpoints
python manage.py n2yo_manager test

# View database statistics
python manage.py n2yo_manager stats

# Search for satellites
python manage.py n2yo_manager search --search-term "ISS"

🌐 API Endpoints

Satellites

• GET /api/satellites/ - List all satellites with filtering
• GET /api/satellites/{id}/ - Get satellite details
• GET /api/satellites/{id}/positions/ - Get satellite positions

Categories

• GET /api/categories/ - List satellite categories

Positions

• GET /api/positions/ - List satellite positions with time filtering

Real-time Updates

• WebSocket /ws/satellites/positions/ - Real-time position updates

Example API Usage

import requests

# Get all active satellites
response = requests.get('http://localhost:8000/api/satellites/?is_active=true')

# Get Starlink satellites
response = requests.get('http://localhost:8000/api/satellites/?category=starlink')

# Get satellite positions
response = requests.get('http://localhost:8000/api/satellites/25544/positions/')

🔄 Background Tasks

Start Celery Workers

# Start worker
celery -A tasks.celery worker --loglevel=info

# Start scheduler
celery -A tasks.celery beat --loglevel=info

# For development (local fallback)
export CELERY_TASK_ALWAYS_EAGER=True

Automated Updates

The system includes automated tasks for:

• High-priority satellite updates (every 30 minutes)
• Starlink constellation updates (every 2 hours)
• Navigation satellite updates (every 5 hours)
• General TLE refresh (every 6 hours)
• Database maintenance (daily)

🐳 Docker Deployment

# Build and run with Docker
docker build -t orbit-tracker-backend .
docker run -p 8000:8000 orbit-tracker-backend

# Or use docker-compose (if available)
docker-compose up

📊 Available Satellite Categories

The system supports 58+ satellite categories from N2YO:

Category	ID	Description
ISS	2	International Space Station
Weather	3	Weather satellites
Amateur radio	18	Ham radio satellites
GPS Operational	20	GPS constellation
Galileo	22	European navigation
Space & Earth Science	26	Scientific satellites
Military	30	Military satellites
CubeSats	32	Small satellites
Starlink	52	SpaceX constellation
OneWeb	53	OneWeb constellation

View all categories →

⚙️ Configuration

Environment Variables

# Django Settings
SECRET_KEY=your-secret-key
DEBUG=False
ALLOWED_HOSTS=localhost,127.0.0.1

# Database
DATABASE_URL=sqlite:///db.sqlite3

# N2YO API
N2YO_API_KEY=your-n2yo-api-key

# Celery (optional)
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=django-db

# CORS (for frontend)
CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

Update Intervals

Customize update frequencies via environment variables:

UPDATE_INTERVAL_HIGH=30        # High priority satellites (minutes)
UPDATE_INTERVAL_STARLINK=120   # Starlink updates (minutes)
UPDATE_INTERVAL_NAV=300        # Navigation satellites (minutes)
UPDATE_INTERVAL_TLE=21600      # General TLE refresh (seconds)

🧪 Testing

# Run tests
python manage.py test

# Run with coverage
coverage run --source='.' manage.py test
coverage report

# Lint code
flake8 .

# Format code
black .

📚 Documentation

• N2YO Integration Guide - Comprehensive guide for satellite data fetching
• API Documentation - Interactive Swagger UI
• WebSocket Guide - Real-time updates documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Install development dependencies
pipenv install --dev

# Run pre-commit hooks
pre-commit install

# Run tests before committing
python manage.py test

📈 Performance

• Database: Optimized SQLite with WAL mode for concurrent access
• Caching: File-based caching for API responses and computed data
• Bulk Operations: Efficient batch processing for large datasets
• Rate Limiting: Smart API usage to respect N2YO quotas
• Concurrent Processing: Multi-threaded satellite data fetching

🔒 Security

• API Key Management: Secure storage of N2YO API credentials
• CORS Configuration: Configurable cross-origin resource sharing
• Input Validation: Comprehensive request validation
• Rate Limiting: Protection against API abuse

📊 Monitoring

The system includes comprehensive monitoring:

# Database statistics
python manage.py n2yo_manager stats

# API health check
python manage.py n2yo_manager status

# TLE data freshness
python manage.py check_tle_freshness

🐛 Troubleshooting

Common Issues

1. N2YO API Errors

   python manage.py n2yo_manager status

2. Database Lock Issues

   • Ensure WAL mode is enabled
   • Check for long-running transactions

3. Memory Usage

   • Adjust batch sizes for large imports
   • Monitor Celery worker memory

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• N2YO.com for satellite tracking data
• CelesTrak for TLE data standards
• SGP4 for orbit propagation
• Django Community for the excellent framework

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

---

Built with ❤️ for the satellite tracking community