{"openapi":"3.0.3","info":{"title":"Celestora API","version":"1.0.0","description":"Celestial-body position calculations: Sun, Moon, planets, stars,\nconstellations, comets, satellites, deep-sky catalogs (Messier, NGC),\nplus celestial events (transits, conjunctions, oppositions, eclipses).\n\nOutput formats include PTZ/VISCA (camera control), Celestron/INDI\n(telescope control), and Modbus/IEC61850 (industrial solar tracking).\nCalculations use VSOP87 (planets) and ELP-2000 (Moon) at sub-arcsecond\nprecision.\n","contact":{"name":"Celestora Support","email":"support@celestora.org"},"license":{"name":"Commercial License","url":"https://celestora.org/license"}},"servers":[{"url":"https://api.celestora.org","description":"Production server"},{"url":"http://localhost:8787","description":"Local development"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"getHealth","tags":["System"],"security":[],"responses":{"200":{"description":"Service healthy"}}}},"/v1/metadata/enums":{"get":{"summary":"List every enum used by the Celestora API.","description":"Returns the directory of enums (output formats, planet IDs,\ncelestial-event types, catalog source IDs) with localised labels in\nthe caller's language. Use when building UIs that need to mirror the\nAPI's vocabulary.\n","operationId":"listEnums","tags":["Metadata"],"security":[],"responses":{"200":{"description":"Enum metadata"}}}},"/v1/metadata/enums/{name}":{"get":{"summary":"Get a single enum by name.","description":"Returns localised values for one enum. See `listEnums` for the\ndirectory of available enum names.\n","operationId":"getEnum","tags":["Metadata"],"security":[],"parameters":[{"name":"name","in":"path","required":true,"description":"Enum identifier (e.g. `output_format`, `event_type`).","example":"output_format","schema":{"type":"string"}}],"responses":{"200":{"description":"Enum values"}}}},"/api/v1/sun/position":{"get":{"summary":"Get the Sun's current position (alt/az or RA/Dec) for an observer.","description":"Returns the Sun's current azimuth + altitude (horizontal coordinates)\nas seen from the (lat, lon) observer location, plus right ascension\nand declination. Use for solar trackers, photovoltaic positioning,\nand golden-hour planning. Computed from VSOP87 + observer coordinates.\n","operationId":"getSunPosition","tags":["Solar"],"parameters":[{"name":"location","in":"query","required":true,"description":"Observer location, comma-separated `lat,lon` (decimal degrees, WGS84).","example":"35.6762,139.6503","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Output format. `basic` JSON; specialised formats for camera/telescope/tracker control.","schema":{"type":"string","enum":["basic","ptz","celestron","indi","modbus","iec61850"],"default":"basic"}}],"responses":{"200":{"description":"Sun position at the requested time"}}}},"/api/v1/moon/position":{"get":{"summary":"Get the Moon's current position (alt/az or RA/Dec) for an observer.","description":"Returns the Moon's current azimuth + altitude for the observer, plus\nRA/Dec, phase percentage, and illuminated fraction. Computed from\nELP-2000. Use for telescope auto-pointing, lunar photography,\nmoon-phase indicators.\n","operationId":"getMoonPosition","tags":["Lunar"],"parameters":[{"name":"location","in":"query","required":true,"description":"Observer location, `lat,lon` decimal degrees.","example":"35.6762,139.6503","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["basic","ptz","celestron","indi"],"default":"basic"}}],"responses":{"200":{"description":"Moon position"}}}},"/api/v1/planets/{planet}/position":{"get":{"summary":"Get the current position of a named planet for an observer.","description":"Returns the requested planet's azimuth + altitude (and RA/Dec) from\nthe observer's location. Mercury through Saturn are computed from\nVSOP87 at high precision; Uranus/Neptune are slightly lower\nprecision (sufficient for amateur observation).\n","operationId":"getPlanetPosition","tags":["Planetary"],"parameters":[{"name":"planet","in":"path","required":true,"description":"Planet name.","example":"mars","schema":{"type":"string","enum":["mercury","venus","mars","jupiter","saturn","uranus","neptune"]}},{"name":"location","in":"query","required":true,"description":"Observer location, `lat,lon` decimal degrees.","example":"35.6762,139.6503","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["basic","ptz","celestron","indi"],"default":"basic"}}],"responses":{"200":{"description":"Planet position"}}}},"/api/v1/moon/alignment":{"get":{"summary":"Find Moon-pointing alignment windows within a time range.","description":"Searches a time window for moments when the Moon enters a target\nazimuth/altitude cone (within tolerance). Useful for camera/PTZ\ntriggers, photography sessions, and ritual / observation timing.\n","operationId":"getMoonAlignment","tags":["Lunar"],"parameters":[{"name":"latitude","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"target_azimuth","in":"query","required":true,"description":"Target azimuth in degrees (0=north, 90=east).","schema":{"type":"number","minimum":0,"maximum":360}},{"name":"target_altitude","in":"query","required":true,"description":"Target altitude in degrees (0=horizon, 90=zenith).","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"from","in":"query","required":true,"description":"Window start (ISO 8601 UTC).","example":"2026-06-01T00:00:00Z","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":true,"description":"Window end (ISO 8601 UTC).","schema":{"type":"string","format":"date-time"}},{"name":"tolerance","in":"query","required":false,"description":"Angular tolerance in degrees.","schema":{"type":"number","default":1}}],"responses":{"200":{"description":"Alignment events"}}}},"/api/v1/moon/ephemeris":{"get":{"summary":"Get a Moon ephemeris (position series) over a time window.","description":"Returns the Moon's position (RA/Dec/alt/az, phase, distance) sampled\nat regular intervals over the requested window. Use for plotting\nlunar tracks, eclipse path analysis, and tide-amplitude planning.\n","operationId":"getMoonEphemeris","tags":["Lunar"],"parameters":[{"name":"latitude","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"step_minutes","in":"query","required":false,"description":"Sample interval in minutes.","schema":{"type":"integer","default":15}}],"responses":{"200":{"description":"Moon ephemeris series"}}}},"/api/v1/celestial/{body}/ephemeris":{"get":{"summary":"Generic ephemeris (position series) for a celestial body.","description":"Generic position series for the supported bodies (Moon, Sun, Venus,\nMars, Jupiter). Same payload schema as `getMoonEphemeris`. Use for\ncomparative ephemeris generation across multiple bodies.\n","operationId":"getCelestialEphemeris","tags":["Celestial"],"parameters":[{"name":"body","in":"path","required":true,"description":"Celestial body identifier (case-sensitive, matches astronomy-engine).","example":"Mars","schema":{"type":"string","enum":["Moon","Sun","Venus","Mars","Jupiter"]}},{"name":"latitude","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Body ephemeris series"}}}},"/api/v1/celestial/{body}/alignment":{"get":{"summary":"Find alignment windows for a celestial body within a time range.","description":"Generic alignment search for the supported bodies. Returns moments\nwhen the body enters a target azimuth/altitude cone. Same as\n`getMoonAlignment` but for any supported body.\n","operationId":"getCelestialAlignment","tags":["Celestial"],"parameters":[{"name":"body","in":"path","required":true,"example":"Venus","schema":{"type":"string","enum":["Moon","Sun","Venus","Mars","Jupiter"]}},{"name":"latitude","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"target_azimuth","in":"query","required":true,"schema":{"type":"number","minimum":0,"maximum":360}},{"name":"target_altitude","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"tolerance","in":"query","required":false,"schema":{"type":"number","default":1}}],"responses":{"200":{"description":"Alignment events"}}}},"/api/v1/catalog/messier":{"get":{"summary":"List the Messier deep-sky catalog (M1–M110).","description":"Returns Charles Messier's classic 110-object deep-sky catalog with\neach object's RA/Dec, magnitude, type, constellation, and common\nname. Stable list — does not change between requests.\n","operationId":"listMessier","tags":["Catalog"],"security":[],"responses":{"200":{"description":"Messier catalog"}}}},"/api/v1/catalog/satellites":{"get":{"summary":"List tracked artificial satellites with current TLE elements.","description":"Returns the list of currently-tracked artificial satellites (ISS,\nStarlink, NOAA, etc.) with their two-line element (TLE) sets for\norbit propagation. TLEs are refreshed daily.\n","operationId":"listSatellites","tags":["Catalog"],"security":[],"responses":{"200":{"description":"Satellite TLE list"}}}},"/api/v1/catalog/atlas":{"get":{"summary":"Get the constellation atlas (boundaries + featured stars).","description":"Returns the IAU constellation atlas with sky boundaries (vector\ncoordinates) and the featured stars per constellation. Use for sky-\nchart rendering and constellation labelling.\n","operationId":"getConstellationAtlas","tags":["Catalog"],"security":[],"responses":{"200":{"description":"Constellation atlas"}}}},"/api/v1/catalog/stars":{"get":{"summary":"List bright stars from the Hipparcos / Yale Bright Star Catalogue.","description":"Returns bright stars (typically magnitude < 6.5) with HIP / HD / BSC\nidentifiers, RA/Dec, magnitude, spectral class, and proper-motion\nvectors. Filterable by magnitude or constellation.\n","operationId":"listStars","tags":["Catalog"],"security":[],"parameters":[{"name":"max_magnitude","in":"query","required":false,"description":"Only return stars brighter than this magnitude.","example":4,"schema":{"type":"number"}},{"name":"constellation","in":"query","required":false,"description":"Filter to one IAU constellation abbreviation.","example":"Ori","schema":{"type":"string"}}],"responses":{"200":{"description":"Star catalog"}}}},"/api/v1/catalog/constellations":{"get":{"summary":"List the 88 IAU-recognised constellations.","description":"Returns the 88 modern constellations with full Latin name, IAU\nabbreviation, hemisphere, area in square degrees, and the\nconstellation's brightest star.\n","operationId":"listConstellations","tags":["Catalog"],"security":[],"responses":{"200":{"description":"Constellation list"}}}},"/api/v1/catalog/ecliptic":{"get":{"summary":"Get the ecliptic plane and zodiac constellations.","description":"Returns the ecliptic great-circle path through the sky (the plane of\nEarth's orbit) and the 13 zodiac constellations the Sun crosses\nthrough annually (including Ophiuchus). Useful for solar / planetary\npath visualisation.\n","operationId":"getEcliptic","tags":["Catalog"],"security":[],"responses":{"200":{"description":"Ecliptic + zodiac data"}}}},"/api/v1/catalog/comets":{"get":{"summary":"List currently-tracked periodic and short-period comets.","description":"Returns the list of comets in Celestora's catalog with orbital\nelements, current heliocentric distance, expected next perihelion,\nand naked-eye-visibility flag. Updated weekly.\n","operationId":"listComets","tags":["Catalog"],"security":[],"responses":{"200":{"description":"Comet catalog"}}}},"/api/v1/catalog/search":{"get":{"summary":"Search across the celestial-object catalogs by name or designation.","description":"Free-text search across Messier, stars, constellations, comets, and\nsatellites. Returns matching objects sorted by relevance.\n","operationId":"searchCatalog","tags":["Catalog"],"security":[],"parameters":[{"name":"q","in":"query","required":true,"description":"Search term — accepts common names, catalog IDs (M31, NGC 224), and partial matches.","example":"andromeda","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Search results"}}}},"/api/v1/catalog/{id}":{"get":{"summary":"Look up a specific catalog object by ID.","description":"Returns the full record for one catalog object identified by ID\n(e.g. `M31`, `HIP 11767`). Use after `searchCatalog` to fetch\ndetails.\n","operationId":"getCatalogObject","tags":["Catalog"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"example":"M31","schema":{"type":"string"}}],"responses":{"200":{"description":"Catalog object record"},"404":{"description":"ID not found in any catalog"}}}},"/api/v1/events/upcoming":{"get":{"summary":"List upcoming celestial events (transits, conjunctions, eclipses).","description":"Returns the next N upcoming celestial events from the curated event\ncatalog: planetary transits, conjunctions, oppositions, lunar/solar\neclipses, meteor-shower peaks. Filter by type or date range.\n","operationId":"listUpcomingEvents","tags":["Events"],"security":[],"parameters":[{"name":"type","in":"query","required":false,"description":"Filter by event type.","schema":{"type":"string","enum":["transit","conjunction","opposition","eclipse","meteor-shower"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Upcoming events"}}}},"/api/v1/events/tonight":{"get":{"summary":"Get the celestial events visible tonight from the observer's location.","description":"Returns events visible from the observer's coordinates during local\nnighttime — Moon phase, visible planets, ISS passes, current\nmeteor shower activity, etc. Use as a one-shot \"what's happening\ntonight?\" feed.\n","operationId":"getTonightEvents","tags":["Events"],"security":[],"parameters":[{"name":"latitude","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Tonight's events"}}}},"/api/v1/observation/conditions":{"get":{"summary":"Assess astronomical observation conditions at a location and time.","description":"Returns a composite observation-condition score combining cloud\ncover, atmospheric seeing, transparency, light pollution, and Moon\ninterference. Use for picking the best slot for stargazing,\nastrophotography, or telescope automation.\n","operationId":"getObservationConditions","tags":["Observation"],"security":[],"parameters":[{"name":"latitude","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"at","in":"query","required":false,"description":"ISO datetime to evaluate. Defaults to next nighttime.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Observation conditions"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key sent via header (X-API-Key). Obtain from the PPN Hub developer portal."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"tags":[{"name":"System","description":"Health, version, and root metadata."},{"name":"Solar","description":"Sun position, solar trackers."},{"name":"Lunar","description":"Moon position, ephemeris, alignment."},{"name":"Planetary","description":"Mercury through Neptune position queries."},{"name":"Celestial","description":"Generic celestial-body endpoints (any supported body)."},{"name":"Catalog","description":"Stars, constellations, Messier, comets, satellites, search."},{"name":"Events","description":"Upcoming and tonight's celestial events."},{"name":"Observation","description":"Composite observation-condition scoring."},{"name":"Metadata","description":"Localised enum lookups."}]}