Standalone Calculations

Fixed Stars

POST /ephemeris/fixed-stars

Calculate positions for fixed stars at a specific moment. Supports individual star names, predefined groups (royal_stars, behenian, navigational, foundation_24, galactic), and magnitude filtering.

Request:

{
  "date_time": {
    "iso": "2000-01-01T12:00:00Z"
  },
  "star_names": ["Regulus", "Spica", "Aldebaran"],
  "star_groups": ["royal_stars", "behenian"],
  "magnitude_limit": 3.5
}

Supported Star Groups:

• royal_stars - The four royal stars of Persia
• behenian - 15 Behenian fixed stars used in medieval astrology
• navigational - Major navigational stars
• foundation_24 - Foundation 24 stars from Project Hindsight
• galactic - Galactic center and supergalactic center

Response:

{
  "success": true,
  "stars": [
    {
      "name": "Regulus",
      "longitude": 149.8934,
      "latitude": 0.4651,
      "sign": "Leo",
      "sign_longitude": 29.8934,
      "magnitude": 1.35,
      "spectral_class": "B7V",
      "constellation": "Leo",
      "traditional_name": "Regulus",
      "distance_light_years": 79.3
    }
  ],
  "calculation_time": "2024-12-10T12:00:00Z",
  "julian_day": 2451545.0
}

---

Midpoints

POST /ephemeris/midpoints

Calculate all pairwise midpoints between celestial bodies for a given datetime. Supports short arc (direct), long arc (opposite), or both.

Request:

{
  "date_time": {
    "iso": "2023-12-07T15:30:00Z"
  },
  "arc_type": "short",
  "include_angles": true,
  "include_occupied": false,
  "orb": 1.0,
  "sort_by": "degree"
}

Parameters:

| Field | Type | Description | |-------|------|-------------| | date_time | DateTimeInput | Datetime for calculation (ISO, components, or Julian day) | | arc_type | string | "short" (direct), "long" (opposite), or "both" | | include_angles | boolean | Include chart angles (ASC, MC) in midpoint pairs | | include_occupied | boolean | Filter to only midpoints occupied by planets (within orb) | | orb | number | Orb in degrees for occupied midpoint detection (default 1.0°) | | sort_by | string | Sort by "degree", "planet1", or "planet2" |

Response:

{
  "success": true,
  "midpoints": [
    {
      "planet1": "Sun",
      "planet2": "Moon",
      "longitude": 123.45,
      "arc_type": "short",
      "sign": "Leo",
      "sign_degrees": 3.45,
      "is_occupied": false,
      "occupying_planets": []
    }
  ],
  "metadata": {
    "calculation_time_ms": 15.3,
    "total_midpoints": 78
  }
}

---

Hermetic Lots

POST /ephemeris/hermetic-lots

Calculate Hermetic lots (Fortune Suite + optional/legacy) for a given datetime and location. Returns normalized lot positions with traditional source references, formulas, and keywords.

Request:

{
  "date_time": {
    "iso": "2000-01-01T12:00:00Z"
  },
  "latitude": 40.7128,
  "longitude": -74.006,
  "include_optional": false,
  "include_legacy": false
}

Parameters:

| Field | Type | Description | |-------|------|-------------| | date_time | DateTimeInput | Chart calculation datetime | | latitude | number | Observer latitude in decimal degrees (-90 to 90) | | longitude | number | Observer longitude in decimal degrees (-180 to 180) | | include_optional | boolean | Include optional catalog lots beyond Fortune Suite | | include_legacy | boolean | Include legacy Hermetic lots from canonical catalog |

Response:

{
  "success": true,
  "lots": [
    {
      "canonical_name": "lot_of_fortune",
      "name": "lot_of_fortune",
      "display_name": "Lot of Fortune",
      "longitude": 145.2341,
      "sign": "Leo",
      "sign_longitude": 25.2341,
      "house": 8,
      "formula_used": "day_formula",
      "keywords": ["material wealth", "body", "fortune"],
      "sources": ["Dorotheus", "Ptolemy"]
    }
  ],
  "metadata": {
    "sect_determination": {
      "is_day_chart": true,
      "sun_above_horizon": true
    },
    "total_lots_calculated": 7,
    "calculation_time_ms": 12.5
  }
}

Fortune Suite Lots:

• Lot of Fortune
• Lot of Spirit
• Lot of Eros
• Lot of Necessity
• Lot of Courage
• Lot of Victory
• Lot of Nemesis

---

Lunar Phase

POST /ephemeris/lunar-phase

Calculate comprehensive lunar phase data including illumination, elongation, phase angle, age, distance, and angular diameter.

Request:

{
  "date_time": {
    "iso": "2000-01-01T12:00:00Z"
  }
}

Response:

{
  "success": true,
  "phase": {
    "name": "Waxing Crescent",
    "illumination": 23.4,
    "phase_angle": 84.6,
    "elongation": 45.2,
    "age_days": 3.2,
    "distance_km": 384400,
    "angular_diameter_arcsec": 1864.5,
    "next_new_moon": "2000-01-15T12:34:56Z",
    "next_full_moon": "2000-01-22T08:45:23Z",
    "lunation_number": 1234
  },
  "metadata": {
    "calculation_time_ms": 5.2,
    "julian_day": 2451545.0
  }
}

Phase Names:

• New Moon
• Waxing Crescent
• First Quarter
• Waxing Gibbous
• Full Moon
• Waning Gibbous
• Last Quarter
• Waning Crescent

Phase Data Fields:

| Field | Description | |-------|-------------| | illumination | Percentage of lunar disk illuminated (0-100) | | phase_angle | Sun-Moon-Earth angle in degrees | | elongation | Angular separation from Sun in degrees | | age_days | Days since last new moon | | distance_km | Earth-Moon distance in kilometers | | angular_diameter_arcsec | Moon's angular diameter in arcseconds | | lunation_number | Brown lunation number |

---

Use Cases

Finding Royal Stars Near Planets

{
  "date_time": { "iso": "1990-06-15T14:30:00" },
  "star_groups": ["royal_stars"],
  "magnitude_limit": 2.0
}

Occupied Midpoints Analysis

{
  "date_time": { "iso": "2000-01-01T00:00:00" },
  "arc_type": "both",
  "include_occupied": true,
  "orb": 1.0
}

Fortune Suite Calculation

{
  "date_time": { "iso": "1985-03-20T08:15:00" },
  "latitude": 37.7749,
  "longitude": -122.4194,
  "include_optional": false,
  "include_legacy": false
}

Moon Phase for Electional Astrology

{
  "date_time": { "iso": "2025-01-15T00:00:00Z" }
}