Personal Horoscope Endpoints

Calculate personalized horoscopes and daily insights with optional AI interpretations.

Perfect for timing analysis, daily horoscopes, and astrological forecasting.

---

Personalized Horoscope

Calculate personalized horoscope based on a specific natal chart with integration of both astrology and numerology.

Endpoint

POST /api/v1/transits

Pricing

Variable pricing based on period and AI inclusion:

Request Body

{
  "birthDate": "1990-12-25",        // Required: YYYY-MM-DD
  "birthTime": "14:30",              // Required: HH:MM (24h)
  "city": "New York",                // Required
  "country": "USA",                  // Required
  "latitude": 40.7128,               // Required
  "longitude": -74.0060,             // Required
  "timezone": "America/New_York",    // Required
  "date": "2025-01-15",              // Optional: defaults to today
  "period": "day",                   // Optional: "day", "week", "month" (default: "day")
  "includeAI": false,                // Optional: defaults to false (set to true for AI interpretation)
  "blueprintId": "bp_abc123",        // Optional: link to existing blueprint
  "name": "My January Transits"      // Optional: custom name for saved transit
}

What's Included

Horoscope Data (Always included):

• ✓ Major transits (transiting planets aspecting natal planets)
• ✓ Significant current aspects between transiting planets
• ✓ Exact aspects (orb < 1°)
• ✓ Lunar phase and illumination percentage
• ✓ Numerology cycles (Personal Year, Month, Day)
• ✓ Dominant energy assessment
• ✓ Key influences summary

AI Interpretation (Optional, +20 credits):

• ✓ Holistic analysis integrating astrology AND numerology
• ✓ Overall energy & theme with numerological context
• ✓ Key areas of focus (both astrological & numerological)
• ✓ Practical guidance aligned with both systems
• ✓ Opportunities and challenges
• ✓ Actionable advice

Response Example

{
  "success": true,
  "data": {
    "id": "transit_xyz789",
    "period": "day",
    "date": "2025-01-15",
    "transits": {
      "majorTransits": [
        {
          "transitingPlanet": "JUPITER",
          "natalPlanet": "SUN",
          "aspect": "trine",
          "orb": 0.5,
          "isExact": true,
          "strength": "very strong",
          "influence": "harmonious",
          "description": "Jupiter trine natal Sun brings expansion and optimism"
        },
        {
          "transitingPlanet": "SATURN",
          "natalPlanet": "MOON",
          "aspect": "square",
          "orb": 2.1,
          "isExact": false,
          "strength": "moderate",
          "influence": "challenging",
          "description": "Saturn square natal Moon requires emotional discipline"
        }
      ],
      "significantAspects": [
        {
          "planet1": "SUN",
          "planet2": "MERCURY",
          "aspect": "conjunction",
          "orb": 0.3,
          "description": "Mental clarity and communication focus"
        }
      ],
      "lunarPhase": {
        "phase": "Waxing Crescent",
        "illumination": 23.5,
        "description": "Building energy, time for growth"
      },
      "numerology": {
        "personalYear": {
          "number": 7,
          "description": "Personal Year 7: A year of reflection, spiritual growth, and inner wisdom"
        },
        "personalMonth": {
          "number": 5,
          "description": "Personal Month 5: A month of change, freedom, and new experiences"
        },
        "personalDay": {
          "number": 3,
          "description": "Personal Day 3: A day for creativity, self-expression, and social connection"
        }
      },
      "dominantEnergy": "Harmonious Flow with Grounding Challenges",
      "keyInfluences": [
        "Jupiter expansion energy",
        "Saturn discipline lessons",
        "Personal Year 7 introspection"
      ]
    },
    "aiInterpretation": {
      "summary": "Today brings a beautiful blend of Jupiter's expansive energy harmonizing with your Sun, while Saturn challenges your Moon to establish stronger emotional boundaries. In your Personal Year 7, this is a day (Personal Day 3) to express your inner wisdom creatively...",
      "opportunities": "This is an excellent time for personal growth, creative expression, and spiritual development. Jupiter's trine to your Sun amplifies confidence and optimism...",
      "challenges": "Be mindful of Saturn's square to your Moon, which may bring emotional heaviness or a sense of restriction. Don't let temporary feelings dampen the Jupiter optimism...",
      "advice": "Focus your energy on balancing expansion with discipline. Use Personal Day 3's creative energy to express your Personal Year 7 insights. Journaling or artistic pursuits can help integrate these energies..."
    }
  },
  "meta": {
    "creditsUsed": 21,
    "creditsRemaining": 1979
  }
}

Use Cases

Daily Horoscopes:

• Generate personalized daily forecasts
• Timing for important decisions
• Energy awareness and planning

Weekly Planning:

• Business planning and scheduling
• Relationship timing
• Project launch dates

Monthly Forecasting:

• Life planning and goal setting
• Career moves and transitions
• Long-term strategic planning

---

Global Daily Insight

Get today's daily insight without requiring a natal chart. Perfect for general daily insights and current sky conditions.

Endpoint

GET /api/v1/transits/today

Pricing

1 credit - Fixed cost

Response Example

{
  "success": true,
  "data": {
    "date": "2025-01-15",
    "planetaryPositions": {
      "sun": { "sign": "Capricorn", "degree": 25.3 },
      "moon": { "sign": "Pisces", "degree": 12.8 },
      "mercury": { "sign": "Capricorn", "degree": 18.5, "isRetrograde": false },
      "venus": { "sign": "Aquarius", "degree": 5.2 },
      "mars": { "sign": "Cancer", "degree": 28.7 },
      "jupiter": { "sign": "Taurus", "degree": 14.3 },
      "saturn": { "sign": "Pisces", "degree": 9.1 },
      "uranus": { "sign": "Taurus", "degree": 22.8, "isRetrograde": true },
      "neptune": { "sign": "Pisces", "degree": 27.4 },
      "pluto": { "sign": "Aquarius", "degree": 1.2 }
    },
    "significantAspects": [
      {
        "planet1": "SUN",
        "planet2": "JUPITER",
        "aspect": "trine",
        "orb": 0.8,
        "description": "Optimism and expansion energy"
      },
      {
        "planet1": "VENUS",
        "planet2": "MARS",
        "aspect": "opposition",
        "orb": 2.5,
        "description": "Tension between love and action"
      }
    ],
    "lunarPhase": {
      "phase": "Waxing Crescent",
      "illumination": 23.5,
      "nextPhase": "First Quarter",
      "daysUntilNextPhase": 3
    },
    "dominantEnergy": "Practical earth energy with emotional water depth"
  },
  "meta": {
    "creditsUsed": 1,
    "creditsRemaining": 1978
  }
}

Use Cases

• General daily insights
• Astrological weather reports
• Current sky conditions
• Timing for general audience

---

List Saved Personal Horoscopes

Retrieve all personal horoscopes calculated for the authenticated user.

Endpoint

GET /api/v1/transits/list

Pricing

0 credits - Retrieval only

Response Example

{
  "success": true,
  "data": {
    "transits": [
      {
        "id": "transit_xyz789",
        "name": "My January Transits",
        "date": "2025-01-15",
        "period": "day",
        "blueprintId": "bp_abc123",
        "hasAI": true,
        "createdAt": "2025-01-15T10:00:00Z"
      },
      // ... more transits
    ]
  },
  "meta": {
    "creditsUsed": 0,
    "count": 15
  }
}

---

Get Personal Horoscope by ID

Retrieve a specific saved personal horoscope by its ID.

Endpoint

GET /api/v1/transits/:id

Pricing

0 credits - Retrieval only

Response Example

Returns the same full horoscope data as the create endpoint, including all calculations and AI interpretation (if it was generated).

---

Personal Horoscope Metadata

Get lightweight horoscope metadata for list views without full horoscope data. Perfect for displaying horoscope lists efficiently.

Endpoint

GET /api/v1/transits/metadata

Pricing

0 credits - Retrieval only

Response Example

{
  "success": true,
  "data": {
    "transits": [
      {
        "id": "transit_xyz789",
        "name": "My January Transits",
        "date": "2025-01-15",
        "period": "day",
        "blueprintId": "bp_abc123",
        "blueprintName": "John Doe",
        "hasAI": true,
        "createdAt": "2025-01-15T10:00:00Z"
      },
      // ... more transit metadata
    ]
  },
  "meta": {
    "creditsUsed": 0,
    "count": 15
  }
}

---

Pricing Summary

---

Error Responses

{
  "error": "Invalid period",
  "message": "Period must be 'day', 'week', or 'month'"
}

{
  "error": "Blueprint not found",
  "message": "The specified blueprint does not exist or does not belong to you"
}

{
  "error": "Insufficient credits",
  "message": "This personal horoscope costs 21 credits",
  "required": 21,
  "available": 10
}