openapi: 3.0.0 info: title: Moon-API.com Advanced Calendar API description: API for retrieving detailed moon phase data, sun data, calendars, and astronomical information version: 2.0.0 contact: name: Moon-API.com url: https://moon-api.com servers: - url: https://moon-phase.p.rapidapi.com description: Production server (via RapidAPI) security: - RapidAPIKey: [] tags: - name: Calendar paths: /calendar: get: summary: Get moon and sun data calendar description: Returns moon and sun data for a date range parameters: - $ref: '#/components/parameters/latitudeParam' - $ref: '#/components/parameters/longitudeParam' - name: start_date in: query description: Start date (YYYY-MM-DD) required: false schema: type: string format: date - name: end_date in: query description: End date (YYYY-MM-DD) required: false schema: type: string format: date - name: days in: query description: 'Number of days from today (if dates not provided, default: 30)' required: false schema: type: integer default: 30 responses: '200': description: Successful response content: application/json: schema: type: object properties: start_date: type: string end_date: type: string data: type: array items: $ref: '#/components/schemas/MoonSunResponse' example: start_date: '2026-01-01' end_date: '2026-01-07' data: - timestamp: 1768327440 datestamp: Tue, 13 Jan 2026 18:04:00 +0000 plan: MEGA sun: sunrise: 1768291282 sunrise_timestamp: 08:01 sunset: 1768321044 sunset_timestamp: '16:17' solar_noon: '12:09' day_length: 08:16 moon: phase: 0.8294482328 phase_name: Waning crescent major_phase: New Moon stage: waning illumination: 22% age_days: 24 '400': description: Bad request '500': description: Server error tags: - Calendar components: schemas: MoonSunResponse: type: object properties: timestamp: type: integer example: 1768327440 datestamp: type: string example: Tue, 13 Jan 2026 18:04:00 +0000 plan: type: string example: MEGA next_eclipse: type: object description: Present for ULTRA and MEGA plans. Next upcoming eclipse with countdown. properties: timestamp: type: integer example: 1771329600 datestamp: type: string example: Tue, 17 Feb 2026 12:00:00 +0000 type: type: string example: Annular Solar Eclipse visibility_regions: type: string example: s Argentina & Chile, s Africa, Antarctica category: type: string enum: - solar - lunar example: solar countdown: type: object properties: days: type: integer example: 28 hours: type: integer example: 18 minutes: type: integer example: 51 seconds: type: integer example: 22 total_seconds: type: integer example: 2487082 sun: type: object properties: sunrise: type: integer example: 1768291282 sunrise_timestamp: type: string example: 08:01 sunset: type: integer example: 1768321044 sunset_timestamp: type: string example: '16:17' solar_noon: type: string example: '12:09' day_length: type: string example: 08:16 position: type: object properties: altitude: type: number example: -15.787896 azimuth: type: number example: 255.330169 distance: type: number example: 147145019639.96698 next_solar_eclipse: type: object properties: timestamp: type: integer example: 1771329600 datestamp: type: string example: Tue, 17 Feb 2026 12:00:00 +0000 type: type: string example: Annular Solar Eclipse visibility_regions: type: string example: 's Argentina & Chile, s Africa, Antarctica ; [Annular: Antarctica]' next_transit: type: object properties: timestamp: type: integer example: 1983944460 datestamp: type: string example: Sat, 13 Nov 2032 07:41:00 +0000 planet: type: string example: Mercury type: type: string example: Mercury Transit visibility_regions: type: string example: Americas, Europe, Africa, Asia, Australia (visible where Sun is above horizon) moon: type: object properties: phase: type: number example: 0.8294482328 phase_name: type: string example: Waning crescent major_phase: type: string example: New Moon stage: type: string example: waning illumination: type: string example: 22% age_days: type: integer example: 24 lunar_cycle: type: string example: 22.49% emoji: type: string example: 🌒 zodiac: type: object properties: sun_sign: type: string example: Capricorn moon_sign: type: string example: Scorpio moonrise: type: string example: 02:27 moonrise_timestamp: type: integer example: 1768184871 moonset: type: string example: '11:17' moonset_timestamp: type: integer example: 1768216634 detailed: type: object properties: position: type: object properties: altitude: type: number example: -55.204021 azimuth: type: number example: 308.80069 distance: type: number example: 405395288.669185 parallactic_angle: type: number example: 29.033486 phase_angle: type: number example: 123.39 visibility: type: object properties: visible_hours: type: integer example: 0 best_viewing_time: type: string example: 02:27 visibility_rating: type: string example: Poor illumination: type: string example: 22.49% viewing_conditions: type: object properties: phase_quality: type: string example: Good for observing surface detail along terminator line recommended_equipment: type: object properties: filters: type: string example: No filters needed telescope: type: string example: 4-inch or larger recommended best_magnification: type: string example: High magnification (100-200x) for crater detail upcoming_phases: type: object properties: new_moon: type: object properties: last: type: object properties: timestamp: type: integer datestamp: type: string days_ago: type: integer next: type: object properties: timestamp: type: integer datestamp: type: string days_ahead: type: integer first_quarter: type: object properties: last: type: object properties: timestamp: type: integer datestamp: type: string days_ago: type: integer next: type: object properties: timestamp: type: integer datestamp: type: string days_ahead: type: integer full_moon: type: object properties: last: type: object properties: timestamp: type: integer datestamp: type: string days_ago: type: integer name: type: string description: type: string next: type: object properties: timestamp: type: integer datestamp: type: string days_ahead: type: integer name: type: string description: type: string last_quarter: type: object properties: last: type: object properties: timestamp: type: integer datestamp: type: string days_ago: type: integer next: type: object properties: timestamp: type: integer datestamp: type: string days_ahead: type: integer illumination_details: type: object properties: percentage: type: number example: 22.49 visible_fraction: type: number example: 0.2249 phase_angle: type: number example: 123.39 events: type: object properties: moonrise_visible: type: boolean example: true moonset_visible: type: boolean example: true optimal_viewing_period: type: object properties: start_time: type: string example: 02:27 end_time: type: string example: '11:17' duration_hours: type: integer example: 8 viewing_quality: type: string example: Good for crater observation along terminator recommendations: type: array items: type: string example: - Visible most of the night - Good period for observing maria (dark areas) and mountain ranges - Medium to high magnification recommended for detail next_lunar_eclipse: type: object properties: timestamp: type: integer example: 1772537640 datestamp: type: string example: Tue, 03 Mar 2026 11:34:00 +0000 description: Maximum eclipse time type: type: string example: Total Lunar Eclipse visibility_regions: type: string example: eastern Asia, Australia, Pacific, Americas parameters: longitudeParam: name: lon in: query description: Longitude coordinate (-180 to 180). Optional, defaults to -0.1278 (London, UK - west is negative) required: false schema: type: number minimum: -180 maximum: 180 default: -0.1278 latitudeParam: name: lat in: query description: Latitude coordinate (-90 to 90). Optional, defaults to 51.5074 (London, UK) required: false schema: type: number minimum: -90 maximum: 90 default: 51.5074 securitySchemes: RapidAPIKey: type: apiKey name: x-rapidapi-key in: header description: RapidAPI authentication key