klemenswal/comet-server repository overview

⁠☄️ Comet-Server API

A high-performance, FastAPI-based astronomical engine designed to calculate real-time ephemerides, visibility, and guiding rates for comets.

⁠🌟 Overview

This service automates the complex math required to track comets. It downloads data from the Minor Planet Center (MPC) and provides precise orbital calculations adjusted for your specific location on Earth.

⁠Core Features:

• Real-time Tracking: RA/DEC, Altitude, Azimuth, and Distance.
• Visual Magnitude Correction: Advanced algorithm to calculate brightness loss due to Atmospheric Extinction (Airmass).
• Astro-Photography Ready: Provides precise Guiding Rates (arcsec/min) for telescope tracking.
• Visibility Logic: Integrated "Horizon Check" (returns 99.0 mag if the object is below the horizon).
• Flexible Output: Choose between structured JSON for apps or a styled HTML table for humans.

⁠🚀 Quick Start

To run the server on your local machine or server:

docker run -d -p 8000:8000 --name comet-service <dein-nutzername>/comet-server:latest

The API will be available at http://localhost:8000.

⁠Example Request:

Current position of Comet 12P (Pons-Brooks): http://localhost:8000/calculate?designation=12P&lat=49.39&lon=10.88&output=html

⁠🛠 Technical Stack

• Language: Python 3.11
• Framework: FastAPI
• Astro-Libraries: Skyfield, Pandas, NumPy
• Data Source: JPL DE421 Ephemerides & MPC Database

⁠📝 License

This project is provided for educational and amateur astronomy purposes.

⁠🛰️ Comet-Server API Reference

The API is accessible via HTTP on port 8000. It supports both JSON for programmatic use and HTML for visual inspection.

⁠1. Get Comet Data

GET /calculate

Calculates the current position and visibility of a specific comet.

⁠Parameters

⁠Example Request

GET http://localhost:8000/calculate?designation=12P&lat=49.3&lon=11.1&output=json

⁠2. Daily Ephemeris Table

GET /daily_table

Generates a 24-hour schedule for a comet at a specific location.

⁠Parameters

⁠3. Batch Calculation

GET /calculate_batch

Request data for multiple comets in a single call.

⁠Parameters

⁠📊 Response Fields (JSON)

When requesting output=json, the service returns:

• magnitude_vis: Apparent magnitude adjusted for airmass/extinction. Returns 99.0 if below horizon.
• **altitude / azimuth**: Topocentric position in degrees.
• **ra_hms / dec_dms**: Right Ascension and Declination (formatted).
• **guiding_ra / guiding_dec**: Tracking rates in arcsec/min for telescope mounts.
• earth_distance_au: Distance from Earth in Astronomical Units.

⁠🛑 Error Handling

• 404 Not Found: The comet designation was not found in the MPC database.
• 422 Unprocessable Entity: Missing or malformed parameters (e.g., invalid coordinates).