================================================================================
                        ASTROLOGY API DOCUMENTATION
================================================================================

Base URL:  http://172.16.16.148:8000
Documentation:  http://172.16.16.148:8000

================================================================================
1. ROOT API
================================================================================

URL: GET /

Response:
{
  "message": "Astrology API is running",
  "docs": "/docs",
  "birth_chart_api": "/calculators/birth-chart",
  "chart_data_api": "/chart-data",
  "synastry_chart_api": "/synastry-chart",
  "synastry_aspects_api": "/synastry-aspects",
  "composite_chart_api": "/calculators/composite-chart",
  "lunar_return_api": "/calculators/lunar-return",
  "solar_return_api": "/calculators/solar-return",
  "charts_static_url": "/charts"
}

================================================================================
2. BIRTH CHART API
================================================================================

URL: POST /calculators/birth-chart

Payload:
{
  "name": "User",
  "year": 2003,
  "month": 11,
  "day": 18,
  "hour": 12,
  "minute": 0,
  "second": 0,
  "latitude": 22.8173,
  "longitude": 70.8377,
  "timezone": 5.5
}

Response:
{
  "chart": "/charts/birthchart/filename.svg",
  "ascendant": "...",
  "ascendant_sign": "...",
  "midheaven": "...",
  "imum_coeli": "...",
  "descendant": "...",
  "vertex": "...",
  "planets": [
    {
      "planet": "Sun",
      "sign": "Scorpio",
      "degree": "25° 30'",
      "house": 8,
      "longitude": 234.5
    },
    ...
  ],
  "moon_phase": "...",
  "major_aspects": [...],
  "minor_aspects": [...],
  "aspects": [...],
  "upcoming_aspects": [...],
  "chart_patterns": [...]
}

================================================================================
3. PROGRESSED CHART API
================================================================================

URL: POST /calculators/progressed-chart

Payload:
{
  "name": "User",
  "birth_date": "2003-11-18",
  "birth_time": "12:00",
  "birth_latitude": 22.8173,
  "birth_longitude": 70.8377,
  "birth_timezone": "Asia/Kolkata",
  "birth_place": "Morbi, Gujarat, India",
  "birth_nation": "IN",
  "current_date": "2026-05-19",
  "house_system": "Placidus"
}

Response:
{
  "name": "User",
  "birth_date": "2003-11-18",
  "birth_time": "12:00",
  "birth_location": "Morbi, Gujarat, India",
  "birth_latitude": 22.8173,
  "birth_longitude": 70.8377,
  "birth_timezone": "Asia/Kolkata",
  "current_date": "2026-05-19",
  "age": 22.5,
  "progressed_date": "2026-05-19",
  "progressed_time": "12:00",
  "house_system": "Placidus",
  "chart": "/charts/progressed/filename.svg",
  "natal_planets": [
    {
      "id": "sun",
      "planet": "Sun",
      "sign": "Scorpio",
      "degree": "25° 30'",
      "longitude": 234.5,
      "house": 8,
      "retrograde": false
    },
    ...
  ],
  "progressed_planets": [...],
  "major_aspects": [
    {
      "progressed_planet": "Moon",
      "natal_planet": "Sun",
      "aspect": "Conjunction",
      "symbol": "☌",
      "orb": "0° 30'",
      "orb_value": 0.5
    },
    ...
  ],
  "minor_aspects": [...],
  "details": {
    "place": "Morbi, Gujarat, India",
    "latitude": 22.8173,
    "longitude": 70.8377
  }
}

================================================================================
4. SYNASTRY CHART API
================================================================================

URL: POST /synastry-chart

Payload:
{
  "name1": "User1",
  "year1": 2003,
  "month1": 11,
  "day1": 18,
  "hour1": 12,
  "minute1": 0,
  "lat1": 22.8173,
  "lng1": 70.8377,
  "tz1": "Asia/Kolkata",
  "name2": "User2",
  "year2": 2000,
  "month2": 5,
  "day2": 15,
  "hour2": 6,
  "minute2": 30,
  "lat2": 19.0760,
  "lng2": 72.8777,
  "tz2": "Asia/Kolkata"
}

Response:
{
  "chart": "/charts/synastry-chart/filename.svg",
  "aspects": [...]
}

================================================================================
5. SYNASTRY ASPECTS API
================================================================================

URL: POST /synastry-aspects

Payload:
{
  "user_planets": [
    {"planet": "Sun", "sign": "Scorpio", "degree": 25.5, "longitude": 234.5},
    ...
  ],
  "partner_planets": [
    {"planet": "Sun", "sign": "Leo", "degree": 10.2, "longitude": 130.2},
    ...
  ]
}

Response:
{
  "major_aspects": [
    {
      "aspect_type": "Conjunction",
      "planet1": "Sun",
      "planet2": "Sun",
      "orb": 1.7
    },
    ...
  ],
  "minor_aspects": [...]
}

================================================================================
6. SYNASTRY PATTERNS API
================================================================================

URL: POST /synastry-patterns

Payload: Same as synastry-aspects

Response:
{
  "patterns": [...]
}

================================================================================
7. LUNAR RETURN API
================================================================================

URL: POST /calculators/lunar-return

Payload:
{
  "name": "User",
  "year": 2003,
  "month": 11,
  "day": 18,
  "hour": 12,
  "minute": 0,
  "second": 0,
  "latitude": 22.8173,
  "longitude": 70.8377,
  "timezone": 5.5,
  "birth_place": "Morbi",
  "return_year": 2026,
  "return_month": 5,
  "return_latitude": 22.8173,
  "return_longitude": 70.8377,
  "return_timezone": 5.5,
  "return_place": "Morbi"
}

Response:
{
  "success": true,
  "result_id": "1234567",
  "redirect_url": "/calculators/lunar-return-chart/1234567",
  "data": {
    "chart": "/charts/lunar-return/filename.svg",
    "lunar_return_date": "2026-05-19",
    "planets": [...],
    ...
  }
}

================================================================================
8. GET LUNAR RETURN RESULT
================================================================================

URL: GET /calculators/lunar-return-chart/{result_id}

Response: Returns stored lunar return data with chart

================================================================================
9. SOLAR RETURN API
================================================================================

URL: POST /calculators/solar-return

Payload:
{
  "name": "User",
  "year": 2003,
  "month": 11,
  "day": 18,
  "hour": 12,
  "minute": 0,
  "second": 0,
  "latitude": 22.8173,
  "longitude": 70.8377,
  "timezone": 5.5,
  "birth_place": "Morbi",
  "return_year": 2026,
  "return_latitude": 22.8173,
  "return_longitude": 70.8377,
  "return_timezone": 5.5,
  "return_place": "Morbi"
}

Response:
{
  "success": true,
  "result_id": "1234567",
  "redirect_url": "/calculators/solar-return-chart/1234567",
  "data": {
    "chart": "/charts/solar-return/filename.svg",
    "solar_return_date": "2026-06-21",
    "planets": [...],
    ...
  }
}

================================================================================
10. GET SOLAR RETURN RESULT
================================================================================

URL: GET /calculators/solar-return-chart/{result_id}

Response: Returns stored solar return data with chart

================================================================================
11. SATURN RETURN API
================================================================================

URL: POST /calculators/saturn-return-chart

Payload: Same as birth chart + target year

Response:
{
  "result_id": "1234567",
  "data": {...}
}

================================================================================
12. GET SATURN RETURN RESULT
================================================================================

URL: GET /calculators/saturn-return-chart/{result_id}

Response: Returns stored Saturn return data with chart

================================================================================
13. COMPOSITE CHART API
================================================================================

URL: POST /calculators/composite-chart

Payload: Two birth data objects

Response:
{
  "result_id": "1234567",
  "data": {...}
}

================================================================================
14. GET COMPOSITE CHART RESULT
================================================================================

URL: GET /calculators/composite-chart/{result_id}

Response: Returns stored composite chart data with chart

================================================================================
15. TRANSIT CHART API
================================================================================

URL: POST /calculators/transit-chart/generate

Payload:
{
  "name": "User",
  "birth_year": 2003,
  "birth_month": 11,
  "birth_day": 18,
  "birth_hour": 12,
  "birth_minute": 0,
  "birth_latitude": 22.8173,
  "birth_longitude": 70.8377,
  "birth_timezone": "Asia/Kolkata",
  "transit_year": 2026,
  "transit_month": 5,
  "transit_day": 19,
  "transit_hour": 12,
  "transit_minute": 0,
  "transit_latitude": 22.8173,
  "transit_longitude": 70.8377,
  "transit_timezone": "Asia/Kolkata"
}

Response:
{
  "status": "success",
  "chart_url": "/charts/transit/filename.svg",
  "filename": "filename.svg",
  "message": "Transit chart generated successfully"
}

================================================================================
16. CHART DATA API
================================================================================

URL: POST /chart-data

Payload:
{
  "year": 2003,
  "month": 11,
  "day": 18,
  "hour": 12,
  "minute": 0,
  "second": 0,
  "latitude": 22.8173,
  "longitude": 70.8377,
  "timezone": 5.5
}

Response:
{
  "planets": [
    {
      "id": "sun",
      "planet": "Sun",
      "sign": "Scorpio",
      "degree": "25° 30'",
      "house": 8,
      "retrograde": false,
      "longitude": 234.5
    },
    ...
  ],
  "moon_phase": "Waxing Gibbous"
}

================================================================================
17. MOON PHASE API
================================================================================

URL: POST /calculator/moon-phase

Payload: Same as chart-data

Response:
{
  "planet": "Moon",
  "sign": "Scorpio",
  "degree": "10° 15'",
  "house": 7,
  "moon_phase": "Waxing Gibbous"
}

================================================================================
18. SINGLE PLANET CALCULATOR
================================================================================

URL: POST /calculator/{planet}

Examples:
- /calculator/sun
- /calculator/moon
- /calculator/mercury
- /calculator/venus
- /calculator/mars
- /calculator/jupiter
- /calculator/saturn
- /calculator/uranus
- /calculator/neptune
- /calculator/pluto
- /calculator/north-node
- /calculator/south-node
- /calculator/ascendant
- /calculator/midheaven
- /calculator/imum-coeli
- /calculator/descendant
- /calculator/vertex

Payload: Same as chart-data

Response:
{
  "planet": "Sun",
  "sign": "Scorpio",
  "degree": "25° 30'",
  "house": 8
}

================================================================================
                              END OF API DOCUMENTATION
================================================================================