Astrology API Reference

Comprehensive astrological services including natal charts, daily horoscopes, and advanced transit calculations powered by accurate astronomical data and AI-generated interpretations.

Base URL

https://api.mysticalapi.com/v1

Three-Tier Horoscope System

Choose the right level of detail for your application:

Tier	Endpoint	Method	Features	Use Case
Basic	`/astrology/daily-horoscope`	POST	Simple interpretation, fast response	Quick daily check
Enhanced	`/astrology/daily-horoscope`	POST/GET	8 categories + lucky elements	Detailed guidance
Personalized	`/astrology/personalized-daily`	POST	Birth chart + transit aspects	Individual analysis

Endpoints Overview

Endpoint	Method	Description	Week 8 Updates
`/astrology/health`	GET	Service health check	-
`/astrology/natal-chart`	POST	Calculate birth chart with advanced house systems	-
`/astrology/daily-horoscope`	POST	Generate daily horoscope (basic/enhanced)	✓ Categories, date keywords
`/astrology/horoscope/daily/:sign`	GET	Simple GET wrapper for daily horoscope	✓ New
`/astrology/personalized-daily`	POST	Personalized horoscope using birth chart	✓ New

Daily Horoscope Endpoint

Generate personalized daily horoscopes with real-time planetary transit analysis and AI-powered interpretations in multiple styles.

📅 POST `/astrology/daily-horoscope`

Features:

Real-time planetary transit calculations
AI-powered interpretations using Gemini 2.5 Flash
Multiple style variations (brief, detailed, poetic)
24-hour intelligent caching for optimal performance
Location-aware transit calculations
Content safety validation

Request Schema

json

{
  "sign": "aries",                    // Required: zodiac sign (case-insensitive)
  "date": "today",                   // Optional: YYYY-MM-DD, "today", "tomorrow", "yesterday"
  "style": "detailed",               // Optional: "brief" | "detailed" | "poetic" (default: "brief")
  "categories": ["all"],             // NEW: [\"all\"] or specific ["love", "career", "health"]
  "location": {                      // Optional: for more accurate transit calculations
    "latitude": 34.0522,
    "longitude": -118.2437
  },
  "timezone": "America/Los_Angeles"  // Optional: IANA timezone (default: UTC)
}

Response Schema

json

{
  "success": true,
  "requestId": "hor_1640995200_abc123",
  "data": {
    "horoscope_id": "hor_1640995200_def456",
    "sign": "aries",
    "date": "2025-09-24",
    "style": "detailed",
    "location": {
      "latitude": 34.0522,
      "longitude": -118.2437
    },
    "transits": {
      "planetary_positions": {
        "sun": {
          "longitude": 300.45,
          "latitude": 0.0,
          "sign": "Capricorn",
          "degree_in_sign": 0.45,
          "retrograde": false
        },
        "moon": {
          "longitude": 45.23,
          "latitude": 5.12,
          "sign": "Taurus",
          "degree_in_sign": 15.23,
          "retrograde": false
        }
        // ... other planets (Mercury through Pluto)
      },
      "aspects": [
        {
          "planet": "mars",
          "aspect": "square",
          "orb": 3.2,
          "strength": "moderate",
          "nature": "challenging",
          "keywords": ["action", "tension", "breakthrough"]
        }
      ],
      "planets_in_sign": [
        {
          "planet": "venus",
          "degree_in_sign": 23.7,
          "retrograde": false,
          "keywords": ["love", "harmony", "relationships"]
        }
      ],
      "overall_influence": {
        "score": 2.1,
        "overall_tone": "positive"
      }
    },
    "interpretation": {
      "summary": "Today brings powerful energy for Aries as Mars forms a dynamic square with Jupiter...",
      "love": "Passionate connections are highlighted with Venus in your partnership sector...",
      "career": "Professional opportunities emerge through networking and collaboration...",
      "wellbeing": "Focus on maintaining balance between ambition and rest...",
      "lucky_elements": {
        "colors": ["red", "gold"],
        "numbers": [3, 7, 21],
        "keywords": ["courage", "leadership", "innovation"]
      }
    },
    "categories": {                     // NEW: Enhanced category predictions
      "personal_life": {
        "outlook": "positive",
        "intensity": "medium",
        "influence_score": 2.3,
        "interpretation": "Family connections strengthen today...",
        "advice": "Focus on quality time with loved ones",
        "themes": ["family", "home", "personal growth"]
      },
      "love": {
        "outlook": "challenging",
        "intensity": "high",
        "influence_score": -1.8,
        "interpretation": "Romantic tensions may surface requiring patience...",
        "advice": "Communicate openly and avoid assumptions",
        "themes": ["communication", "passion", "understanding"]
      }
      // ... 6 more categories: health, profession, emotions, travel, luck, finance
    },
    "lucky_elements": {                // NEW: Enhanced lucky elements
      "numbers": [7, 14, 23],
      "colors": ["emerald green", "gold"],
      "times": ["early morning", "sunset"],
      "primary_influence": "venus"
    },
    "metadata": {
      "calculation_time_ms": 142,
      "transit_count": 8,
      "planets_in_sign_count": 2,
      "overall_score": 2.1,
      "overall_tone": "positive",
      "calculated_at": "2025-01-20T12:00:00.000Z",
      "timezone": "America/Los_Angeles",
      "confidence_score": 0.89,
      "style_applied": "detailed",
      "cache_hit": false
    }
  },
  "timestamp": "2025-01-20T12:00:00.000Z"
}

Style Options & Enhancements

Style	Summary Length	Use Case	Categories	Lucky Elements
brief	80-150 chars	Quick daily check, mobile apps	❌ No	❌ No
detailed	150-250 chars	Comprehensive guidance	✅ Auto-included	✅ Auto-included
poetic	120-200 chars	Spiritual/mystical tone	✅ If requested	✅ If requested

Category Predictions (Enhanced Feature)

When style: "detailed" or categories: ["all"] is specified, the response includes predictions for 8 life areas:

Category	Focus Area	Keywords
personal_life	Family, home, personal growth	family, identity, self-care
love	Romance, relationships, partnerships	romance, attraction, harmony
health	Physical/mental wellbeing	vitality, balance, healing
profession	Career, work, business	ambition, success, recognition
emotions	Emotional state, mood, inner world	feelings, intuition, processing
travel	Movement, journeys, exploration	adventure, change, expansion
luck	Opportunities, fortune, serendipity	timing, chance, manifestation
finance	Money, resources, material security	abundance, investment, stability

Category Response Structure:

json

{
  "category_name": {
    "outlook": "positive" | "challenging" | "neutral",
    "intensity": "low" | "medium" | "high",
    "influence_score": -10.0 to +10.0,
    "interpretation": "Detailed prediction for this area...",
    "advice": "Specific actionable guidance...",
    "themes": ["keyword1", "keyword2", "keyword3"]
  }
}

Lucky Elements (Enhanced Feature)

Enhanced lucky elements provide practical guidance:

json

{
  "lucky_elements": {
    "numbers": [7, 14, 23],                    // Significant numbers for the day
    "colors": ["emerald green", "gold"],       // Favorable colors to wear/use
    "times": ["early morning", "sunset"],      // Best times for important activities
    "primary_influence": "venus"               // Planet driving today's luck
  }
}

Code Examples

Basic Horoscope Request

Enhanced Horoscope with Categories

Dated Horoscope with Location

GET Daily Horoscope Endpoint (Simplified)

Simplified GET endpoint for quick horoscope retrieval with automatic enhanced features.

🚀 GET `/astrology/horoscope/daily/:sign`

Features:

One-line integration: Just append the zodiac sign to the URL
Automatic enhancement: Always returns detailed style with all 8 categories
Today's date: Always fetches today's horoscope
All lucky elements: Numbers, colors, times included automatically
Mobile-friendly: Perfect for mobile apps and simple integrations

Request Parameters

Parameter	Type	Description	Example
`sign`	string	Zodiac sign (case-insensitive)	`aries`, `SCORPIO`, `Leo`

Usage Examples

Response Structure

The GET endpoint returns the same enhanced response as POST with style: "detailed" and categories: ["all"]:

json

{
  "success": true,
  "data": {
    "sign": "gemini",
    "date": "2025-09-24",
    "style": "detailed",
    "categories": {
      "personal_life": { /* category details */ },
      "love": { /* category details */ },
      "health": { /* category details */ },
      // ... all 8 categories
    },
    "lucky_elements": {
      "numbers": [3, 12, 27],
      "colors": ["yellow", "silver"],
      "times": ["morning", "late evening"],
      "primary_influence": "mercury"
    }
    // ... full response structure
  }
}

Mobile App Integration

Perfect for mobile applications requiring minimal setup:

javascript

// React Native example
const fetchDailyHoroscope = async (userSign) => {
  try {
    const response = await fetch(`https://api.mysticalapi.com/v1/astrology/horoscope/daily/${userSign}`);
    const data = await response.json();

    return {
      summary: data.data.interpretation.summary,
      loveAdvice: data.data.categories.love.interpretation,
      careerAdvice: data.data.categories.profession.interpretation,
      luckyNumbers: data.data.lucky_elements.numbers,
      luckyColors: data.data.lucky_elements.colors
    };
  } catch (error) {
    console.error('Horoscope fetch failed:', error);
    return null;
  }
};

Personalized Daily Horoscope Endpoint

Get truly personalized horoscopes based on your exact birth chart and current planetary transits.

🎯 POST `/astrology/personalized-daily`

Features:

Birth Chart Integration: Uses your exact natal chart positions
Transit Aspects: Calculates real aspects between natal planets and current transits
Personalized Categories: 8 life areas tailored to your chart
Dominant Themes: Identifies your most important astrological influences today
Aspect Analysis: Shows exact aspects affecting you (conjunctions, squares, trines, etc.)
Individual Timing: Considers your specific planetary patterns

Request Schema

json

{
  "birthDateTime": "1990-06-15T14:30:00",    // Required: ISO format birth date/time
  "birthLocation": {                         // Required: exact birth location
    "latitude": 40.7589,
    "longitude": -73.9851,
    "timezone": "America/New_York"
  },
  "date": "today"                           // Optional: "today", "tomorrow", "yesterday", or YYYY-MM-DD
}

Response Schema

json

{
  "success": true,
  "data": {
    "type": "personalized-daily",
    "targetDate": "2025-09-24",
    "birthProfile": {
      "birthDateTime": "1990-06-15T14:30:00.000Z",
      "location": {
        "latitude": 40.7589,
        "longitude": -73.9851,
        "timezone": "America/New_York"
      },
      "sunSign": "gemini",
      "ascendant": "libra"
    },
    "interpretation": {
      "type": "personalized",
      "content": {
        "overall": "Your Mercury-Mars conjunction activates today as transiting Jupiter forms a trine...",
        "personal_development": "This is a powerful day for self-expression and creative communication...",
        "relationships": "Venus transiting your 7th house brings harmony to partnerships...",
        "career_purpose": "Mars energizing your Midheaven suggests career momentum building...",
        "emotional_wisdom": "Moon's aspect to your natal Neptune heightens intuition...",
        "practical_advice": [
          "Schedule important conversations during Mercury hour (9-11 AM)",
          "Wear blue or green to enhance your Venus transit",
          "Focus on creative projects in the afternoon",
          "Avoid major decisions during Mercury retrograde shadow"
        ],
        "timing_guidance": "Best energy flow: 9 AM - 2 PM, Evening meditation: 8-9 PM",
        "affirmation": "I express my authentic self with confidence and creativity"
      },
      "aspectsUsed": 8,
      "dominantTheme": "communication",
      "energyType": "harmonious"
    },
    "transitAnalysis": {
      "significantAspects": [
        {
          "type": "trine",
          "natalPlanet": "sun",
          "transitPlanet": "jupiter",
          "exactness": 6.2,
          "orb": 1.8,
          "strength": 85,
          "influence": {
            "nature": "harmonious",
            "intensity": "high",
            "description": "jupiter trine natal sun"
          }
        }
        // ... more aspects
      ],
      "dominantThemes": {
        "primary": "communication",
        "secondary": "creativity",
        "tertiary": "relationships",
        "dominantScore": 78
      },
      "overallEnergy": {
        "type": "harmonious",
        "intensity": "medium",
        "description": "Flowing energies supporting growth and ease",
        "scores": {
          "challenging": 25,
          "harmonious": 65,
          "neutral": 10
        }
      },
      "totalAspects": 12
    },
    "metadata": {
      "calculatedAt": "2025-09-24T12:00:00.000Z",
      "processingTime": {
        "total": 650,
        "natalChart": 180,
        "transits": 95,
        "aspects": 220,
        "interpretation": 155
      },
      "dataQuality": {
        "natalPlanets": 10,
        "transitPlanets": 10,
        "aspectsAnalyzed": 12,
        "significantAspects": 8
      }
    }
  }
}

Code Examples

Personalized vs. General Horoscopes

Feature	General Horoscope	Personalized Horoscope
Based on	Sun sign only	Complete birth chart
Accuracy	Broad generalizations	Individual planetary positions
Aspects	Sign-level transits	Exact natal-transit aspects
Timing	General daily energy	Personal timing based on chart
Categories	Universal themes	Tailored to your chart emphasis
Advice	Generic guidance	Specific to your planetary patterns
Calculation time	~300ms	~650ms
Use case	Quick daily check	Deep personal insight

Advanced Natal Chart Endpoint

Enhanced natal chart calculations with support for multiple house systems including high-latitude fallback handling.

🏠 POST `/astrology/natal-chart`

New Features in Week 7:

✅ Placidus and Koch house systems (in addition to Whole Sign)
✅ Automatic high-latitude fallback for Arctic/Antarctic locations
✅ Enhanced caching with house system differentiation
✅ Detailed response metadata including fallback reasons

Request Schema

json

{
  "birthDateTime": "1990-07-15 14:30:00",
  "timezone": "America/New_York",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "options": {
    "house_system": "placidus",        // New: "whole" | "placidus" | "koch"
    "zodiac": "tropical"               // "tropical" only (sidereal not yet supported)
  }
}

Response Schema Enhancements

json

{
  "success": true,
  "requestId": "natal_1640995200_abc123",
  "data": {
    "chart_id": "chart_abc123def456",
    "birth_info": {
      "date_time": "1990-07-15T18:30:00.000Z",
      "timezone": "America/New_York",
      "location": {
        "latitude": 40.7128,
        "longitude": -74.0060
      }
    },
    "planets": {
      "sun": {
        "longitude": 22.45,
        "latitude": 0.0,
        "sign": "Cancer",
        "house": 10,
        "retrograde": false
      }
      // ... other planets
    },
    "houses": [
      {
        "house": 1,
        "cusp": 15.23,
        "sign": "Scorpio",
        "degree": 15,
        "minute": 14
      }
      // ... other houses (12 total)
    ],
    "aspects": [
      {
        "planet1": "sun",
        "planet2": "moon",
        "aspect": "trine",
        "orb": 4.2,
        "exact": false
      }
      // ... other aspects
    ],
    "metadata": {
      "house_system": "placidus",                    // New: Requested system
      "house_system_used": "equal",                  // New: Actual system used
      "fallback_reason": "High latitude (70.5°) detected, falling back to Equal houses", // New
      "high_latitude_detected": true,               // New
      "zodiac_mode": "tropical",
      "calculation_time_ms": 89,
      "cache_hit": false,
      "near_boundary": false,
      "calculated_at": "2025-01-20T12:00:00.000Z"
    }
  },
  "timestamp": "2025-01-20T12:00:00.000Z"
}

House Systems Comparison

System	Description	Best For	High-Latitude Behavior	Accuracy
Whole Sign	Traditional, sign-based cusps	Beginners, simplicity	Always works	Good
Placidus	Time-based, most popular	Detailed analysis	Auto-fallback >66°	Excellent
Koch	Birthplace-focused	Location emphasis	Auto-fallback >66°	Excellent
Equal (fallback)	30° house division	High latitudes	Always works	Good

High-Latitude Documentation

Automatic Fallback Behavior:

Latitudes above 66° (Arctic Circle) automatically fall back to Equal houses
Latitudes below -66° (Antarctic Circle) automatically fall back to Equal houses
Fallback reason provided in response metadata
Original request honored for latitudes within normal range

Affected Regions:

Arctic: Northern Canada, Alaska, Greenland, Northern Scandinavia, Siberia
Antarctic: Antarctic research stations

Example Response with Fallback:

json

{
  "metadata": {
    "house_system": "placidus",
    "house_system_used": "equal",
    "fallback_reason": "High latitude (69.6°) detected - Placidus calculations unreliable above 66°",
    "high_latitude_detected": true
  }
}

Transit Calculations

Understanding how planetary transits affect daily horoscopes.

How Transits Work

Planetary Positions:

Calculated using accurate astronomical ephemeris data
Positions given in ecliptic longitude (0-360°)
Mapped to zodiac signs (30° segments)
Retrograde motion detection for all planets

Aspect Calculations:

Conjunction (0°): Planets in same position - amplified energy
Square (90°): Challenging aspect - tension and growth
Trine (120°): Harmonious aspect - easy flow of energy
Opposition (180°): Balancing aspect - integration needed

Orb Tolerances:

Major aspects: ±8° orb
Minor aspects: ±3° orb
Strength rated as: strong (0-3°), moderate (3-6°), weak (6°+)

Transit Response Fields

json

{
  "transits": {
    "planetary_positions": {
      "planet_name": {
        "longitude": 45.67,              // Ecliptic longitude (0-360°)
        "latitude": 1.23,                // Ecliptic latitude
        "sign": "Taurus",                // Zodiac sign
        "degree_in_sign": 15.67,         // Degrees within sign (0-30°)
        "retrograde": false              // Retrograde motion flag
      }
    },
    "aspects": [
      {
        "planet": "mars",                // Transiting planet
        "aspect": "square",              // Aspect type
        "orb": 4.1,                     // Orb in degrees
        "strength": "moderate",          // "strong" | "moderate" | "weak"
        "nature": "challenging",         // "beneficial" | "challenging" | "neutral"
        "keywords": ["action", "tension"] // Interpretive keywords
      }
    ],
    "planets_in_sign": [
      {
        "planet": "venus",               // Planet in the queried sign
        "degree_in_sign": 12.3,          // Position within sign
        "retrograde": false,             // Retrograde status
        "keywords": ["love", "beauty"]   // Planet meanings
      }
    ],
    "overall_influence": {
      "score": 1.5,                     // Overall influence score (-10 to +10)
      "overall_tone": "positive"        // "very_positive" | "positive" | "neutral" | "challenging" | "very_challenging"
    }
  }
}

Rate Limits & Performance

Rate Limits

Endpoint	RPM	RPD	Notes
Daily Horoscope (Basic)	60	1000	More lenient than natal charts
Daily Horoscope (GET)	60	1000	Same as POST version
Personalized Daily	20	300	NEW: Most compute-intensive
Natal Chart	30	500	Compute-intensive operations
Health Checks	120	-	High frequency allowed

Rate Limit Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995260

Caching Behavior

Daily Horoscope Caching:

TTL: 24 hours for identical sign+date+style combinations
Cache Key: Generated from sign, date (YYYY-MM-DD), and style
Cache Warming: Popular signs (Aries, Leo, Scorpio) pre-cached
Performance: Cache hits return in ~50ms vs ~400ms uncached

Natal Chart Caching:

TTL: 7 days for identical birth data+house system combinations
Cache Key: Generated from birth datetime, location, and house system
Performance: Cache hits return in ~75ms vs ~250ms uncached

Performance Targets

Operation	Target	Typical	Cache Hit
Horoscope Generation	<400ms	~300ms	~50ms
House Calculation	<50ms	~25ms	N/A
Transit Calculation	<100ms	~75ms	N/A
AI Interpretation	<5000ms	~2500ms	~50ms

Error Codes & Handling

HTTP Status Codes

Code	Status	Description
200	Success	Request completed successfully
400	Bad Request	Invalid request parameters
422	Unprocessable Entity	Valid format, invalid data
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
503	Service Unavailable	Temporary unavailability

New Error Codes (Week 7)

json

{
  "error": {
    "code": "INVALID_ZODIAC_SIGN",
    "message": "Invalid zodiac sign 'invalid'. Must be one of: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces",
    "details": {
      "provided": "invalid",
      "valid_options": ["aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"]
    }
  }
}

json

{
  "error": {
    "code": "UNSUPPORTED_HOUSE_SYSTEM",
    "message": "House system 'campanus' not supported. Supported systems: whole, placidus, koch",
    "details": {
      "requested": "campanus",
      "supported": ["whole", "placidus", "koch"]
    }
  }
}

High-Latitude Fallback (200 Response)

json

{
  "success": true,
  "data": {
    // ... normal response
    "metadata": {
      "house_system": "placidus",
      "house_system_used": "equal",
      "fallback_reason": "High latitude (70.0°) detected, falling back to Equal houses",
      "high_latitude_detected": true
    }
  },
  "warnings": [
    {
      "code": "HIGH_LATITUDE_FALLBACK",
      "message": "Requested house system unavailable at this latitude",
      "severity": "info"
    }
  ]
}

Migration Guide

For Existing Users

Backward Compatibility:

✅ Default house_system remains "whole" - no breaking changes
✅ All existing API calls continue to work unchanged
✅ New response fields are additive and optional

Recommended Updates:

javascript

// Before (still works)
const chart = await calculateChart({
  birthDateTime: "1990-07-15 14:30:00",
  timezone: "America/New_York",
  latitude: 40.7128,
  longitude: -74.0060
});

// After (enhanced)
const chart = await calculateChart({
  birthDateTime: "1990-07-15 14:30:00",
  timezone: "America/New_York",
  latitude: 40.7128,
  longitude: -74.0060,
  options: {
    house_system: "placidus"  // New option
  }
});

// Check for fallbacks
if (chart.data.metadata.fallback_reason) {
  console.log('Fallback used:', chart.data.metadata.fallback_reason);
}

Testing High-Latitude Locations

Test Coordinates:

javascript

// Tromsø, Norway (should trigger fallback)
{ latitude: 69.6496, longitude: 18.9560 }

// Reykjavik, Iceland (should NOT trigger fallback)
{ latitude: 64.1466, longitude: -21.9426 }

// Extreme Arctic (should trigger fallback)
{ latitude: 85.0, longitude: 0.0 }

Best Practices

Client-Side Implementation

Caching Recommendations:

javascript

// Cache horoscopes client-side for 24 hours
const cacheKey = `horoscope-${sign}-${date}-${style}`;
const cached = localStorage.getItem(cacheKey);

if (cached) {
  const { data, timestamp } = JSON.parse(cached);
  if (Date.now() - timestamp < 24 * 60 * 60 * 1000) {
    return data; // Use cached version
  }
}

// Fetch new horoscope and cache
const horoscope = await fetchHoroscope(sign, date, style);
localStorage.setItem(cacheKey, JSON.stringify({
  data: horoscope,
  timestamp: Date.now()
}));

Mobile App Optimization:

javascript

// Use brief style for mobile apps
const horoscope = await fetch('/astrology/daily-horoscope', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sign: userSign,
    date: 'today',
    style: 'brief'  // Faster generation, smaller payload
  })
});

Location Awareness:

javascript

// Include user location for personalized transits
if ('geolocation' in navigator) {
  navigator.geolocation.getCurrentPosition(async (position) => {
    const horoscope = await fetchHoroscope({
      sign: 'virgo',
      location: {
        latitude: position.coords.latitude,
        longitude: position.coords.longitude
      },
      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
    });
  });
}

Error Handling Best Practices

javascript

async function fetchHoroscope(params) {
  try {
    const response = await fetch('/astrology/daily-horoscope', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(params)
    });

    if (!response.ok) {
      const error = await response.json();

      // Handle specific error types
      switch (error.error?.code) {
        case 'INVALID_ZODIAC_SIGN':
          return { error: 'Please select a valid zodiac sign' };
        case 'RATE_LIMIT_EXCEEDED':
          return { error: 'Please wait before requesting another horoscope' };
        default:
          return { error: 'Unable to generate horoscope at this time' };
      }
    }

    const data = await response.json();

    // Check for warnings (like high-latitude fallback)
    if (data.warnings?.length > 0) {
      console.log('Warnings:', data.warnings);
    }

    return data;

  } catch (error) {
    console.error('Network error:', error);
    return { error: 'Connection error. Please check your internet connection.' };
  }
}

Performance Optimization

Request Batching:

javascript

// Don't batch horoscope requests - they're cached efficiently
// Each request benefits from individual caching

// DO batch natal chart requests for families/couples
const charts = await Promise.all([
  calculateChart(person1Data),
  calculateChart(person2Data)
]);

Timezone Handling:

javascript

// Always provide timezone for accurate daily boundaries
const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

const horoscope = await fetchHoroscope({
  sign: 'libra',
  date: '2025-01-20',
  timezone: userTimezone  // Critical for accurate "today"
});

Try It Live

Test the API endpoints with sample requests:

Daily Horoscope Test

bash

curl -X POST https://api.mysticalapi.com/v1/astrology/daily-horoscope \
  -H "Content-Type: application/json" \
  -d '{
    "sign": "gemini",
    "style": "detailed"
  }'

Enhanced Natal Chart Test

bash

curl -X POST https://api.mysticalapi.com/v1/astrology/natal-chart \
  -H "Content-Type: application/json" \
  -d '{
    "birthDateTime": "1990-06-21 15:30:00",
    "timezone": "America/Chicago",
    "latitude": 41.8781,
    "longitude": -87.6298,
    "houseSystem": "koch"
  }'

High-Latitude Test

bash

curl -X POST https://api.mysticalapi.com/v1/astrology/natal-chart \
  -H "Content-Type: application/json" \
  -d '{
    "birthDateTime": "1985-12-25 12:00:00",
    "timezone": "Europe/Oslo",
    "latitude": 69.6496,
    "longitude": 18.9560,
    "houseSystem": "placidus"
  }'

Expected result: Automatic fallback to Equal houses with fallback_reason in metadata.

Last updated: Week 7 - September 2025API Version: v2.1Production URL: https://api.mysticalapi.com/v1

Working Examples

Real Production Test - Natal Chart

bash

# Working example from production deployment
curl -X POST https://api.mysticalapi.com/v1/astrology/natal-chart \
  -H "Content-Type: application/json" \
  -d '{
    "birthDateTime": "1990-01-15 12:00:00",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "timezone": "America/New_York",
    "houseSystem": "placidus"
  }'

Sample Response:

json

{
  "success": true,
  "requestId": "natal_1758738240677_4ap5xa6ge",
  "data": {
    "chart_id": "chr_1758738241839_b9dhqjro",
    "birth_info": {
      "date_time": "1990-01-15T17:00:00.000Z",
      "timezone": "America/New_York",
      "location": {
        "latitude": 40.7128,
        "longitude": -74.006
      }
    },
    "planets": {
      "sun": {
        "longitude": 295.15447572589574,
        "sign": "Capricorn",
        "degree": 25,
        "minute": 9,
        "house": 1,
        "retrograde": false,
        "dailyMotion": 1.0181949792121259
      },
      "moon": {
        "longitude": 169.67928997203123,
        "sign": "Virgo",
        "degree": 19,
        "minute": 40,
        "house": 1,
        "retrograde": false,
        "dailyMotion": 12.233656240389138
      }
    },
    "houses": [
      {
        "house": 1,
        "cusp": 0,
        "sign": "Aries",
        "degree": 0,
        "minute": 0
      }
    ],
    "aspects": [
      {
        "planet1": "sun",
        "planet2": "venus",
        "type": "conjunction",
        "symbol": "☌",
        "angle": 0,
        "orb": 5.272006269046699,
        "maxOrb": 8,
        "exact": false,
        "applying": true,
        "strength": 0.34099921636916264
      }
    ],
    "metadata": {
      "house_system": "whole",
      "house_system_used": "whole",
      "fallback_reason": null,
      "zodiac_mode": "tropical",
      "calculation_time_ms": 1156.87,
      "cache_hit": false,
      "calculated_at": "2025-09-24T18:16:03.695Z"
    }
  }
}

Real Production Test - Daily Horoscope

bash

# Working example from production deployment
curl -X POST https://api.mysticalapi.com/v1/astrology/daily-horoscope \
  -H "Content-Type: application/json" \
  -d '{"sign": "capricorn", "date": "today", "style": "brief"}'

Sample Response:

json

{
  "success": true,
  "requestId": "horoscope_1758738258677_3pbbv97hs",
  "data": {
    "horoscope_id": "hor_1758738258771_03cg70",
    "sign": "capricorn",
    "date": "2025-09-24",
    "style": "brief",
    "transits": {
      "planetary_positions": {
        "sun": {
          "longitude": 180.78546843274034,
          "sign": "Libra",
          "degree_in_sign": 0.7854684327403447,
          "retrograde": false
        },
        "saturn": {
          "longitude": 359.09723172574644,
          "sign": "Pisces",
          "degree_in_sign": 29.09723172574644,
          "retrograde": true
        }
      },
      "aspects": [
        {
          "planet": "saturn",
          "aspect": "square",
          "orb": 0.9027682742535603,
          "strength": "strong",
          "nature": "very_challenging",
          "is_exact": true,
          "planet_retrograde": true,
          "keywords": ["structure", "limitation", "discipline"]
        }
      ],
      "overall_influence": {
        "score": -5,
        "overall_tone": "challenging"
      }
    },
    "interpretation": {
      "summary": "Transit analysis for capricorn: Strong transiting aspects: 5, Total transiting influences: 8, Overall tone: challenging",
      "key_themes": ["structure", "discipline", "responsibility"],
      "energy_level": "very_low",
      "focus_areas": ["saturn", "neptune", "uranus"],
      "advice": "Practice patience and mindfulness today. Challenges may arise, but they offer opportunities for growth."
    },
    "metadata": {
      "calculation_time_ms": 94.17,
      "transit_count": 8,
      "overall_score": -5,
      "overall_tone": "challenging",
      "calculated_at": "2025-09-24T18:24:18.772Z"
    }
  }
}

Astrology API Reference ​

Base URL ​

Three-Tier Horoscope System ​

Endpoints Overview ​

Daily Horoscope Endpoint ​

📅 POST /astrology/daily-horoscope ​

Request Schema ​

Response Schema ​

Style Options & Enhancements ​

Category Predictions (Enhanced Feature) ​

Lucky Elements (Enhanced Feature) ​

Code Examples ​

Basic Horoscope Request ​

Enhanced Horoscope with Categories ​

Dated Horoscope with Location ​

GET Daily Horoscope Endpoint (Simplified) ​

🚀 GET /astrology/horoscope/daily/:sign ​

Request Parameters ​

Usage Examples ​

Response Structure ​

Mobile App Integration ​

Personalized Daily Horoscope Endpoint ​

🎯 POST /astrology/personalized-daily ​

Request Schema ​

Response Schema ​

Code Examples ​

Personalized vs. General Horoscopes ​

Advanced Natal Chart Endpoint ​

🏠 POST /astrology/natal-chart ​

Request Schema ​

Response Schema Enhancements ​

House Systems Comparison ​

High-Latitude Documentation ​

Transit Calculations ​

How Transits Work ​

Transit Response Fields ​

Rate Limits & Performance ​

Rate Limits ​

Caching Behavior ​

Performance Targets ​

Error Codes & Handling ​

HTTP Status Codes ​

New Error Codes (Week 7) ​

High-Latitude Fallback (200 Response) ​

Migration Guide ​

For Existing Users ​

Testing High-Latitude Locations ​

Best Practices ​

Client-Side Implementation ​

Error Handling Best Practices ​

Performance Optimization ​

Try It Live ​

Daily Horoscope Test ​

Enhanced Natal Chart Test ​

High-Latitude Test ​

Working Examples ​

Real Production Test - Natal Chart ​

Real Production Test - Daily Horoscope ​

Astrology API Reference

Base URL

Three-Tier Horoscope System

Endpoints Overview

Daily Horoscope Endpoint

📅 POST `/astrology/daily-horoscope`

Request Schema

Response Schema

Style Options & Enhancements

Category Predictions (Enhanced Feature)

Lucky Elements (Enhanced Feature)

Code Examples

Basic Horoscope Request

Enhanced Horoscope with Categories

Dated Horoscope with Location

GET Daily Horoscope Endpoint (Simplified)

🚀 GET `/astrology/horoscope/daily/:sign`

Request Parameters

Usage Examples

Response Structure

Mobile App Integration

Personalized Daily Horoscope Endpoint

🎯 POST `/astrology/personalized-daily`

Request Schema

Response Schema

Code Examples

Personalized vs. General Horoscopes

Advanced Natal Chart Endpoint

🏠 POST `/astrology/natal-chart`

Request Schema

Response Schema Enhancements

House Systems Comparison

High-Latitude Documentation

Transit Calculations

How Transits Work

Transit Response Fields

Rate Limits & Performance

Rate Limits

Caching Behavior

Performance Targets

Error Codes & Handling

HTTP Status Codes

New Error Codes (Week 7)

High-Latitude Fallback (200 Response)

Migration Guide

For Existing Users

Testing High-Latitude Locations

Best Practices

Client-Side Implementation

Error Handling Best Practices

Performance Optimization

Try It Live

Daily Horoscope Test

Enhanced Natal Chart Test

High-Latitude Test

Working Examples

Real Production Test - Natal Chart

Real Production Test - Daily Horoscope