{
  "openapi": "3.1.0",
  "info": {
    "title": "Mercury Retrograde API",
    "description": "The authoritative API for Mercury retrograde data. Provides real-time astronomical calculations using Swiss Ephemeris with ~36 second precision. Free to use, no authentication required.",
    "version": "1.0.0",
    "contact": {
      "name": "Mercury Retrograde Support",
      "email": "support@mercury-retrograde.com",
      "url": "https://www.mercury-retrograde.com"
    },
    "license": {
      "name": "Free to use",
      "url": "https://www.mercury-retrograde.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.mercury-retrograde.com",
      "description": "Production server"
    }
  ],
  "tags": [
    {"name": "Status", "description": "Current retrograde status and checks"},
    {"name": "Periods", "description": "Query retrograde periods"},
    {"name": "Advanced", "description": "Detailed phase and statistical data"},
    {"name": "Export", "description": "Calendar and data exports"},
    {"name": "Meta", "description": "API information and health"}
  ],
  "paths": {
    "/api/v1/status": {
      "get": {
        "operationId": "getStatus",
        "tags": ["Status"],
        "summary": "Get current Mercury retrograde status",
        "description": "Returns comprehensive current status including phase, countdown, current/next periods, and advanced astronomical data.",
        "responses": {
          "200": {
            "description": "Current retrograde status",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/StatusResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/check": {
      "get": {
        "operationId": "checkDate",
        "tags": ["Status"],
        "summary": "Check retrograde status for a specific date",
        "description": "Check if Mercury is/was/will be retrograde on any date from 1900-2100.",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "description": "Date to check (YYYY-MM-DD format)",
            "schema": {"type": "string", "format": "date"},
            "example": "2026-03-15"
          }
        ],
        "responses": {
          "200": {
            "description": "Retrograde status for the specified date",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CheckResponse"}
              }
            }
          },
          "400": {
            "description": "Invalid date format or missing parameter",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/ErrorResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/next": {
      "get": {
        "operationId": "getNext",
        "tags": ["Status"],
        "summary": "Get next (or current) retrograde period",
        "description": "Returns the next upcoming retrograde period, or the current one if Mercury is currently retrograde.",
        "responses": {
          "200": {
            "description": "Next/current retrograde period with countdown",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/NextResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/countdown": {
      "get": {
        "operationId": "getCountdown",
        "tags": ["Status"],
        "summary": "Get countdown to next retrograde",
        "description": "Optimized endpoint for widgets and quick status checks. Returns countdown days and simple status message.",
        "responses": {
          "200": {
            "description": "Countdown information",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CountdownResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/periods": {
      "get": {
        "operationId": "getPeriodsByRange",
        "tags": ["Periods"],
        "summary": "Get retrograde periods by date range",
        "description": "Query all retrograde periods within a date range (max 10 years).",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "Start date (YYYY-MM-DD)",
            "schema": {"type": "string", "format": "date"}
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "End date (YYYY-MM-DD)",
            "schema": {"type": "string", "format": "date"}
          }
        ],
        "responses": {
          "200": {
            "description": "List of retrograde periods",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PeriodsResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/periods/year": {
      "get": {
        "operationId": "getPeriodsByYear",
        "tags": ["Periods"],
        "summary": "Get all retrograde periods for a year",
        "description": "Returns all Mercury retrograde periods for a specific year with advanced phase data.",
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": true,
            "description": "Year (1900-2100)",
            "schema": {"type": "integer", "minimum": 1900, "maximum": 2100},
            "example": 2026
          }
        ],
        "responses": {
          "200": {
            "description": "All retrograde periods for the year",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/YearResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/phases": {
      "get": {
        "operationId": "getPhases",
        "tags": ["Advanced"],
        "summary": "Get detailed phase data",
        "description": "Returns precise timestamps for all phases: stations, cazimi (inferior conjunction), speed changes, and shadow periods.",
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Year (defaults to current year)",
            "schema": {"type": "integer"}
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed phase information",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PhasesResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/history": {
      "get": {
        "operationId": "getHistory",
        "tags": ["Advanced"],
        "summary": "Get historical retrograde data",
        "description": "Returns past retrograde periods grouped by year.",
        "parameters": [
          {
            "name": "years",
            "in": "query",
            "required": false,
            "description": "Number of years to retrieve (1-50, default: 5)",
            "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 5}
          }
        ],
        "responses": {
          "200": {
            "description": "Historical retrograde data",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/HistoryResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "operationId": "getStats",
        "tags": ["Advanced"],
        "summary": "Get retrograde statistics for a year",
        "description": "Returns statistics including total retrograde days, percentage of year, and average duration.",
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Year (defaults to current year)",
            "schema": {"type": "integer"}
          }
        ],
        "responses": {
          "200": {
            "description": "Year statistics",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/StatsResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/calendar.ics": {
      "get": {
        "operationId": "getCalendar",
        "tags": ["Export"],
        "summary": "Download iCalendar file",
        "description": "Download retrograde periods as an iCalendar (.ics) file for calendar integration.",
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Year to export",
            "schema": {"type": "integer"}
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start date for range export",
            "schema": {"type": "string", "format": "date"}
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End date for range export",
            "schema": {"type": "string", "format": "date"}
          }
        ],
        "responses": {
          "200": {
            "description": "iCalendar file",
            "content": {
              "text/calendar": {
                "schema": {"type": "string"}
              }
            }
          }
        }
      }
    },
    "/api/v1/info": {
      "get": {
        "operationId": "getInfo",
        "tags": ["Meta"],
        "summary": "Get API information",
        "description": "Returns API documentation, available endpoints, and usage information.",
        "responses": {
          "200": {
            "description": "API information",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/InfoResponse"}
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getHealth",
        "tags": ["Meta"],
        "summary": "Health check",
        "description": "Check if the API is operational.",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/HealthResponse"}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {"type": "boolean", "example": true},
          "message": {"type": "string"},
          "status": {"type": "integer"},
          "error_code": {"type": "string"}
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "source": {"type": "string", "example": "mercury-retrograde.com"},
          "calculation_method": {"type": "string", "example": "Swiss Ephemeris"},
          "precision": {"type": "string", "example": "~36 seconds"},
          "api_version": {"type": "string", "example": "1.0"}
        }
      },
      "Period": {
        "type": "object",
        "properties": {
          "pre_shadow_start": {"type": "string", "format": "date", "nullable": true},
          "retrograde_start": {"type": "string", "format": "date"},
          "retrograde_end": {"type": "string", "format": "date"},
          "post_shadow_end": {"type": "string", "format": "date", "nullable": true},
          "retrograde_duration_days": {"type": "integer"},
          "total_cycle_duration_days": {"type": "integer"}
        }
      },
      "AdvancedPhases": {
        "type": "object",
        "properties": {
          "pre_shadow_start": {"type": "string", "format": "date-time", "nullable": true},
          "speed_slowdown": {"type": "string", "format": "date-time", "nullable": true},
          "station_retrograde": {
            "type": "object",
            "properties": {
              "datetime": {"type": "string", "format": "date-time"},
              "zodiac_degree": {"type": "string"},
              "degree_decimal": {"type": "number"}
            },
            "nullable": true
          },
          "inferior_conjunction": {
            "type": "object",
            "properties": {
              "datetime": {"type": "string", "format": "date-time"},
              "zodiac_degree": {"type": "string"},
              "degree_decimal": {"type": "number"}
            },
            "nullable": true
          },
          "station_direct": {
            "type": "object",
            "properties": {
              "datetime": {"type": "string", "format": "date-time"},
              "zodiac_degree": {"type": "string"},
              "degree_decimal": {"type": "number"}
            },
            "nullable": true
          },
          "speed_normalization": {"type": "string", "format": "date-time", "nullable": true},
          "post_shadow_end": {"type": "string", "format": "date-time", "nullable": true}
        }
      },
      "StatusResponse": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "enum": ["retrograde", "not_retrograde"]},
          "is_retrograde": {"type": "boolean"},
          "current_phase": {"type": "string", "enum": ["normal", "pre_shadow", "retrograde", "post_shadow"]},
          "phase_description": {"type": "string"},
          "date": {"type": "string", "format": "date"},
          "timestamp": {"type": "string", "format": "date-time"},
          "countdown": {"type": "object"},
          "current_period": {"$ref": "#/components/schemas/Period"},
          "next_period": {"$ref": "#/components/schemas/Period"},
          "advanced_phases": {"$ref": "#/components/schemas/AdvancedPhases"},
          "upcoming_periods": {"type": "array", "items": {"$ref": "#/components/schemas/Period"}},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "CheckResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "object",
            "properties": {
              "date": {"type": "string", "format": "date"},
              "temporal": {"type": "string", "enum": ["past", "present", "future"]}
            }
          },
          "result": {
            "type": "object",
            "properties": {
              "is_retrograde": {"type": "boolean"},
              "phase": {"type": "string"},
              "phase_description": {"type": "string"}
            }
          },
          "period": {"$ref": "#/components/schemas/Period"},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "NextResponse": {
        "type": "object",
        "properties": {
          "is_current": {"type": "boolean"},
          "countdown": {"type": "object"},
          "period": {"$ref": "#/components/schemas/Period"},
          "today": {"type": "string", "format": "date"},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "CountdownResponse": {
        "type": "object",
        "properties": {
          "status": {"type": "string"},
          "message": {"type": "string"},
          "countdown": {"type": "object"},
          "today": {"type": "string", "format": "date"},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "PeriodsResponse": {
        "type": "object",
        "properties": {
          "query": {"type": "object"},
          "count": {"type": "integer"},
          "periods": {"type": "array", "items": {"$ref": "#/components/schemas/Period"}},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "YearResponse": {
        "type": "object",
        "properties": {
          "query": {"type": "object"},
          "count": {"type": "integer"},
          "periods": {"type": "array", "items": {"$ref": "#/components/schemas/Period"}},
          "summary": {"type": "object"},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "PhasesResponse": {
        "type": "object",
        "properties": {
          "query": {"type": "object"},
          "count": {"type": "integer"},
          "cycles": {"type": "array"},
          "phase_descriptions": {"type": "object"},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "HistoryResponse": {
        "type": "object",
        "properties": {
          "query": {"type": "object"},
          "total_periods": {"type": "integer"},
          "average_per_year": {"type": "number"},
          "by_year": {"type": "object"},
          "periods": {"type": "array", "items": {"$ref": "#/components/schemas/Period"}},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "query": {"type": "object"},
          "statistics": {"type": "object"},
          "retrograde_periods": {"type": "array"},
          "fun_facts": {"type": "object"},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "InfoResponse": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "version": {"type": "string"},
          "description": {"type": "string"},
          "base_url": {"type": "string"},
          "endpoints": {"type": "object"},
          "meta": {"$ref": "#/components/schemas/Meta"}
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "enum": ["healthy", "unhealthy"]},
          "timestamp": {"type": "string", "format": "date-time"},
          "checks": {"type": "object"}
        }
      }
    }
  }
}