{"openapi":"3.2.0","info":{"title":"Astronomy and Time API","description":"Accurate astronomical calculations — moon phases, sunrise/sunset, twilight, seasons, zodiac signs, and eclipse calendars for any date and location. No external API dependencies.","version":"1.0.0"},"servers":[{"url":"https://cardc.jojapi.net"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"zodiac"},{"name":"moon"},{"name":"eclipses"},{"name":"sun"},{"name":"health"},{"name":"seasons"}],"x-agent-commerce":{"catalog_url":"https://cardc.jojapi.net/_jojapi/agent/plans","discovery_url":"https://cardc.jojapi.net/.well-known/x402","directory_url":"https://agents.jojapi.net/apis/astronomy-and-time","docs":"https://docs.jojapi.com/consumers/agents"},"paths":{"/":{"get":{"operationId":"get","summary":"getApiInfo","description":"Get basic API information and list of all available endpoints.","responses":{"200":{"description":"API info with endpoints list","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"status":{"type":"string"},"timestamp":{"type":"string"},"endpoints":{"type":"array","items":{"type":"string"}}}},"examples":{"Example_1":{"value":{"name":"","version":"","status":"","timestamp":"","endpoints":[]}}}}}}}}},"/zodiac":{"get":{"operationId":"get_zodiac","summary":"getZodiacByDate","description":"Get the zodiac sign for a specific date using precise astronomical calculation.","tags":["zodiac"],"responses":{"200":{"description":"Zodiac sign for the specified date","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"sign":{"type":"string"},"symbol":{"type":"string"},"sun_ecliptic_longitude":{"type":"number"},"calculation":{"type":"string"}}},"examples":{"Example_1":{"value":{"date":"","sign":"","symbol":"","sun_ecliptic_longitude":0,"calculation":""}}}}}}},"parameters":[{"name":"date","in":"query","description":"Date in YYYY-MM-DD format (default: today)","required":false,"schema":{"type":"string","example":"2026-06-23"}}]}},"/zodiac/today":{"get":{"operationId":"get_zodiac_today","summary":"getZodiacToday","description":"Get today's zodiac sign based on the sun's astronomical ecliptic longitude.","tags":["zodiac"],"responses":{"200":{"description":"Today's zodiac sign","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"sign":{"type":"string"},"symbol":{"type":"string"},"sun_ecliptic_longitude":{"type":"number"},"calculation":{"type":"string"}}},"examples":{"Example_1":{"value":{"date":"","sign":"","symbol":"","sun_ecliptic_longitude":0,"calculation":""}}}}}}}}},"/moon/today":{"get":{"operationId":"get_moon_today","summary":"getMoonPhaseToday","description":"Get the current moon phase with illumination percentage and next new/full moon dates.","tags":["moon"],"responses":{"200":{"description":"Current moon phase data","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"phase_name":{"type":"string"},"phase_degrees":{"type":"number"},"illumination_percent":{"type":"number"},"next_new_moon":{"type":"string"},"next_full_moon":{"type":"string"}}},"examples":{"Example_1":{"value":{"date":"","phase_name":"","phase_degrees":0,"illumination_percent":0,"next_new_moon":"","next_full_moon":""}}}}}}}}},"/moon":{"get":{"operationId":"get_moon","summary":"getMoonPhaseByDate","description":"Get the moon phase for a specific date. Returns phase name, illumination percentage, and next new/full moon dates.","tags":["moon"],"responses":{"200":{"description":"Moon phase data for the specified date","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"phase_name":{"type":"string"},"phase_degrees":{"type":"number"},"illumination_percent":{"type":"number"},"next_new_moon":{"type":"string"},"next_full_moon":{"type":"string"}}},"examples":{"Example_1":{"value":{"date":"","phase_name":"","phase_degrees":0,"illumination_percent":0,"next_new_moon":"","next_full_moon":""}}}}}}},"parameters":[{"name":"date","in":"query","description":"Date in YYYY-MM-DD format (default: today)","required":false,"schema":{"type":"string","example":"2026-06-23"}}]}},"/eclipses/{year}":{"get":{"operationId":"get_eclipses_year","summary":"getEclipses","description":"Get solar and lunar eclipse calendar for a specified year (1900-2100).","tags":["eclipses"],"responses":{"200":{"description":"Eclipse calendar for the year","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer"},"total_eclipses":{"type":"integer"},"solar_eclipses":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"time_utc":{"type":"string"},"type":{"type":"string"}}}},"lunar_eclipses":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"time_utc":{"type":"string"},"type":{"type":"string"}}}}}},"examples":{"Example_1":{"value":{"year":0,"total_eclipses":0,"solar_eclipses":[{"date":"","time_utc":"","type":""}],"lunar_eclipses":[{"date":"","time_utc":"","type":""}]}}}}}}},"parameters":[{"name":"year","in":"path","description":"Year (1900-2100)","required":true,"schema":{"type":"number","example":2026}}]}},"/sun/today":{"get":{"operationId":"get_sun_today","summary":"getSunDataToday","description":"Get today's sunrise, sunset, twilight times and solar noon for a location.","tags":["sun"],"responses":{"200":{"description":"Sun data for today","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"location":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"sunrise":{"type":"string"},"sunset":{"type":"string"},"solar_noon":{"type":"string"},"day_length":{"type":"string"},"day_length_seconds":{"type":"integer"},"civil_dawn":{"type":"string"},"civil_dusk":{"type":"string"},"nautical_dawn":{"type":"string"},"nautical_dusk":{"type":"string"},"astronomical_dawn":{"type":"string"},"astronomical_dusk":{"type":"string"}}},"examples":{"Example_1":{"value":{"date":"","location":{"lat":0,"lon":0},"sunrise":"","sunset":"","solar_noon":"","day_length":"","day_length_seconds":0,"civil_dawn":"","civil_dusk":"","nautical_dawn":"","nautical_dusk":"","astronomical_dawn":"","astronomical_dusk":""}}}}}}},"parameters":[{"name":"lon","in":"query","description":"Longitude (default: 14.4378 — Prague)","required":false,"schema":{"type":"number","example":14.4378}},{"name":"lat","in":"query","description":"Latitude (default: 50.0755 — Prague)","required":false,"schema":{"type":"number","example":50.0755}}]}},"/sun":{"get":{"operationId":"get_sun","summary":"getSunDataByDate","description":"Get sunrise, sunset, twilight for a specific date and location.","tags":["sun"],"responses":{"200":{"description":"Sun data for the specified date","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"location":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"sunrise":{"type":"string"},"sunset":{"type":"string"},"solar_noon":{"type":"string"},"day_length":{"type":"string"},"day_length_seconds":{"type":"integer"},"civil_dawn":{"type":"string"},"civil_dusk":{"type":"string"},"nautical_dawn":{"type":"string"},"nautical_dusk":{"type":"string"},"astronomical_dawn":{"type":"string"},"astronomical_dusk":{"type":"string"}}},"examples":{"Example_1":{"value":{"date":"","location":{"lat":0,"lon":0},"sunrise":"","sunset":"","solar_noon":"","day_length":"","day_length_seconds":0,"civil_dawn":"","civil_dusk":"","nautical_dawn":"","nautical_dusk":"","astronomical_dawn":"","astronomical_dusk":""}}}}}}},"parameters":[{"name":"lon","in":"query","description":"Longitude (default: 14.4378 — Prague)","required":false,"schema":{"type":"number","example":14.4378}},{"name":"date","in":"query","description":"Date in YYYY-MM-DD format (default: today)","required":false,"schema":{"type":"string","example":"2026-06-23"}},{"name":"lat","in":"query","description":"Latitude (default: 50.0755 — Prague)","required":false,"schema":{"type":"number","example":50.0755}}]}},"/health":{"get":{"operationId":"get_health","summary":"healthCheck","description":"Simple health check endpoint — returns status and server timestamp.","tags":["health"],"responses":{"200":{"description":"Health status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"timestamp":{"type":"string"}}},"examples":{"Example_1":{"value":{"status":"","timestamp":""}}}}}}}}},"/seasons/{year}":{"get":{"operationId":"get_seasons_year","summary":"getSeasons","description":"Get equinox and solstice dates for a specified year (1900-2100).","tags":["seasons"],"responses":{"200":{"description":"Season dates for the year","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer"},"seasons":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"date":{"type":"string"},"time_utc":{"type":"string"}}}}}},"examples":{"Example_1":{"value":{"year":0,"seasons":[{"name":"","date":"","time_utc":""}]}}}}}}},"parameters":[{"name":"year","in":"path","description":"Year (1900-2100)","required":true,"schema":{"type":"number","example":2026}}]}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-JoJAPI-Key","description":"Your JoJ API key."}}}}