# RoxyAPI - **OpenAPI Version:** `3.1.0` - **API Version:** `2.0.0` # Fast, reliable data APIs > **Base URL:** `https://roxyapi.com/api/v2`\ > **Important:** All endpoint paths listed below are relative to this base URL. Prepend the base URL to any endpoint path when generating code. RoxyAPI provides developer-focused data APIs with **transparent pricing** and **instant API key delivery**. No user accounts required - just checkout and start calling endpoints. ## Quick Start ### 1. Get Your API Key Visit [roxyapi.com/pricing](https://roxyapi.com/pricing) to: - Select a subscription plan (monthly or yearly) - Choose duration based on your needs - Complete checkout with your email - Receive your API key instantly Your API key remains valid for your subscription duration. You can view your API keys anytime in your dashboard after login, or request recovery via [roxyapi.com/contact](https://roxyapi.com/contact). ### 2. Make Your First Request All API endpoints require authentication via API key. Pass it in the header or query parameter: **Header (recommended):** ```bash curl -X GET "https://roxyapi.com/api/v2/usage" \ -H "X-API-Key: YOUR_API_KEY" ``` **Query parameter (for testing):** ```bash curl "https://roxyapi.com/api/v2/usage?api_key=YOUR_API_KEY" ``` ### 3. Monitor Usage Check your current usage and limits: ```bash GET /api/v2/usage ``` Response includes: - `usage` - Current request count this month - `limit` - Total monthly requests allowed - `remaining` - Remaining requests - `recommendation` - Suggested plan if nearing limit ### 4. Track Per-Request Usage Every API response includes standard rate limit headers: - `X-RateLimit-Limit` - Total monthly requests allowed - `X-RateLimit-Remaining` - Remaining requests this month - `X-RateLimit-Used` - Current request count this month ## Authentication All endpoints require an API key. Two methods: 1. **Header** (recommended): `X-API-Key: YOUR_API_KEY` 2. **Query param** (testing only): `?api_key=YOUR_API_KEY` ## Rate Limits - **Monthly limits** based on your plan (calendar month, UTC timezone) - Limits reset on the 1st of each month at 00:00 UTC - Monitor usage via response headers on every request - Check detailed usage breakdown at `/usage` endpoint ## Error Handling Standard HTTP status codes: - `200` - Success - `400` - Invalid request parameters - `401` - Missing or invalid API key, subscription inactive or expired - `429` - Rate limit exceeded (monthly quota reached) - `500` - Server error Error response format: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable error description" } } ``` Common error codes: - `API_KEY_REQUIRED` - No API key provided - `INVALID_API_KEY` - Invalid API key - `SUBSCRIPTION_NOT_FOUND` - API key references non-existent subscription - `SUBSCRIPTION_INACTIVE` - Subscription cancelled or expired - `RATE_LIMIT_EXCEEDED` - Monthly quota reached ## Pricing & Billing - **Subscription plans** - monthly or yearly with included API calls - **Flexible duration** - choose subscription length that fits your needs - **Transparent pricing** - see [roxyapi.com/pricing](https://roxyapi.com/pricing) - **Cancel anytime** - subscription remains active until end date - **Usage monitoring** - track via `/usage` endpoint and response headers ## Support - **FAQ**: [roxyapi.com/faq](https://roxyapi.com/faq) - **Contact**: [roxyapi.com/contact](https://roxyapi.com/contact) - **API Key Recovery**: Email us with your checkout email ## SDKs & Libraries Currently no official SDKs - use standard HTTP clients: - JavaScript: `fetch()`, `axios` - Python: `requests`, `httpx` - Ruby: `net/http`, `httparty` - PHP: `guzzle`, `curl` - Go: `net/http` ## Available APIs Explore available endpoints in the sections below. All APIs are documented with interactive examples. ## Servers - **URL:** `/api/v2` - **Description:** Production API v2 ## Operations ### Get all zodiac signs - Complete zodiac signs list with dates and elements - **Method:** `GET` - **Path:** `/astrology/signs` - **Tags:** Western Astrology Returns all 12 tropical zodiac signs (Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius, Capricorn, Aquarius, Pisces) with essential information: name, symbol, element (fire, earth, air, water), date ranges, and short descriptions. Perfect for zodiac sign lists, horoscope widgets, birth chart calculators, astrology apps, star sign selectors, and zodiac reference tools. Use GET /signs/{identifier} for complete zodiac sign profiles with personality traits, compatibility, and detailed characteristics. #### Responses ##### Status: 200 Successfully retrieved all 12 zodiac signs ###### Content-Type: application/json **Array of:** - **`dates` (required)** `object` — Tropical zodiac date range - **`end` (required)** `string` — End date (e.g., "Apr 19") - **`start` (required)** `string` — Start date (e.g., "Mar 21") - **`description` (required)** `string` — Brief 1-2 sentence overview - **`element` (required)** `string`, possible values: `"fire", "earth", "air", "water"` — Elemental classification - **`id` (required)** `string` — Lowercase sign identifier (e.g., "aries") - **`name` (required)** `string` — Display name (e.g., "Aries") - **`symbol`** `string` — Unicode zodiac symbol (e.g., "♈") **Example:** ```json [ { "id": "", "name": "", "symbol": "", "element": "fire", "dates": { "start": "", "end": "" }, "description": "" } ] ``` ### Get zodiac sign details - Complete astrology sign profile with personality traits - **Method:** `GET` - **Path:** `/astrology/signs/{identifier}` - **Tags:** Western Astrology Retrieve comprehensive zodiac sign information for any astrological sign using lowercase ID (e.g., "aries") or case-insensitive name (e.g., "Aries", "ARIES"). Returns complete astrology profile including: element (fire, earth, air, water), modality (cardinal, fixed, mutable), ruling planet, birth date ranges, personality traits (positive, negative, keywords), zodiac sign descriptions, famous people with this sign, key strengths and qualities, sign motto, greatest gifts, challenges, and secret weapon. Perfect for horoscope readings, zodiac compatibility checks, birth chart interpretations, astrology blogs, star sign personality analysis, and zodiac meaning databases. #### Responses ##### Status: 200 Successfully retrieved zodiac sign ###### Content-Type: application/json - **`dates` (required)** `object` — Tropical zodiac date range - **`end` (required)** `string` — End date (e.g., "Apr 19") - **`start` (required)** `string` — Start date (e.g., "Mar 21") - **`description` (required)** `object` - **`long` (required)** `string` — Detailed paragraph description - **`short` (required)** `string` — Brief 1-2 sentence overview - **`element` (required)** `string`, possible values: `"fire", "earth", "air", "water"` — Elemental classification - **`id` (required)** `string` — Lowercase sign identifier (e.g., "aries") - **`keywords` (required)** `array` — Key personality descriptive words (lowercase) **Items:** `string` - **`modality` (required)** `string`, possible values: `"cardinal", "fixed", "mutable"` — Quality/modality classification - **`name` (required)** `string` — Display name (e.g., "Aries") - **`rulingPlanet` (required)** `string` — Traditional ruling planet - **`symbolName` (required)** `string` — Symbol name/mascot (e.g., "The Ram", "The Bull") - **`challenges`** `string` — Greatest challenges/weaknesses - **`famous`** `array` — Famous people with this sign **Items:** `string` - **`gifts`** `string` — Greatest gifts/strengths - **`motto`** `string` — Sign motto/tagline - **`strengths`** `array` — Key strengths and lovable qualities **Items:** `string` - **`symbol`** `string` — Unicode zodiac symbol (e.g., "♈") - **`weapon`** `string` — Secret weapon/superpower **Example:** ```json { "id": "", "name": "", "symbol": "", "symbolName": "", "element": "fire", "modality": "cardinal", "rulingPlanet": "", "dates": { "start": "", "end": "" }, "keywords": [ "" ], "description": { "short": "", "long": "" }, "famous": [ "" ], "strengths": [ "" ], "motto": "", "gifts": "", "challenges": "", "weapon": "" } ``` ##### Status: 404 Zodiac sign not found ###### Content-Type: application/json - **`error` (required)** `string` **Example:** ```json { "error": "" } ``` ### Get all planet meanings - Complete astrology planet interpretations list - **Method:** `GET` - **Path:** `/astrology/planet-meanings` - **Tags:** Western Astrology Returns all 10 astrological planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto) with essential meanings: name, symbol, tagline, category (personal/social/generational), ruling sign, and short descriptions. Perfect for astrology reference apps, planet meaning widgets, birth chart interpretation tools, astrology learning platforms, planetary keywords reference, and zodiac planet guides. Use GET /planet-meanings/{identifier} for complete planet profiles with detailed interpretations, keywords, temperature, and dignities (rulership/detriment/exultation/fall). #### Responses ##### Status: 200 Successfully retrieved all 10 planet meanings ###### Content-Type: application/json **Array of:** - **`description` (required)** `string` — Brief 1-2 sentence overview - **`id` (required)** `string` — Lowercase planet identifier (e.g., "sun", "moon") - **`name` (required)** `string` — Display name (e.g., "Sun", "Moon") - **`rulership` (required)** `string` — Zodiac sign this planet rules - **`symbol` (required)** `string` — Unicode planet symbol (e.g., "☉", "☽") - **`tagline` (required)** `string` — Short tagline (e.g., "Self-awareness & ego") - **`category`** `string` — Planet classification (personal/social/generational). Sun/Moon lack this field. **Example:** ```json [ { "id": "", "name": "", "symbol": "", "tagline": "", "category": "", "rulership": "", "description": "" } ] ``` ### Get planet meaning details - Complete astrology planet interpretation - **Method:** `GET` - **Path:** `/astrology/planet-meanings/{identifier}` - **Tags:** Western Astrology Retrieve comprehensive planet interpretation for any astrological planet using lowercase ID (e.g., "sun", "moon") or case-insensitive name (e.g., "Sun", "MOON"). Returns complete astrology meaning including: symbol, tagline, category (personal/social/generational), temperature, orbital period, retrograde status, dignities (rulership/detriment/exultation/fall), positive and negative keywords, and short/long descriptions. Perfect for birth chart readings, planet meaning lookups, astrology education, natal chart interpretation, transit meanings, planetary symbolism reference, and keyword-based interpretations. #### Responses ##### Status: 200 Successfully retrieved planet meaning ###### Content-Type: application/json - **`description` (required)** `object` - **`long` (required)** `string` — Detailed paragraph description - **`short` (required)** `string` — Brief 1-2 sentence overview - **`detriment` (required)** `string` — Sign of detriment - **`exultation` (required)** `string` — Sign of exultation - **`fall` (required)** `string` — Sign of fall - **`id` (required)** `string` — Lowercase planet identifier (e.g., "sun") - **`keywords` (required)** `object` - **`negative` (required)** `array` — Negative keywords/traits **Items:** `string` - **`positive` (required)** `array` — Positive keywords/traits **Items:** `string` - **`name` (required)** `string` — Display name (e.g., "Sun") - **`orbit` (required)** `string` — Orbital period description - **`rulership` (required)** `string` — Zodiac sign this planet rules - **`symbol` (required)** `string` — Unicode planet symbol (e.g., "☉") - **`tagline` (required)** `string` — Short tagline (e.g., "Self-awareness & ego") - **`temperature` (required)** `string` — Planet temperature (Hot/Cold/Neutral) - **`category`** `string` — Planet classification (personal/social/generational). Sun/Moon lack this field. - **`retrograde`** `boolean` — Whether planet can go retrograde (only set for Sun/Moon as false) **Example:** ```json { "id": "", "name": "", "symbol": "", "tagline": "", "category": "", "temperature": "", "orbit": "", "retrograde": true, "rulership": "", "detriment": "", "exultation": "", "fall": "", "keywords": { "positive": [ "" ], "negative": [ "" ] }, "description": { "short": "", "long": "" } } ``` ##### Status: 404 Planet not found ###### Content-Type: application/json - **`error` (required)** `string` **Example:** ```json { "error": "" } ``` ### Generate natal chart - Birth chart calculator API with houses and aspects - **Method:** `POST` - **Path:** `/astrology/natal-chart` - **Tags:** Western Astrology Calculate complete Western astrology natal chart (birth chart) with tropical zodiac. Returns all 10 planetary positions (Sun through Pluto), 12 house cusps with customizable house systems (Placidus, Whole Sign, Equal, Koch), major and minor aspects, Ascendant, Midheaven, dominant elements and modalities. Perfect for astrology apps, birth chart generators, horoscope websites, and astrological consultation tools. Accurate ephemeris data from NASA JPL. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. This is the exact calendar date when the person was born, used to calculate planetary positions for that specific day. Format must be YYYY-MM-DD (e.g., 1990-07-15 for July 15, 1990). - **`latitude` (required)** `number` — Birth location latitude in decimal degrees (-90 to 90). Positive values are North, negative are South. This affects house cusps and local horizon calculations. Example: 40.7128 for New York City. Use geocoding APIs or location services to convert addresses to coordinates. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees (-180 to 180). Positive values are East, negative are West. This affects house cusps and local time. Example: -74.006 for New York City. Use geocoding APIs to convert addresses to coordinates. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. This precise time determines the Ascendant (rising sign) and house cusps. Even small time differences (minutes) can change house placements. Use 12:00:00 if birth time is unknown (solar chart). Format: HH:MM:SS (e.g., 14:30:00 for 2:30 PM). - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for Western Hemisphere (west of UTC), positive for Eastern Hemisphere (east of UTC). Examples: New York EST = -5, Los Angeles PST = -8, London GMT = 0, Paris CET = 1, India IST = 5.5 (NOT 5:30), Tokyo JST = 9. IMPORTANT: Use decimal format for half-hour zones (India = 5.5, not 5:30). This converts LOCAL birth time to UTC for astronomical calculations (e.g., 14:30 with timezone 5.5 → 09:00 UTC). Calculations are timezone-independent - server timezone does NOT affect results. - **`houseSystem`** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"`, default: `"placidus"` — House system for dividing the chart into 12 houses. Placidus (default) is most popular in Western astrology and time-sensitive. Whole Sign assigns one sign per house (simpler, ancient). Equal houses divide chart into 30° segments from Ascendant. Koch emphasizes houses in high latitudes. Choose based on astrological tradition or user preference. **Example:** ```json { "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5, "houseSystem": "placidus" } ``` #### Responses ##### Status: 200 Successful natal chart calculation with complete astrological data ###### Content-Type: application/json - **`ascendant` (required)** `object` - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`aspects` (required)** `array` **Items:** - **`angle` (required)** `number` - **`interpretation` (required)** `string` - **`isApplying` (required)** `boolean` - **`orb` (required)** `number` - **`planet1` (required)** `string` - **`planet2` (required)** `string` - **`strength` (required)** `number` - **`type` (required)** `string` - **`aspectsInterpretation` (required)** `object` - **`challenging` (required)** `number` - **`dominant` (required)** `string` - **`harmonious` (required)** `number` - **`neutral` (required)** `number` - **`summary` (required)** `string` - **`birthDetails` (required)** `object` - **`date` (required)** `string` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` - **`houses` (required)** `array` **Items:** - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`number` (required)** `number` - **`sign` (required)** `string` - **`houseSystem` (required)** `string` - **`midheaven` (required)** `object` - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`planets` (required)** `array` **Items:** - **`degree` (required)** `number` - **`house` (required)** `number` - **`isRetrograde` (required)** `boolean` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`name` (required)** `string` - **`sign` (required)** `string` - **`speed` (required)** `number` - **`interpretation`** `object` - **`detailed` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`summary` (required)** `string` - **`summary` (required)** `object` - **`dominantElement` (required)** `string` - **`dominantModality` (required)** `string` - **`elementDistribution` (required)** `object` - **`modalityDistribution` (required)** `object` - **`retrogradePlanets` (required)** `array` **Items:** `string` **Example:** ```json { "birthDetails": { "date": "", "time": "", "latitude": 1, "longitude": 1, "timezone": 1 }, "planets": [ { "name": "Sun", "longitude": 112.45, "latitude": 0.01, "sign": "Cancer", "degree": 22.45, "house": 7, "speed": 0.9571, "isRetrograde": false, "interpretation": { "summary": "Your Sun in Cancer in The Seventh House reveals how you express self-awareness & ego with ambitious and independent energy in the realm of partnerships", "detailed": "Sun represents self-awareness & ego. In Cancer, this energy becomes ambitious, independent, impatient...", "keywords": [ "Leader", "Bright", "Fire", "ambitious", "independent" ] } } ], "houses": [ { "number": 1, "longitude": 45.32, "sign": "Taurus", "degree": 15.32 } ], "houseSystem": "placidus", "aspects": [ { "planet1": "Sun", "planet2": "Moon", "type": "TRINE", "angle": 120, "orb": 2.5, "isApplying": true, "strength": 75, "interpretation": "harmonious" } ], "aspectsInterpretation": { "summary": "Your chart contains 15 aspects: 8 harmonious, 5 challenging, and 2 neutral. This creates a harmonious overall pattern.", "dominant": "harmonious", "harmonious": 8, "challenging": 5, "neutral": 2 }, "ascendant": { "sign": "Taurus", "degree": 15.32, "longitude": 45.32 }, "midheaven": { "sign": "Aquarius", "degree": 8.76, "longitude": 308.76 }, "summary": { "dominantElement": "Water", "dominantModality": "Cardinal", "retrogradePlanets": [ "Mercury", "Saturn" ], "elementDistribution": { "Fire": 2, "Earth": 3, "Air": 1, "Water": 4 }, "modalityDistribution": { "Cardinal": 4, "Fixed": 3, "Mutable": 3 } } } ``` ### Get planetary positions - Ephemeris calculator for all planets - **Method:** `POST` - **Path:** `/astrology/planets` - **Tags:** Western Astrology Calculate accurate tropical zodiac positions for all 10 planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto) for any date, time, and location. Returns longitude, latitude, zodiac sign, degree within sign, daily motion speed, and retrograde status. Perfect for transit tracking, ephemeris tables, astrology apps, and planetary position widgets. NASA JPL ephemeris accuracy. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Target date for planetary positions in YYYY-MM-DD format. Use current date for transit positions, or any historical/future date for research. Planets move daily, so this date determines their zodiac positions. - **`latitude` (required)** `number` — Observer latitude in decimal degrees (-90 to 90). While planetary longitudes are geocentric (same worldwide), this is needed for house calculations if extending functionality. For basic ephemeris, use 0 as default. - **`longitude` (required)** `number` — Observer longitude in decimal degrees (-180 to 180). Used for precise local time conversion. For basic planetary positions, this has minimal impact but ensures accuracy. - **`time` (required)** `string` — Time in 24-hour HH:MM:SS format for precise calculations. Moon moves \~13° per day, so time matters for accurate lunar position. Use 12:00:00 (noon) as default if exact time not needed. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east of UTC. Examples: New York EST = -5, India IST = 5.5 (NOT 5:30), Tokyo JST = 9, Nepal NPT = 5.75. IMPORTANT: Use decimal format (5.5, not 5:30). **Example:** ```json { "date": "2025-12-18", "time": "12:00:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5 } ``` #### Responses ##### Status: 200 Planetary positions calculated successfully ###### Content-Type: application/json - **`planets` (required)** `array` **Items:** - **`degree` (required)** `number` - **`isRetrograde` (required)** `boolean` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`name` (required)** `string` - **`sign` (required)** `string` - **`speed` (required)** `number` - **`description`** `string` - **`interpretation`** `object` - **`keywords` (required)** `array` **Items:** `string` - **`planetMeaning` (required)** `string` - **`signExpression` (required)** `string` - **`summary` (required)** `string` - **`keywords`** `array` **Items:** `string` - **`symbol`** `string` - **`tagline`** `string` **Example:** ```json { "planets": [ { "name": "", "longitude": 1, "latitude": 1, "sign": "", "degree": 1, "speed": 1, "isRetrograde": true, "symbol": "", "tagline": "", "description": "", "keywords": [ "" ], "interpretation": { "summary": "", "planetMeaning": "", "signExpression": "", "keywords": [ "" ] } } ] } ``` ### Get current moon phase - Lunar phase calculator with zodiac sign - **Method:** `GET` - **Path:** `/astrology/moon-phase/current` - **Tags:** Western Astrology Get current moon phase with illumination percentage, lunar age (days since new moon), zodiac sign, and distance from Earth. Returns phase name (New Moon, Waxing Crescent Moon, First Quarter Moon, Waxing Gibbous Moon, Full Moon, Waning Gibbous Moon, Last Quarter Moon, Waning Crescent Moon) plus exact lunar position. Perfect for moon tracking apps, lunar calendars, astrology widgets, and gardening by moon phase tools. #### Responses ##### Status: 200 Moon phase calculated successfully ###### Content-Type: application/json - **`age` (required)** `number` - **`date` (required)** `string` - **`degree` (required)** `number` - **`distance` (required)** `number` - **`illumination` (required)** `number` - **`phase` (required)** `string` - **`sign` (required)** `string` - **`meaning`** `object` — Moon phase meaning and interpretation from astrological tradition - **`description` (required)** `string` - **`energy` (required)** `string`, possible values: `"waxing", "waning", "new", "full"` - **`illumination` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`name` (required)** `string` - **`symbol` (required)** `string` **Example:** ```json { "date": "", "phase": "Waxing Gibbous Moon", "illumination": 78.5, "age": 10.25, "sign": "Pisces", "degree": 15.42, "distance": 384400, "meaning": { "name": "Waxing Gibbous Moon", "symbol": "🌔", "description": "The waxing gibbous moon is there when we are close to our goals...", "keywords": [ "assess", "refine", "perfect" ], "energy": "waxing", "illumination": "50-100% (Nearly Full)" } } ``` ### Get upcoming moon phases - Next new moon, full moon, quarters - **Method:** `GET` - **Path:** `/astrology/moon-phase/upcoming` - **Tags:** Western Astrology Get upcoming moon phase transitions (New Moon, First Quarter, Full Moon, Last Quarter) for the next weeks/months. Returns dates and phase names for each lunar quarter. Perfect for lunar event calendars, moon phase widgets, and astrology planning tools. #### Responses ##### Status: 200 Upcoming moon phases retrieved successfully ###### Content-Type: application/json - **`phases` (required)** `array` **Items:** - **`date` (required)** `string` - **`phase` (required)** `string` **Example:** ```json { "phases": [ { "date": "", "phase": "" } ] } ``` ### Get lunar calendar - Moon phases for entire month - **Method:** `GET` - **Path:** `/astrology/moon-phase/calendar/:year/:month` - **Tags:** Western Astrology Get complete lunar calendar showing moon phase and illumination for every day of a specific month. Perfect for creating moon phase calendars, lunar planners, and astrology event schedules. #### Responses ##### Status: 200 Lunar calendar generated successfully ###### Content-Type: application/json - **`calendar` (required)** `array` **Items:** - **`date` (required)** `string` - **`illumination` (required)** `number` - **`phase` (required)** `string` - **`month` (required)** `number` - **`year` (required)** `number` **Example:** ```json { "year": 1, "month": 1, "calendar": [ { "date": "", "phase": "", "illumination": 1 } ] } ``` ### Calculate synastry - Relationship compatibility analysis API - **Method:** `POST` - **Path:** `/astrology/synastry` - **Tags:** Western Astrology Calculate complete synastry (relationship compatibility) between two natal charts using Western tropical astrology. Analyzes inter-chart aspects between all planets to determine romantic, friendship, and karmic compatibility. Returns compatibility score (0-100), detailed inter-aspects with strength ratings, harmonious vs challenging aspect counts, and relationship dynamics analysis. Perfect for dating apps, matrimonial sites, relationship counseling tools, and astrology compatibility features. Based on professional astrological techniques. #### Request Body ##### Content-Type: application/json - **`person1` (required)** `object` - **`date` (required)** `string`, format: `date` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` - **`name`** `string` - **`person2` (required)** `object` - **`date` (required)** `string`, format: `date` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` - **`name`** `string` - **`houseSystem`** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"`, default: `"placidus"` **Example:** ```json { "person1": { "name": "Alex", "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5 }, "person2": { "name": "Alex", "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5 }, "houseSystem": "placidus" } ``` #### Responses ##### Status: 200 Synastry calculated successfully with compatibility analysis ###### Content-Type: application/json - **`analysis` (required)** `object` - **`challenges` (required)** `array` **Items:** `string` - **`overall` (required)** `string` - **`strengths` (required)** `array` **Items:** `string` - **`compatibilityScore` (required)** `number` — Overall compatibility score (0-100) - **`interAspects` (required)** `array` **Items:** - **`angle` (required)** `number` - **`interpretation` (required)** `string` - **`orb` (required)** `number` - **`planet1` (required)** `string` - **`planet2` (required)** `string` - **`strength` (required)** `number` - **`type` (required)** `string` - **`meaning`** `object` - **`description` (required)** `object` - **`long` (required)** `string` - **`short` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`name` (required)** `string` - **`nature` (required)** `string` - **`relationshipContext` (required)** `string` - **`person1` (required)** `object` - **`ascendant` (required)** `object` - **`degree` (required)** `number` - **`sign` (required)** `string` - **`moonSign` (required)** `string` - **`sunSign` (required)** `string` - **`name`** `string` - **`person2` (required)** `object` - **`ascendant` (required)** `object` - **`degree` (required)** `number` - **`sign` (required)** `string` - **`moonSign` (required)** `string` - **`sunSign` (required)** `string` - **`name`** `string` - **`summary` (required)** `object` - **`byType` (required)** `object` - **`challenging` (required)** `number` - **`harmonious` (required)** `number` - **`neutral` (required)** `number` - **`total` (required)** `number` **Example:** ```json { "person1": { "name": "", "ascendant": { "sign": "", "degree": 1 }, "sunSign": "", "moonSign": "" }, "person2": { "name": "", "ascendant": { "sign": "", "degree": 1 }, "sunSign": "", "moonSign": "" }, "compatibilityScore": 78, "interAspects": [ { "planet1": "", "planet2": "", "type": "", "angle": 1, "orb": 1, "strength": 1, "interpretation": "", "meaning": { "name": "", "description": { "short": "", "long": "" }, "keywords": [ "" ], "nature": "", "relationshipContext": "" } } ], "summary": { "total": 24, "harmonious": 12, "challenging": 8, "neutral": 4, "byType": { "TRINE": 5, "SEXTILE": 7, "SQUARE": 6, "OPPOSITION": 2 } }, "analysis": { "overall": "", "strengths": [ "" ], "challenges": [ "" ] } } ``` ### Calculate house cusps - House system calculator with comparison - **Method:** `POST` - **Path:** `/astrology/houses` - **Tags:** Western Astrology Calculate astrological house cusps using Placidus, Whole Sign, Equal, or Koch house systems. Returns all 12 house cusps with zodiac signs, degrees, Ascendant, and Midheaven. Use "all" parameter to compare all 4 house systems side-by-side. Perfect for astrology charts, house cusp tables, and educational tools showing house system differences. Includes accurate Ascendant and MC calculations. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string` — Birth date in YYYY-MM-DD format. Date is critical for house cusp calculations as it determines planetary positions used in some house systems. - **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines the local horizon and meridian, which are fundamental to house division. Higher latitudes cause more distortion in time-based systems like Placidus. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time and horizon calculations for house cusps. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is ESSENTIAL for accurate house cusps - even minutes matter. The Ascendant (1st house cusp) changes roughly every 4 minutes. Without accurate time, house placements will be incorrect. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: New York EST = -5, India IST = 5.5 (NOT 5:30), Tokyo JST = 9. IMPORTANT: Use decimal format (5.5, not 5:30). - **`houseSystem`** `object`, default: `"placidus"` — House system for dividing ecliptic into 12 houses. Placidus (most popular) uses time, Whole Sign (ancient) uses signs, Equal divides from Ascendant. Use "all" to compare all 4 systems side-by-side for educational purposes. **Example:** ```json { "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5, "houseSystem": "placidus" } ``` #### Responses ##### Status: 200 House cusps calculated successfully ###### Content-Type: application/json - **`data` (required)** `object` - **`ascendant` (required)** `object` - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`date` (required)** `string` - **`houses` (required)** `array` **Items:** - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`number` (required)** `number` - **`sign` (required)** `string` - **`houseSystem` (required)** `string` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`midheaven` (required)** `object` - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`time` (required)** `string` - **`timezone` (required)** `number` - **`comparison`** `object` — House cusp comparison across all systems (only when houseSystem="all") - **`success` (required)** `boolean`, possible values: `true` **Example:** ```json { "success": true, "data": { "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5, "houseSystem": "placidus", "ascendant": { "sign": "Taurus", "degree": 15.32, "longitude": 45.32 }, "midheaven": { "sign": "Aquarius", "degree": 8.76, "longitude": 308.76 }, "houses": [ { "number": 1, "longitude": 45.32, "sign": "Taurus", "degree": 15.32 } ], "comparison": { "propertyName*": { "houses": [ { "number": 1, "longitude": 1, "sign": "", "degree": 1 } ] } } } } ``` ### Calculate planetary aspects - Aspect finder for any date and time - **Method:** `POST` - **Path:** `/astrology/aspects` - **Tags:** Western Astrology Calculate all major and minor aspects between planets for any date and time. Finds conjunctions (0°), oppositions (180°), trines (120°), squares (90°), sextiles (60°), and minor aspects. Returns aspect type, exact angle, orb, applying/separating status, and strength (0-100). Filter by specific planets or aspect types. Perfect for aspect tables, transit analysis, and aspect pattern detection. Uses standard Western astrology orbs. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Date in YYYY-MM-DD format - **`time` (required)** `string` — Time in HH:MM:SS format (24-hour) - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Examples: New York EST = -5, India IST = 5.5 (NOT 5:30), Tokyo JST = 9. IMPORTANT: Use decimal format (5.5, not 5:30). - **`aspectTypes`** `array` — Optional: specific aspect types to find (defaults to all 9) **Items:** `string` - **`planets`** `array` — Optional: specific planets to calculate aspects for (defaults to all 10) **Items:** `string` **Example:** ```json { "date": "1990-07-15", "time": "14:30:00", "timezone": -5, "planets": [ "Sun", "Moon", "Mercury", "Venus", "Mars" ], "aspectTypes": [ "CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE" ] } ``` #### Responses ##### Status: 200 Aspects calculated successfully ###### Content-Type: application/json - **`aspects` (required)** `array` **Items:** - **`angle` (required)** `number` - **`interpretation` (required)** `string` - **`isApplying` (required)** `boolean` - **`orb` (required)** `number` - **`planet1` (required)** `string` - **`planet2` (required)** `string` - **`strength` (required)** `number` - **`type` (required)** `string` - **`meaning`** `object` - **`description` (required)** `object` - **`long` (required)** `string` - **`short` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`name` (required)** `string` - **`nature` (required)** `string` - **`aspectsFound` (required)** `number` - **`date` (required)** `string` - **`summary` (required)** `object` - **`byType` (required)** `object` - **`challenging` (required)** `number` - **`harmonious` (required)** `number` - **`neutral` (required)** `number` - **`totalAspects` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` **Example:** ```json { "date": "1990-07-15", "time": "14:30:00", "timezone": -5, "aspectsFound": 12, "aspects": [ { "planet1": "Sun", "planet2": "Moon", "type": "TRINE", "angle": 120, "orb": 2.5, "isApplying": true, "strength": 75, "interpretation": "harmonious", "meaning": { "name": "", "description": { "short": "", "long": "" }, "keywords": [ "" ], "nature": "" } } ], "summary": { "totalAspects": 12, "harmonious": 7, "challenging": 4, "neutral": 1, "byType": { "CONJUNCTION": 2, "TRINE": 3, "SQUARE": 2, "SEXTILE": 2, "OPPOSITION": 1 } } } ``` ### Calculate planetary transits - Current transits with natal chart comparison - **Method:** `POST` - **Path:** `/astrology/transits` - **Tags:** Western Astrology Calculate current or future planetary transits (positions of all planets now). Optionally compare transits to natal chart to find transit-to-natal aspects. Returns all 10 planet positions with signs, degrees, and speeds. When natal chart provided, includes transit aspects (transiting Sun conjunct natal Mars, etc.) with orbs and applying/separating status. Perfect for daily transit forecasts, aspect alerts, and personalized transit reports. #### Request Body ##### Content-Type: application/json - **`date`** `string`, format: `date` — Transit date in YYYY-MM-DD format (defaults to current date) - **`natalChart`** `object` — Optional natal chart data to compare transits against - **`date` (required)** `string`, format: `date` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` - **`time`** `string` — Transit time in HH:MM:SS format (defaults to current time) - **`timezone`** `number`, default: `0` — Timezone offset from UTC in hours (defaults to 0 = UTC) **Example:** ```json { "date": "2025-12-19", "time": "12:00:00", "timezone": 0, "natalChart": { "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5 } } ``` #### Responses ##### Status: 200 Transits calculated successfully ###### Content-Type: application/json - **`timezone` (required)** `number` - **`transitDate` (required)** `string` - **`transitPlanets` (required)** `array` **Items:** - **`degree` (required)** `number` - **`isRetrograde` (required)** `boolean` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`name` (required)** `string` - **`sign` (required)** `string` - **`speed` (required)** `number` - **`transitTime` (required)** `string` - **`summary`** `object` — Transit aspect summary (only when natalChart provided) - **`challenging` (required)** `number` - **`harmonious` (required)** `number` - **`neutral` (required)** `number` - **`totalAspects` (required)** `number` - **`transitAspects`** `array` — Transit-to-natal aspects (only when natalChart provided) **Items:** - **`angle` (required)** `number` - **`interpretation` (required)** `string` - **`isApplying` (required)** `boolean` - **`natalPlanet` (required)** `string` - **`orb` (required)** `number` - **`strength` (required)** `number` - **`transitPlanet` (required)** `string` - **`type` (required)** `string` **Example:** ```json { "transitDate": "2025-12-19", "transitTime": "12:00:00", "timezone": 0, "transitPlanets": [ { "name": "Sun", "longitude": 267.45, "latitude": 0.01, "sign": "Sagittarius", "degree": 27.45, "speed": 0.9571, "isRetrograde": false } ], "transitAspects": [ { "transitPlanet": "Sun", "natalPlanet": "Mars", "type": "CONJUNCTION", "angle": 0, "orb": 1.2, "isApplying": true, "strength": 88, "interpretation": "challenging" } ], "summary": { "totalAspects": 8, "harmonious": 4, "challenging": 3, "neutral": 1 } } ``` ### Calculate transit aspects to natal chart - **Method:** `POST` - **Path:** `/astrology/transit-aspects` - **Tags:** Western Astrology Calculates current transiting planet aspects to natal chart planets. More detailed analysis than /transits endpoint. #### Request Body ##### Content-Type: application/json - **`natalChart` (required)** `object` — Natal chart birth details - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours - **`aspectTypes`** `array` — Filter specific aspect types **Items:** `string`, possible values: `"CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE", "SEXTILE", "SEMI_SEXTILE", "QUINCUNX", "SEMI_SQUARE", "SESQUIQUADRATE"` - **`minStrength`** `number` — Minimum aspect strength (0-100) - **`planets`** `array` — Filter specific transiting planets **Items:** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`transitDate`** `string` — Transit date (YYYY-MM-DD), defaults to current date - **`transitTime`** `string` — Transit time (HH:MM:SS), defaults to 12:00:00 **Example:** ```json { "natalChart": { "date": "", "time": "", "latitude": -90, "longitude": -180, "timezone": 1 }, "transitDate": "", "transitTime": "", "planets": [ "Sun" ], "aspectTypes": [ "CONJUNCTION" ], "minStrength": 0 } ``` #### Responses ##### Status: 200 Transit aspects calculated successfully ###### Content-Type: application/json - **`aspects` (required)** `array` — Transit-to-natal aspects with interpretations **Items:** - **`angle` (required)** `number` — Exact aspect angle - **`interpretation` (required)** `string`, possible values: `"harmonious", "challenging", "neutral"` - **`isApplying` (required)** `boolean` — True if planets moving toward exact - **`orb` (required)** `number` — Difference from exact aspect - **`planet1` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`planet2` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`strength` (required)** `number` — Aspect strength (0-100) - **`type` (required)** `string`, possible values: `"CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE", "SEXTILE", "SEMI_SEXTILE", "QUINCUNX", "SEMI_SQUARE", "SESQUIQUADRATE"` - **`transitInterpretation`** `object` - **`guidance` (required)** `string` - **`impact` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`summary` (required)** `string` - **`timing` (required)** `string` - **`natalPlanets` (required)** `array` — Natal planet positions **Items:** - **`degree` (required)** `number` — Degree within sign - **`house` (required)** `integer` — House number - **`isRetrograde` (required)** `boolean` — True if planet is retrograde - **`latitude` (required)** `number` — Ecliptic latitude - **`longitude` (required)** `number` — Tropical zodiac longitude - **`name` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`speed` (required)** `number` — Daily motion in degrees - **`summary` (required)** `object` — Statistical summary - **`byType` (required)** `object` — Count by aspect type - **`challenging` (required)** `number` — Challenging aspects (square, opposition, etc) - **`harmonious` (required)** `number` — Harmonious aspects (trine, sextile) - **`neutral` (required)** `number` — Neutral aspects (conjunction, minor) - **`strongest` (required)** `object` — Strongest aspect by orb tightness - **`angle` (required)** `number` — Exact aspect angle - **`interpretation` (required)** `string`, possible values: `"harmonious", "challenging", "neutral"` - **`isApplying` (required)** `boolean` — True if planets moving toward exact - **`orb` (required)** `number` — Difference from exact aspect - **`planet1` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`planet2` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`strength` (required)** `number` — Aspect strength (0-100) - **`type` (required)** `string`, possible values: `"CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE", "SEXTILE", "SEMI_SEXTILE", "QUINCUNX", "SEMI_SQUARE", "SESQUIQUADRATE"` - **`total` (required)** `number` — Total aspects found - **`transitDate` (required)** `string` — Date/time of transits - **`transitPlanets` (required)** `array` — Current transiting planet positions **Items:** - **`degree` (required)** `number` — Degree within sign - **`house` (required)** `integer` — House number - **`isRetrograde` (required)** `boolean` — True if planet is retrograde - **`latitude` (required)** `number` — Ecliptic latitude - **`longitude` (required)** `number` — Tropical zodiac longitude - **`name` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`speed` (required)** `number` — Daily motion in degrees **Example:** ```json { "transitDate": "", "transitPlanets": [ { "name": "Sun", "longitude": 0, "latitude": 1, "sign": "aries", "degree": 0, "house": 1, "speed": 1, "isRetrograde": true } ], "natalPlanets": [ { "name": "Sun", "longitude": 0, "latitude": 1, "sign": "aries", "degree": 0, "house": 1, "speed": 1, "isRetrograde": true } ], "aspects": [ { "planet1": "Sun", "planet2": "Sun", "type": "CONJUNCTION", "angle": 1, "orb": 1, "isApplying": true, "strength": 0, "interpretation": "harmonious", "transitInterpretation": { "summary": "", "timing": "", "impact": "", "guidance": "", "keywords": [ "" ] } } ], "summary": { "total": 1, "harmonious": 1, "challenging": 1, "neutral": 1, "strongest": { "planet1": "Sun", "planet2": "Sun", "type": "CONJUNCTION", "angle": 1, "orb": 1, "isApplying": true, "strength": 0, "interpretation": "harmonious" }, "byType": { "propertyName*": 1 } } } ``` ##### Status: 400 Invalid request body ### Calculate solar return chart - **Method:** `POST` - **Path:** `/astrology/solar-return` - **Tags:** Western Astrology Generates an annual solar return chart cast for the moment the Sun returns to its natal position. Used for yearly forecasting. #### Request Body ##### Content-Type: application/json - **`birthDate` (required)** `string` — Original birth date (YYYY-MM-DD) - **`birthTime` (required)** `string` — Original birth time (HH:MM:SS) - **`latitude` (required)** `number` — Latitude for solar return location (current residence) - **`longitude` (required)** `number` — Longitude for solar return location (current residence) - **`returnYear` (required)** `integer` — Year for solar return chart - **`timezone` (required)** `number` — Timezone offset in hours - **`houseSystem`** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"`, default: `"placidus"` — House system to use **Example:** ```json { "birthDate": "", "birthTime": "", "returnYear": 1, "latitude": 1, "longitude": 1, "timezone": 1, "houseSystem": "placidus" } ``` #### Responses ##### Status: 200 Solar return chart calculated successfully ###### Content-Type: application/json - **`birthDate` (required)** `string` — Original birth date - **`chart` (required)** `object` — Solar return chart - **`aspects` (required)** `array` **Items:** - **`angle` (required)** `number` — Exact aspect angle - **`interpretation` (required)** `string`, possible values: `"harmonious", "challenging", "neutral"` - **`isApplying` (required)** `boolean` — True if planets moving toward exact - **`orb` (required)** `number` — Difference from exact aspect - **`planet1` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`planet2` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`strength` (required)** `number` — Aspect strength (0-100) - **`type` (required)** `string`, possible values: `"CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE", "SEXTILE", "SEMI_SEXTILE", "QUINCUNX", "SEMI_SQUARE", "SESQUIQUADRATE"` - **`birthDetails` (required)** `object` - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours - **`houses` (required)** `array` **Items:** - **`degree` (required)** `number` — Degree within sign - **`longitude` (required)** `number` — Cusp longitude - **`number` (required)** `integer` — House number - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`houseSystem` (required)** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"` - **`planets` (required)** `array` **Items:** - **`degree` (required)** `number` — Degree within sign - **`house` (required)** `integer` — House number - **`isRetrograde` (required)** `boolean` — True if planet is retrograde - **`latitude` (required)** `number` — Ecliptic latitude - **`longitude` (required)** `number` — Tropical zodiac longitude - **`name` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`speed` (required)** `number` — Daily motion in degrees - **`interpretation` (required)** `object` — Solar return interpretation - **`keyThemes` (required)** `array` — Key themes to focus on this year **Items:** `string` - **`purpose` (required)** `string` — Purpose and use of solar return charts - **`summary` (required)** `string` — Solar return summary - **`location` (required)** `object` — Solar return location - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`timezone` (required)** `number` - **`natalSunPosition` (required)** `object` — Original natal Sun position - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`solarReturnDate` (required)** `string` — Exact solar return date/time - **`solarReturnYear` (required)** `number` — Solar return year **Example:** ```json { "birthDate": "", "solarReturnDate": "", "solarReturnYear": 1, "location": { "latitude": 1, "longitude": 1, "timezone": 1 }, "chart": { "birthDetails": { "date": "", "time": "", "latitude": -90, "longitude": -180, "timezone": 1 }, "planets": [ { "name": "Sun", "longitude": 0, "latitude": 1, "sign": "aries", "degree": 0, "house": 1, "speed": 1, "isRetrograde": true } ], "houses": [ { "number": 1, "longitude": 0, "sign": "aries", "degree": 0 } ], "houseSystem": "placidus", "aspects": [ { "planet1": "Sun", "planet2": "Sun", "type": "CONJUNCTION", "angle": 1, "orb": 1, "isApplying": true, "strength": 0, "interpretation": "harmonious" } ] }, "natalSunPosition": { "longitude": 1, "sign": "", "degree": 1 }, "interpretation": { "summary": "", "purpose": "", "keyThemes": [ "" ] } } ``` ##### Status: 400 Invalid request body ### Calculate lunar return chart - **Method:** `POST` - **Path:** `/astrology/lunar-return` - **Tags:** Western Astrology Generates a monthly lunar return chart cast for the moment the Moon returns to its natal position. Used for monthly forecasting. #### Request Body ##### Content-Type: application/json - **`birthDate` (required)** `string` — Original birth date (YYYY-MM-DD) - **`birthTime` (required)** `string` — Original birth time (HH:MM:SS) - **`latitude` (required)** `number` — Latitude for lunar return location - **`longitude` (required)** `number` — Longitude for lunar return location - **`returnDate` (required)** `string` — Approximate return date (YYYY-MM-DD) - **`timezone` (required)** `number` — Timezone offset in hours - **`houseSystem`** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"`, default: `"placidus"` — House system to use **Example:** ```json { "birthDate": "", "birthTime": "", "returnDate": "", "latitude": 1, "longitude": 1, "timezone": 1, "houseSystem": "placidus" } ``` #### Responses ##### Status: 200 Lunar return chart calculated successfully ###### Content-Type: application/json - **`birthDate` (required)** `string` — Original birth date - **`chart` (required)** `object` — Lunar return chart - **`aspects` (required)** `array` **Items:** - **`angle` (required)** `number` — Exact aspect angle - **`interpretation` (required)** `string`, possible values: `"harmonious", "challenging", "neutral"` - **`isApplying` (required)** `boolean` — True if planets moving toward exact - **`orb` (required)** `number` — Difference from exact aspect - **`planet1` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`planet2` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`strength` (required)** `number` — Aspect strength (0-100) - **`type` (required)** `string`, possible values: `"CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE", "SEXTILE", "SEMI_SEXTILE", "QUINCUNX", "SEMI_SQUARE", "SESQUIQUADRATE"` - **`birthDetails` (required)** `object` - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours - **`houses` (required)** `array` **Items:** - **`degree` (required)** `number` — Degree within sign - **`longitude` (required)** `number` — Cusp longitude - **`number` (required)** `integer` — House number - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`houseSystem` (required)** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"` - **`planets` (required)** `array` **Items:** - **`degree` (required)** `number` — Degree within sign - **`house` (required)** `integer` — House number - **`isRetrograde` (required)** `boolean` — True if planet is retrograde - **`latitude` (required)** `number` — Ecliptic latitude - **`longitude` (required)** `number` — Tropical zodiac longitude - **`name` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`speed` (required)** `number` — Daily motion in degrees - **`interpretation` (required)** `object` — Lunar return interpretation - **`keyThemes` (required)** `array` — Key themes to focus on this month **Items:** `string` - **`purpose` (required)** `string` — Purpose and use of lunar return charts - **`summary` (required)** `string` — Lunar return summary - **`location` (required)** `object` — Lunar return location - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`timezone` (required)** `number` - **`lunarReturnDate` (required)** `string` — Exact lunar return date/time - **`natalMoonPosition` (required)** `object` — Original natal Moon position - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` **Example:** ```json { "birthDate": "", "lunarReturnDate": "", "location": { "latitude": 1, "longitude": 1, "timezone": 1 }, "chart": { "birthDetails": { "date": "", "time": "", "latitude": -90, "longitude": -180, "timezone": 1 }, "planets": [ { "name": "Sun", "longitude": 0, "latitude": 1, "sign": "aries", "degree": 0, "house": 1, "speed": 1, "isRetrograde": true } ], "houses": [ { "number": 1, "longitude": 0, "sign": "aries", "degree": 0 } ], "houseSystem": "placidus", "aspects": [ { "planet1": "Sun", "planet2": "Sun", "type": "CONJUNCTION", "angle": 1, "orb": 1, "isApplying": true, "strength": 0, "interpretation": "harmonious" } ] }, "natalMoonPosition": { "longitude": 1, "sign": "", "degree": 1 }, "interpretation": { "summary": "", "purpose": "", "keyThemes": [ "" ] } } ``` ##### Status: 400 Invalid request body ### Calculate composite chart for relationship - **Method:** `POST` - **Path:** `/astrology/composite-chart` - **Tags:** Western Astrology Generates a composite chart by calculating midpoints between two natal charts. Used for relationship astrology. #### Request Body ##### Content-Type: application/json - **`person1` (required)** `object` — First person birth details - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours - **`person2` (required)** `object` — Second person birth details - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours - **`houseSystem`** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"`, default: `"placidus"` — House system to use **Example:** ```json { "person1": { "date": "", "time": "", "latitude": -90, "longitude": -180, "timezone": 1 }, "person2": { "date": "", "time": "", "latitude": -90, "longitude": -180, "timezone": 1 }, "houseSystem": "placidus" } ``` #### Responses ##### Status: 200 Composite chart calculated successfully ###### Content-Type: application/json - **`aspects` (required)** `array` — Aspects in composite chart **Items:** - **`angle` (required)** `number` — Exact aspect angle - **`interpretation` (required)** `string`, possible values: `"harmonious", "challenging", "neutral"` - **`isApplying` (required)** `boolean` — True if planets moving toward exact - **`orb` (required)** `number` — Difference from exact aspect - **`planet1` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`planet2` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`strength` (required)** `number` — Aspect strength (0-100) - **`type` (required)** `string`, possible values: `"CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE", "SEXTILE", "SEMI_SEXTILE", "QUINCUNX", "SEMI_SQUARE", "SESQUIQUADRATE"` - **`compositeAscendant` (required)** `object` — Composite Ascendant - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`compositeHouses` (required)** `array` — Midpoint houses **Items:** - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`number` (required)** `number` - **`sign` (required)** `string` - **`compositeMidheaven` (required)** `object` — Composite Midheaven - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`compositePlanets` (required)** `array` — Midpoint planets with composite interpretations **Items:** - **`degree` (required)** `number` — Degree within sign - **`house` (required)** `integer` — House number - **`isRetrograde` (required)** `boolean` — True if planet is retrograde - **`latitude` (required)** `number` — Ecliptic latitude - **`longitude` (required)** `number` — Tropical zodiac longitude - **`name` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`speed` (required)** `number` — Daily motion in degrees - **`compositeInterpretation`** `object` - **`keywords` (required)** `array` **Items:** `string` - **`relationshipMeaning` (required)** `string` - **`summary` (required)** `string` - **`interpretation` (required)** `object` — Relationship interpretation - **`challenges` (required)** `array` **Items:** `string` - **`strengths` (required)** `array` **Items:** `string` - **`summary` (required)** `string` - **`person1` (required)** `object` — First person details - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours - **`person2` (required)** `object` — Second person details - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours **Example:** ```json { "person1": { "date": "", "time": "", "latitude": -90, "longitude": -180, "timezone": 1 }, "person2": { "date": "", "time": "", "latitude": -90, "longitude": -180, "timezone": 1 }, "compositePlanets": [ { "name": "Sun", "longitude": 0, "latitude": 1, "sign": "aries", "degree": 0, "house": 1, "speed": 1, "isRetrograde": true, "compositeInterpretation": { "summary": "", "relationshipMeaning": "", "keywords": [ "" ] } } ], "compositeHouses": [ { "number": 1, "sign": "", "degree": 1, "longitude": 1 } ], "compositeAscendant": { "sign": "", "degree": 1, "longitude": 1 }, "compositeMidheaven": { "sign": "", "degree": 1, "longitude": 1 }, "aspects": [ { "planet1": "Sun", "planet2": "Sun", "type": "CONJUNCTION", "angle": 1, "orb": 1, "isApplying": true, "strength": 0, "interpretation": "harmonious" } ], "interpretation": { "summary": "", "strengths": [ "" ], "challenges": [ "" ] } } ``` ##### Status: 400 Invalid request body ### Calculate relationship compatibility score - **Method:** `POST` - **Path:** `/astrology/compatibility-score` - **Tags:** Western Astrology Generates a comprehensive compatibility analysis between two birth charts with scores and detailed breakdown. #### Request Body ##### Content-Type: application/json - **`person1` (required)** `object` — First person birth details - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours - **`person2` (required)** `object` — Second person birth details - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours **Example:** ```json { "person1": { "date": "", "time": "", "latitude": 1, "longitude": 1, "timezone": 1 }, "person2": { "date": "", "time": "", "latitude": 1, "longitude": 1, "timezone": 1 } } ``` #### Responses ##### Status: 200 Compatibility score calculated successfully ###### Content-Type: application/json - **`aspectBreakdown` (required)** `object` — Synastry aspect breakdown - **`challenging` (required)** `number` — Challenging aspects - **`harmonious` (required)** `number` — Harmonious aspects - **`neutral` (required)** `number` — Neutral aspects - **`total` (required)** `number` — Total aspects found - **`categories` (required)** `object` — Compatibility by category - **`emotional` (required)** `number` — Emotional compatibility - **`intellectual` (required)** `number` — Intellectual compatibility - **`physical` (required)** `number` — Physical compatibility - **`romantic` (required)** `number` — Romantic compatibility - **`spiritual` (required)** `number` — Spiritual compatibility - **`challenges` (required)** `array` — Relationship challenges **Items:** `string` - **`interpretation` (required)** `string` — Detailed compatibility interpretation - **`overallScore` (required)** `number` — Overall compatibility score (0-100) - **`strengths` (required)** `array` — Relationship strengths **Items:** `string` - **`summary` (required)** `string` — Overall relationship summary **Example:** ```json { "overallScore": 0, "categories": { "romantic": 0, "emotional": 0, "intellectual": 0, "physical": 0, "spiritual": 0 }, "strengths": [ "" ], "challenges": [ "" ], "summary": "", "interpretation": "", "aspectBreakdown": { "total": 1, "harmonious": 1, "challenging": 1, "neutral": 1 } } ``` ##### Status: 400 Invalid request body ### Get daily horoscope for zodiac sign - **Method:** `GET` - **Path:** `/astrology/horoscope/:sign/daily` - **Tags:** Western Astrology Returns today's horoscope forecast for the specified zodiac sign based on current planetary transits. #### Responses ##### Status: 200 Daily horoscope retrieved successfully ###### Content-Type: application/json - **`advice` (required)** `string` — Daily advice - **`career` (required)** `string` — Career and work - **`compatibleSigns` (required)** `array` — Most compatible signs today **Items:** `string` - **`date` (required)** `string` — Date (YYYY-MM-DD) - **`finance` (required)** `string` — Financial outlook - **`health` (required)** `string` — Health and wellness - **`love` (required)** `string` — Love and relationships - **`luckyColor` (required)** `string` — Lucky color for the day - **`luckyNumber` (required)** `number` — Lucky number for the day - **`overview` (required)** `string` — Daily overview - **`sign` (required)** `string` — Zodiac sign **Example:** ```json { "sign": "", "date": "", "overview": "", "love": "", "career": "", "health": "", "finance": "", "advice": "", "luckyNumber": 1, "luckyColor": "", "compatibleSigns": [ "" ] } ``` ##### Status: 400 Invalid zodiac sign ### Get daily horoscopes for all zodiac signs - **Method:** `GET` - **Path:** `/astrology/horoscope/daily` - **Tags:** Western Astrology Returns today's horoscope forecasts for all 12 zodiac signs based on current planetary transits. More efficient than making 12 separate requests. #### Responses ##### Status: 200 Daily horoscopes retrieved successfully ###### Content-Type: application/json - **`date` (required)** `string` — Date (YYYY-MM-DD) - **`horoscopes` (required)** `array` — Horoscopes for all 12 signs **Items:** - **`advice` (required)** `string` — Daily advice - **`career` (required)** `string` — Career and work - **`compatibleSigns` (required)** `array` — Most compatible signs today **Items:** `string` - **`date` (required)** `string` — Date (YYYY-MM-DD) - **`finance` (required)** `string` — Financial outlook - **`health` (required)** `string` — Health and wellness - **`love` (required)** `string` — Love and relationships - **`luckyColor` (required)** `string` — Lucky color for the day - **`luckyNumber` (required)** `number` — Lucky number for the day - **`overview` (required)** `string` — Daily overview - **`sign` (required)** `string` — Zodiac sign **Example:** ```json { "date": "", "horoscopes": [ { "sign": "", "date": "", "overview": "", "love": "", "career": "", "health": "", "finance": "", "advice": "", "luckyNumber": 1, "luckyColor": "", "compatibleSigns": [ "" ] } ] } ``` ### Get weekly horoscope for zodiac sign - **Method:** `GET` - **Path:** `/astrology/horoscope/:sign/weekly` - **Tags:** Western Astrology Returns a 7-day horoscope forecast for the specified zodiac sign based on current planetary transits. Uses the industry-standard planet-in-sign methodology to generate personalized forecasts for love, career, health, and finances. #### Responses ##### Status: 200 Weekly horoscope retrieved successfully ###### Content-Type: application/json - **`advice` (required)** `string` — Weekly advice - **`career` (required)** `string` — Career and work - **`compatibleSigns` (required)** `array` — Most compatible signs this week **Items:** `string` - **`finance` (required)** `string` — Financial outlook - **`health` (required)** `string` — Health and wellness - **`love` (required)** `string` — Love and relationships - **`luckyDays` (required)** `array` — Lucky days of the week **Items:** `string` - **`luckyNumbers` (required)** `array` — Lucky numbers for the week **Items:** `number` - **`overview` (required)** `string` — Weekly overview - **`sign` (required)** `string` — Zodiac sign - **`week` (required)** `string` — Week of (start date) **Example:** ```json { "sign": "", "week": "", "overview": "", "love": "", "career": "", "health": "", "finance": "", "advice": "", "luckyDays": [ "" ], "luckyNumbers": [ 1 ], "compatibleSigns": [ "" ] } ``` ##### Status: 400 Invalid zodiac sign ### Get monthly horoscope for zodiac sign - **Method:** `GET` - **Path:** `/astrology/horoscope/:sign/monthly` - **Tags:** Western Astrology Returns a 30-day horoscope forecast for the specified zodiac sign based on current planetary transits. Uses the industry-standard planet-in-sign methodology to generate comprehensive monthly forecasts across all life areas. #### Responses ##### Status: 200 Monthly horoscope retrieved successfully ###### Content-Type: application/json - **`career` (required)** `string` — Career and work - **`compatibleSigns` (required)** `array` — Most compatible signs this month **Items:** `string` - **`finance` (required)** `string` — Financial outlook - **`health` (required)** `string` — Health and wellness - **`keyDates` (required)** `array` — Important dates this month **Items:** - **`date` (required)** `string` — Date (YYYY-MM-DD) - **`event` (required)** `string` — Astrological event or theme - **`love` (required)** `string` — Love and relationships - **`luckyColor` (required)** `string` — Lucky color for the month - **`luckyNumbers` (required)** `array` — Lucky numbers for the month **Items:** `number` - **`month` (required)** `string` — Month (YYYY-MM) - **`overview` (required)** `string` — Monthly overview - **`sign` (required)** `string` — Zodiac sign - **`weekByWeek` (required)** `array` — Week-by-week breakdown **Items:** - **`advice` (required)** `string` — Week-specific advice - **`focus` (required)** `string` — Main focus for the week - **`week` (required)** `number` — Week number (1-4) **Example:** ```json { "sign": "", "month": "", "overview": "", "love": "", "career": "", "health": "", "finance": "", "weekByWeek": [ { "week": 1, "focus": "", "advice": "" } ], "keyDates": [ { "date": "", "event": "" } ], "luckyNumbers": [ 1 ], "luckyColor": "", "compatibleSigns": [ "" ] } ``` ##### Status: 400 Invalid zodiac sign ### Calculate planetary return chart - **Method:** `POST` - **Path:** `/astrology/planetary-returns` - **Tags:** Western Astrology Generates a return chart for any planet when it returns to its natal position. Useful for Mercury, Venus, Mars, Jupiter, and Saturn returns. #### Request Body ##### Content-Type: application/json - **`approximateDate` (required)** `string` — Approximate date for return (YYYY-MM-DD) - **`birthDate` (required)** `string` — Original birth date (YYYY-MM-DD) - **`birthTime` (required)** `string` — Original birth time (HH:MM:SS) - **`latitude` (required)** `number` — Latitude for return location - **`longitude` (required)** `number` — Longitude for return location - **`planet` (required)** `string`, possible values: `"Mercury", "Venus", "Mars", "Jupiter", "Saturn"` — Planet for return calculation - **`timezone` (required)** `number` — Timezone offset in hours - **`houseSystem`** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"`, default: `"placidus"` — House system to use **Example:** ```json { "birthDate": "", "birthTime": "", "planet": "Mercury", "approximateDate": "", "latitude": 1, "longitude": 1, "timezone": 1, "houseSystem": "placidus" } ``` #### Responses ##### Status: 200 Planetary return chart calculated successfully ###### Content-Type: application/json - **`approximateCycle` (required)** `string` — Approximate cycle length for this planet - **`birthDate` (required)** `string` — Original birth date - **`chart` (required)** `object` — Planetary return chart - **`aspects` (required)** `array` **Items:** - **`angle` (required)** `number` — Exact aspect angle - **`interpretation` (required)** `string`, possible values: `"harmonious", "challenging", "neutral"` - **`isApplying` (required)** `boolean` — True if planets moving toward exact - **`orb` (required)** `number` — Difference from exact aspect - **`planet1` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`planet2` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`strength` (required)** `number` — Aspect strength (0-100) - **`type` (required)** `string`, possible values: `"CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE", "SEXTILE", "SEMI_SEXTILE", "QUINCUNX", "SEMI_SQUARE", "SESQUIQUADRATE"` - **`birthDetails` (required)** `object` - **`date` (required)** `string` — Birth date (YYYY-MM-DD) - **`latitude` (required)** `number` — Birth latitude - **`longitude` (required)** `number` — Birth longitude - **`time` (required)** `string` — Birth time (HH:MM:SS) - **`timezone` (required)** `number` — Timezone offset in hours - **`houses` (required)** `array` **Items:** - **`degree` (required)** `number` — Degree within sign - **`longitude` (required)** `number` — Cusp longitude - **`number` (required)** `integer` — House number - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`houseSystem` (required)** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"` - **`planets` (required)** `array` **Items:** - **`degree` (required)** `number` — Degree within sign - **`house` (required)** `integer` — House number - **`isRetrograde` (required)** `boolean` — True if planet is retrograde - **`latitude` (required)** `number` — Ecliptic latitude - **`longitude` (required)** `number` — Tropical zodiac longitude - **`name` (required)** `string`, possible values: `"Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"` - **`sign` (required)** `string`, possible values: `"aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"` - **`speed` (required)** `number` — Daily motion in degrees - **`interpretation` (required)** `object` — Basic interpretation - **`keyThemes` (required)** `array` — Key themes for this return period **Items:** `string` - **`summary` (required)** `string` — Return chart summary - **`location` (required)** `object` — Return location - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`timezone` (required)** `number` - **`natalPlanetPosition` (required)** `object` — Original natal planet position - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`planet` (required)** `string` — Planet name - **`returnDate` (required)** `string` — Exact planetary return date/time **Example:** ```json { "birthDate": "", "planet": "", "returnDate": "", "approximateCycle": "", "location": { "latitude": 1, "longitude": 1, "timezone": 1 }, "chart": { "birthDetails": { "date": "", "time": "", "latitude": -90, "longitude": -180, "timezone": 1 }, "planets": [ { "name": "Sun", "longitude": 0, "latitude": 1, "sign": "aries", "degree": 0, "house": 1, "speed": 1, "isRetrograde": true } ], "houses": [ { "number": 1, "longitude": 0, "sign": "aries", "degree": 0 } ], "houseSystem": "placidus", "aspects": [ { "planet1": "Sun", "planet2": "Sun", "type": "CONJUNCTION", "angle": 1, "orb": 1, "isApplying": true, "strength": 0, "interpretation": "harmonious" } ] }, "natalPlanetPosition": { "longitude": 1, "sign": "", "degree": 1 }, "interpretation": { "summary": "", "keyThemes": [ "" ] } } ``` ##### Status: 400 Invalid request body ### Get birth chart (D1 Rashi chart) - Kundli Calculator API - **Method:** `POST` - **Path:** `/vedic-astrology/birth-chart` - **Tags:** Vedic Astrology Calculate complete Vedic birth chart (Janam Kundli, natal chart) with all 9 planetary positions (Sun through Ketu) plus Ascendant (Lagna). Kundli calculator API for astrology apps, matrimonial sites. Returns accurate graha positions grouped by zodiac signs (rashis) with nakshatra details and pada. Perfect for kundli generation, horoscope matching, and Vedic astrology software integration. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). - **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` #### Responses ##### Status: 200 Successful birth chart calculation ###### Content-Type: application/json - **`aries` (required)** `object` - **`rashi` (required)** `string` - **`signs` (required)** `array` **Items:** - **`graha` (required)** `string` - **`isRetrograde` (required)** `boolean` - **`longitude` (required)** `number` - **`nakshatra` (required)** `object` - **`key` (required)** `number` - **`name` (required)** `string` - **`pada` (required)** `number` - **`meta` (required)** `object` **Example:** ```json { "aries": { "rashi": "aries", "signs": [] }, "meta": { "Sun": { "graha": "Sun", "rashi": "Leo", "longitude": 132.45, "nakshatra": { "name": "Magha", "pada": 2, "key": 9 }, "isRetrograde": false }, "Moon": { "graha": "Moon", "rashi": "Cancer", "longitude": 98.32, "nakshatra": { "name": "Punarvasu", "pada": 4, "key": 6 }, "isRetrograde": false } } } ``` ### Get Navamsa chart (D9) - Marriage Compatibility Calculator - **Method:** `POST` - **Path:** `/vedic-astrology/navamsa` - **Tags:** Vedic Astrology Calculate Navamsa (D9 divisional chart) for marriage compatibility analysis, spouse prediction, and spiritual life assessment. Navamsa calculator API reveals planetary strength in married life. Each planet's position is divided into 9 parts for accurate marriage astrology. Detects Vargottama planets (exalted status). Essential for matrimonial matching, relationship prediction, and marital harmony analysis in Vedic astrology. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). - **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` #### Responses ##### Status: 200 Successful Navamsa chart calculation ###### Content-Type: application/json - **`vargottama` (required)** `array` — Planets that are Vargottama (same sign in D1 and D9) **Items:** `string` - **`vargottamaExplanation` (required)** `string` — Explanation of Vargottama significance - **`chart`** `object` — Navamsa chart with same structure as birth chart **Example:** ```json { "chart": null, "vargottama": [ "Sun", "Moon" ], "vargottamaExplanation": "Vargottama planets occupy the same zodiac sign in both D1 (birth chart) and D9 (Navamsa chart), indicating exceptional strength and purity. These planets deliver their full results with minimal affliction, bringing stability and success in their significations. Vargottama is considered highly auspicious, especially for benefics like Jupiter and Venus, as it doubles the positive effects in marriage, spirituality, and overall life prosperity." } ``` ### Calculate compatibility score - Gun Milan API (Ashtakoot Matching) - **Method:** `POST` - **Path:** `/vedic-astrology/compatibility` - **Tags:** Vedic Astrology Calculate detailed Ashtakoot compatibility (Gun Milan) for kundli matching between two people. Marriage compatibility API for matrimonial sites and astrology apps. Returns accurate 36-point Guna Milan scale with breakdown: Nakshatra, Gana, Yoni, Rashi Lord, Vasya, Tara, Nadi, Bhakoot. Perfect for kundli matching for marriage, horoscope compatibility check, and Vedic matchmaking services. #### Request Body ##### Content-Type: application/json - **`person1` (required)** `object` — First person birth data - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). - **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. - **`person2` (required)** `object` — Second person birth data - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). - **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. **Example:** ```json { "person1": { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 }, "person2": { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } } ``` #### Responses ##### Status: 200 Successful compatibility calculation ###### Content-Type: application/json - **`breakdown` (required)** `array` — Detailed breakdown of compatibility scores across 8 categories: Nakshatra (4), Gana (6), Yoni (4), Rashi Lord (5), Vasya (2), Tara (3), Nadi (8), Bhakoot (7) **Items:** - **`category` (required)** `string` - **`description` (required)** `string` - **`score` (required)** `number` - **`isCompatible` (required)** `boolean` — Compatible if >= 50% - **`maxScore` (required)** `number` — Maximum possible score - **`percentage` (required)** `number` — Compatibility percentage - **`total` (required)** `number` — Total compatibility score **Example:** ```json { "total": 24.5, "maxScore": 36, "percentage": 68.1, "isCompatible": true, "breakdown": [ { "category": "Nakshatra", "score": 4, "description": "Excellent nakshatra match" }, { "category": "Gana", "score": 6, "description": "Perfect temperament match" }, { "category": "Yoni", "score": 2, "description": "Moderate nature compatibility" } ] } ``` ### Get planetary positions - Graha Positions API - **Method:** `POST` - **Path:** `/vedic-astrology/planetary-positions` - **Tags:** Vedic Astrology Get simplified planetary positions (graha positions) for all 9 planets (Sun through Ketu) plus Ascendant (Lagna). Real-time planet transit calculator for Vedic astrology. Navagraha positions API with nakshatra, pada, and rashi details. Faster response for basic planetary data without full chart structure. Perfect for planetary alignment tracking, daily transit updates, and astrology widgets. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). - **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` #### Responses ##### Status: 200 Successful planetary positions calculation ###### Content-Type: application/json **Example:** ```json { "Sun": { "graha": "Sun", "rashi": "Leo", "longitude": 132.45, "nakshatra": { "name": "Magha", "pada": 2, "key": 9, "deity": "Pitris (Ancestors)", "symbol": "Royal Throne", "characteristics": "Leadership, ancestral pride, regal nature" }, "rashiDetails": { "vedicName": "Simha", "symbol": "Lion", "energy": "Masculine, Fire", "characteristics": "Natural leadership, confidence, creativity" }, "isRetrograde": false }, "Moon": { "graha": "Moon", "rashi": "Cancer", "longitude": 98.32, "nakshatra": { "name": "Punarvasu", "pada": 4, "key": 6, "deity": "Aditi", "symbol": "Bow and Quiver", "characteristics": "Renewal, optimism, spiritual growth" }, "rashiDetails": { "vedicName": "Karka", "symbol": "Crab", "energy": "Feminine, Water", "characteristics": "Nurturing, emotional depth, protective" }, "isRetrograde": false } } ``` ### Get current Mahadasha, Antardasha, Pratyantardasha - Dasha Calculator API - **Method:** `POST` - **Path:** `/vedic-astrology/dasha/current` - **Tags:** Vedic Astrology Calculate current Vimshottari Dasha periods (Mahadasha, Antardasha, Pratyantardasha) with remaining time. Accurate dasha calculator API for life phase prediction and planetary period analysis. Returns dasha timeline with start/end dates for each period. Essential for understanding current planetary influences, dasha transitions, and timing events in Vedic astrology. 120-year dasha system based on moon nakshatra at birth. #### Request Body ##### Content-Type: application/json - **`day` (required)** `integer` - **`hour` (required)** `number` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`month` (required)** `integer` - **`year` (required)** `integer` **Example:** ```json { "year": 1990, "month": 7, "day": 4, "hour": 10.2, "latitude": 28.6139, "longitude": 77.209 } ``` #### Responses ##### Status: 200 Current running dasha periods ###### Content-Type: application/json - **`antardasha` (required)** `object` — Antardasha (sub-period) within Mahadasha - **`durationYears` (required)** `number` - **`endDate` (required)** `string`, format: `date-time` - **`mahadashaLord` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`planet` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`startDate` (required)** `string`, format: `date-time` - **`interpretation`** `string` - **`mahadasha` (required)** `object` — Mahadasha period for a planet with interpretation - **`durationYears` (required)** `number` - **`endDate` (required)** `string`, format: `date-time` - **`planet` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`startDate` (required)** `string`, format: `date-time` - **`interpretation`** `string` - **`moonNakshatra` (required)** `integer` - **`nakshatraLord` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`nakshatraName` (required)** `string` - **`pratyantardasha` (required)** `object` — Pratyantardasha (sub-sub-period) - **`antardashaLord` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`durationYears` (required)** `number` - **`endDate` (required)** `string`, format: `date-time` - **`mahadashaLord` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`planet` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`startDate` (required)** `string`, format: `date-time` - **`interpretation`** `string` - **`remainingInAntardasha` (required)** `object` - **`days` (required)** `number` - **`months` (required)** `number` - **`totalDays` (required)** `number` - **`years` (required)** `number` - **`remainingInMahadasha` (required)** `object` - **`days` (required)** `number` - **`months` (required)** `number` - **`totalDays` (required)** `number` - **`years` (required)** `number` - **`remainingInPratyantardasha` (required)** `object` - **`days` (required)** `number` - **`months` (required)** `number` - **`totalDays` (required)** `number` - **`years` (required)** `number` **Example:** ```json { "moonNakshatra": 15, "nakshatraName": "Swati", "nakshatraLord": "Rahu", "mahadasha": { "planet": "Ketu", "startDate": "1990-07-04T10:12:00.000Z", "endDate": "1996-07-04T10:12:00.000Z", "durationYears": 6, "interpretation": "Sun Mahadasha brings leadership opportunities, authority, and self-expression." }, "antardasha": { "planet": "Ketu", "startDate": "1990-07-04T10:12:00.000Z", "endDate": "1996-07-04T10:12:00.000Z", "durationYears": 6, "interpretation": "Sun Mahadasha brings leadership opportunities, authority, and self-expression.", "mahadashaLord": "Ketu" }, "pratyantardasha": { "planet": "Ketu", "startDate": "1990-07-04T10:12:00.000Z", "endDate": "1996-07-04T10:12:00.000Z", "durationYears": 6, "interpretation": "Sun Mahadasha brings leadership opportunities, authority, and self-expression.", "mahadashaLord": "Ketu", "antardashaLord": "Ketu" }, "remainingInMahadasha": { "years": 2, "months": 4, "days": 15, "totalDays": 865 }, "remainingInAntardasha": { "years": 2, "months": 4, "days": 15, "totalDays": 865 }, "remainingInPratyantardasha": { "years": 2, "months": 4, "days": 15, "totalDays": 865 } } ``` ### Get all 9 Mahadasha periods (120-year cycle) - **Method:** `POST` - **Path:** `/vedic-astrology/dasha/major` - **Tags:** Vedic Astrology Returns complete Vimshottari Dasha cycle starting from birth. Shows all major planetary periods from birth through 120 years. #### Request Body ##### Content-Type: application/json - **`day` (required)** `integer` - **`hour` (required)** `number` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`month` (required)** `integer` - **`year` (required)** `integer` **Example:** ```json { "year": 1990, "month": 7, "day": 4, "hour": 10.2, "latitude": 28.6139, "longitude": 77.209 } ``` #### Responses ##### Status: 200 All 9 Mahadasha periods ###### Content-Type: application/json - **`birthDashaBalance` (required)** `object` — Remaining balance of first Mahadasha at birth - **`days` (required)** `number` - **`months` (required)** `number` - **`totalDays` (required)** `number` - **`years` (required)** `number` - **`mahadashas` (required)** `array` — All 9 Mahadasha periods in sequence **Items:** - **`durationYears` (required)** `number` - **`endDate` (required)** `string`, format: `date-time` - **`planet` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`startDate` (required)** `string`, format: `date-time` - **`interpretation`** `string` - **`moonNakshatra` (required)** `integer` - **`nakshatraLord` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`nakshatraName` (required)** `string` - **`totalYears` (required)** `number` **Example:** ```json { "moonNakshatra": 1, "nakshatraName": "", "nakshatraLord": "Ketu", "birthDashaBalance": { "years": 2, "months": 4, "days": 15, "totalDays": 865 }, "mahadashas": [ { "planet": "Ketu", "startDate": "1990-07-04T10:12:00.000Z", "endDate": "1996-07-04T10:12:00.000Z", "durationYears": 6, "interpretation": "Sun Mahadasha brings leadership opportunities, authority, and self-expression." } ], "totalYears": 120 } ``` ### Get all Antardashas (sub-periods) for a specific Mahadasha - **Method:** `POST` - **Path:** `/vedic-astrology/dasha/sub/{mahadasha}` - **Tags:** Vedic Astrology Returns 9 Antardasha sub-periods within a Mahadasha. Each Mahadasha is divided into 9 proportional sub-periods. #### Request Body ##### Content-Type: application/json - **`day` (required)** `integer` - **`hour` (required)** `number` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`month` (required)** `integer` - **`year` (required)** `integer` **Example:** ```json { "year": 1990, "month": 7, "day": 4, "hour": 10.2, "latitude": 28.6139, "longitude": 77.209 } ``` #### Responses ##### Status: 200 Antardasha periods for specified Mahadasha ###### Content-Type: application/json - **`antardashas` (required)** `array` **Items:** - **`durationYears` (required)** `number` - **`endDate` (required)** `string`, format: `date-time` - **`mahadashaLord` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`planet` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`startDate` (required)** `string`, format: `date-time` - **`interpretation`** `string` - **`mahadashaLord` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`mahadashaPeriod` (required)** `object` — Mahadasha period for a planet with interpretation - **`durationYears` (required)** `number` - **`endDate` (required)** `string`, format: `date-time` - **`planet` (required)** `string`, possible values: `"Ketu", "Venus", "Sun", "Moon", "Mars", "Rahu", "Jupiter", "Saturn", "Mercury"` - **`startDate` (required)** `string`, format: `date-time` - **`interpretation`** `string` **Example:** ```json { "mahadashaLord": "Ketu", "mahadashaPeriod": { "planet": "Ketu", "startDate": "1990-07-04T10:12:00.000Z", "endDate": "1996-07-04T10:12:00.000Z", "durationYears": 6, "interpretation": "Sun Mahadasha brings leadership opportunities, authority, and self-expression." }, "antardashas": [ { "planet": "Ketu", "startDate": "1990-07-04T10:12:00.000Z", "endDate": "1996-07-04T10:12:00.000Z", "durationYears": 6, "interpretation": "Sun Mahadasha brings leadership opportunities, authority, and self-expression.", "mahadashaLord": "Ketu" } ] } ``` ### Get basic Panchang - Tithi Nakshatra Yoga Karana Calculator - **Method:** `POST` - **Path:** `/vedic-astrology/panchang/basic` - **Tags:** Vedic Astrology Calculate Panchang elements (Hindu calendar) for any date: Tithi (lunar day), Nakshatra (lunar mansion), Yoga, and Karana. Daily panchang API for determining auspicious timings (muhurta), festival dates, and planetary influences. Tithi calculator with Shukla/Krishna paksha. Accurate nakshatra today with ruling planet. Essential for Hindu calendar integration, muhurta selection, and Vedic timekeeping in astrology apps. #### Request Body ##### Content-Type: application/json - **`day` (required)** `integer` - **`hour` (required)** `number` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`month` (required)** `integer` - **`year` (required)** `integer` **Example:** ```json { "year": 2025, "month": 12, "day": 17, "hour": 12, "latitude": 28.6139, "longitude": 77.209 } ``` #### Responses ##### Status: 200 Panchang elements calculated successfully ###### Content-Type: application/json - **`karana` (required)** `object` — Karana (half-tithi) information with characteristics - **`name` (required)** `string` - **`number` (required)** `integer` - **`characteristics`** `string` - **`type`** `string` - **`moonLongitude` (required)** `number` - **`nakshatra` (required)** `object` — Nakshatra (lunar mansion) information with interpretations - **`lord` (required)** `string` - **`name` (required)** `string` - **`number` (required)** `integer` - **`characteristics`** `string` - **`deity`** `string` - **`symbol`** `string` - **`sunLongitude` (required)** `number` - **`tithi` (required)** `object` — Lunar day (tithi) information with interpretations - **`name` (required)** `string` - **`number` (required)** `integer` - **`paksha` (required)** `string`, possible values: `"Shukla", "Krishna"` - **`percent` (required)** `number` - **`deity`** `string` - **`element`** `string` - **`rulingPlanet`** `string` - **`yoga` (required)** `object` — Yoga information with characteristics - **`name` (required)** `string` - **`number` (required)** `integer` - **`characteristics`** `string` **Example:** ```json { "tithi": { "number": 1, "name": "", "paksha": "Shukla", "percent": 0, "deity": "Vishnu", "rulingPlanet": "Sun", "element": "Fire" }, "nakshatra": { "number": 1, "name": "", "lord": "", "deity": "Ashwini Kumaras", "symbol": "Horse Head", "characteristics": "Quick, healing energy" }, "yoga": { "number": 1, "name": "", "characteristics": "Auspicious for new beginnings" }, "karana": { "number": 1, "name": "", "type": "Movable", "characteristics": "Good for travel and movement" }, "sunLongitude": 265.42, "moonLongitude": 315.67 } ``` ### Check Manglik Dosha - Mangal Dosha Calculator API - **Method:** `POST` - **Path:** `/vedic-astrology/dosha/manglik` - **Tags:** Vedic Astrology Detect Manglik dosha (Kuja dosha, Mars dosha) based on Mars position in inauspicious houses (1, 2, 4, 7, 8, 12) from Lagna. Accurate mangal dosha calculator for matrimonial compatibility checks in Vedic astrology. Returns severity levels (Mild/Moderate/Severe) and cancellation factors. Essential for kundli matching for marriage, manglik compatibility, and marriage astrology in matrimonial sites. Includes exceptions that reduce manglik dosha effects. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format - **`latitude` (required)** `number` — Birth location latitude - **`longitude` (required)** `number` — Birth location longitude - **`time` (required)** `string` — Birth time in HH:MM:SS format (24-hour) - **`timezone` (required)** `number` — Timezone offset from UTC in hours (e.g., 5.5 for IST) **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` #### Responses ##### Status: 200 Manglik dosha analysis ###### Content-Type: application/json - **`description` (required)** `string` — Detailed description of the dosha - **`present` (required)** `boolean` — Whether the dosha is present - **`exceptions`** `array` — Exceptions or cancellations that reduce severity **Items:** `string` - **`severity`** `string`, possible values: `"Mild", "Moderate", "Severe"` — Severity level of the dosha - **`type`** `string` — Type or phase of the dosha **Example:** ```json { "present": true, "severity": "Moderate", "type": "Ananta Kalsarpa", "description": "Manglik Dosha present. Mars in house 7 creates matrimonial afflictions.", "exceptions": [ "Mars in own sign (reduces severity)" ] } ``` ### Check Kalsarpa Dosha - Kalsarpa Yoga Calculator API - **Method:** `POST` - **Path:** `/vedic-astrology/dosha/kalsarpa` - **Tags:** Vedic Astrology Detect Kalsarpa dosha (Kalsarpa yoga) when all 7 planets are hemmed between Rahu-Ketu axis. Accurate kalsarpa dosha calculator identifying 12 types (Ananta, Kulik, Vasuki, Shankhapala, Padma, Mahapadma, Takshak, Karkotak, Shankhnaad, Patak, Vishdhar, Shesh). Returns severity and effects based on Rahu house position. Essential for Vedic astrology dosha analysis, birth chart evaluation, and matrimonial compatibility. Considered significant dosha affecting life obstacles and spiritual growth. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format - **`latitude` (required)** `number` — Birth location latitude - **`longitude` (required)** `number` — Birth location longitude - **`time` (required)** `string` — Birth time in HH:MM:SS format (24-hour) - **`timezone` (required)** `number` — Timezone offset from UTC in hours (e.g., 5.5 for IST) **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` #### Responses ##### Status: 200 Kalsarpa dosha analysis ###### Content-Type: application/json - **`description` (required)** `string` — Detailed description of the dosha - **`present` (required)** `boolean` — Whether the dosha is present - **`exceptions`** `array` — Exceptions or cancellations that reduce severity **Items:** `string` - **`severity`** `string`, possible values: `"Mild", "Moderate", "Severe"` — Severity level of the dosha - **`type`** `string` — Type or phase of the dosha **Example:** ```json { "present": true, "severity": "Moderate", "type": "Ananta Kalsarpa", "description": "Manglik Dosha present. Mars in house 7 creates matrimonial afflictions.", "exceptions": [ "Mars in own sign (reduces severity)" ] } ``` ### Check Sadhesati - Sade Sati Calculator API (Saturn Transit) - **Method:** `POST` - **Path:** `/vedic-astrology/dosha/sadhesati` - **Tags:** Vedic Astrology Calculate Sadhesati (Sade Sati) periods when Saturn transits 12th, 1st, and 2nd houses from natal Moon. Accurate sade sati calculator with current status and phase identification (Rising/Peak/Setting). Shani sadhesati 7.5 year period tracker. Returns Saturn transit dates and effects on life. Essential for Saturn transit analysis, sadhesati remedies timing, and understanding challenging Saturn periods in Vedic astrology. Important for timing major life decisions. #### Request Body ##### Content-Type: application/json - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format - **`latitude` (required)** `number` — Birth location latitude - **`longitude` (required)** `number` — Birth location longitude - **`time` (required)** `string` — Birth time in HH:MM:SS format (24-hour) - **`timezone` (required)** `number` — Timezone offset from UTC in hours (e.g., 5.5 for IST) **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` #### Responses ##### Status: 200 Sadhesati period analysis ###### Content-Type: application/json - **`description` (required)** `string` — Detailed description of the dosha - **`present` (required)** `boolean` — Whether the dosha is present - **`exceptions`** `array` — Exceptions or cancellations that reduce severity **Items:** `string` - **`severity`** `string`, possible values: `"Mild", "Moderate", "Severe"` — Severity level of the dosha - **`type`** `string` — Type or phase of the dosha **Example:** ```json { "present": true, "severity": "Moderate", "type": "Ananta Kalsarpa", "description": "Manglik Dosha present. Mars in house 7 creates matrimonial afflictions.", "exceptions": [ "Mars in own sign (reduces severity)" ] } ``` ### List all planetary yogas - 300+ Vedic Yoga Combinations - **Method:** `GET` - **Path:** `/vedic-astrology/yoga` - **Tags:** Vedic Astrology Returns list of all 300+ planetary yogas (astrological combinations) with basic information (id and name only). Use this to discover available yogas, then call GET /yogas/:id for detailed information. Perfect for building yoga browser interfaces, search functionality, and progressive data loading in astrology apps. #### Responses ##### Status: 200 List of all yogas (basic info) ###### Content-Type: application/json - **`total` (required)** `number` - **`yogas` (required)** `array` — List of yoga IDs and names **Items:** - **`id` (required)** `string` - **`name` (required)** `string` **Example:** ```json { "yogas": [ { "id": "gajakesari", "name": "Gajakesari Yoga" } ], "total": 300 } ``` ### Get yoga details by ID - Detailed Yoga Information API - **Method:** `GET` - **Path:** `/vedic-astrology/yoga/:id` - **Tags:** Vedic Astrology Returns complete details for a specific yoga including formation conditions, results/effects, and quality (Positive/Negative/Both). Use GET /yogas first to get the list of IDs. Provides in-depth information about each planetary combination. Perfect for yoga detail pages, educational content, and astrological interpretation in horoscope apps. #### Responses ##### Status: 200 Detailed yoga information ###### Content-Type: application/json - **`description` (required)** `string` - **`id` (required)** `string` - **`name` (required)** `string` - **`quality` (required)** `string`, possible values: `"Positive", "Negative", "Both"` - **`result` (required)** `string` **Example:** ```json { "id": "gajakesari", "name": "Gajakesari Yoga", "description": "Jupiter in kendra from Moon", "result": "Gajakesari Yoga is one of the most powerful yogas. You will be eloquent, wealthy...", "quality": "Positive" } ``` ### Get KP-Newcomb ayanamsa - Dynamic daily calculation - **Method:** `GET` - **Path:** `/vedic-astrology/kp/ayanamsa` - **Tags:** Vedic Astrology Get real-time KP-Newcomb ayanamsa value calculated using Newcomb precession theory - no preset tables. Returns precise ayanamsa for any date based on IAU modern precession standards. Essential for accurate KP chart calculations and research. Formula: A = 16.90709×(Year/10000) - 0.757371×(Year/1000)² - 6.92416, B = (Month-1 + Date/30)×1.1574074/1000. KP Newcomb ayanamsa API, dynamic ayanamsa calculator, Krishnamurti ayanamsa today, current KP ayanamsa #### Responses ##### Status: 200 Successfully calculated KP-Newcomb ayanamsa ###### Content-Type: application/json - **`ayanamsa` (required)** `number` — KP-Newcomb ayanamsa value in degrees - **`calculated` (required)** `string` — UTC timestamp when calculation was performed - **`date` (required)** `string` — Date for which ayanamsa was calculated - **`formula` (required)** `string` — Mathematical basis for ayanamsa calculation - **`type` (required)** `string` — Ayanamsa type identifier **Example:** ```json { "date": "2025-12-26", "ayanamsa": 24.22233926, "type": "kp-newcomb", "formula": "Newcomb precession theory", "calculated": "2025-12-26T10:30:00Z" } ``` ### Get KP planetary positions with sub-lords - **Method:** `POST` - **Path:** `/vedic-astrology/kp/planets` - **Tags:** Vedic Astrology Get planetary positions with detailed KP star-lord and sub-lord calculations for precise event timing and significator analysis. Returns all 9 planets (Sun through Ketu) with nakshatra, star-lord, sub-lord, and KP horary numbers (1-249). Essential for KP astrology software, significator analysis, and event prediction. KP planet positions API, star lord sub lord calculator, KP significator API, Krishnamurti Paddhati planets #### Request Body ##### Content-Type: application/json - **`ayanamsa` (required)** `string`, possible values: `"kp-newcomb", "custom"` — Ayanamsa type: "kp-newcomb" for dynamic calculation or "custom" to provide your own value - **`date` (required)** `string` — Birth date in YYYY-MM-DD format - **`latitude` (required)** `number` — Birth location latitude in decimal degrees - **`longitude` (required)** `number` — Birth location longitude in decimal degrees - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours - **`ayanamsaValue`** `number` — Custom ayanamsa value in degrees (required if ayanamsa="custom") **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5, "ayanamsa": "kp-newcomb", "ayanamsaValue": 24 } ``` #### Responses ##### Status: 200 Successfully calculated KP planetary positions ###### Content-Type: application/json - **`ayanamsa` (required)** `number` — Applied ayanamsa value in degrees - **`planets` (required)** `array` **Items:** - **`kpNumber` (required)** `number` — KP horary number (1-249) - **`longitude` (required)** `number` — Sidereal ecliptic longitude (0-360°) - **`nakshatra` (required)** `string` — Nakshatra (lunar mansion) - **`nakshatraLord` (required)** `string` — Nakshatra ruling planet - **`nakshatraNumber` (required)** `number` — Nakshatra number (1-27) - **`pada` (required)** `number` — Nakshatra pada/quarter (1-4) - **`planet` (required)** `string` — Planet name - **`retrograde` (required)** `boolean` — Whether planet is in retrograde motion - **`sign` (required)** `string` — Zodiac sign - **`signLord` (required)** `string` — Ruling planet of the sign - **`starLord` (required)** `string` — Star-lord (same as nakshatra lord in KP system) - **`subLord` (required)** `string` — Sub-lord based on 249-level KP subdivision **Example:** ```json { "ayanamsa": 24.22233926, "planets": [ { "planet": "Sun", "longitude": 108.23, "sign": "Cancer", "signLord": "Moon", "nakshatra": "Pushya", "nakshatraNumber": 8, "nakshatraLord": "Saturn", "pada": 2, "starLord": "Saturn", "subLord": "Mercury", "kpNumber": 45, "retrograde": false } ] } ``` ### Get Placidus house cusps with sub-lords - **Method:** `POST` - **Path:** `/vedic-astrology/kp/cusps` - **Tags:** Vedic Astrology Calculate unequal Placidus house cusps with ruling sign-lord, nakshatra-lord, and sub-lord for each cusp. Dynamic KP-Newcomb or custom ayanamsa support. Used in KP horary astrology, cusp sub-lord analysis, and birth chart rectification. Returns all 12 house cusps with KP sub-division details. SEO: Placidus house cusps API, KP cusp calculator, house cusps star sub lord, KP horary cusps #### Request Body ##### Content-Type: application/json - **`ayanamsa` (required)** `string`, possible values: `"kp-newcomb", "custom"` — Ayanamsa type: "kp-newcomb" for dynamic calculation or "custom" for custom value - **`date` (required)** `string` — Birth date in YYYY-MM-DD format - **`latitude` (required)** `number` — Birth location latitude in decimal degrees - **`longitude` (required)** `number` — Birth location longitude in decimal degrees - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours - **`ayanamsaValue`** `number` — Custom ayanamsa value in degrees (required if ayanamsa="custom") **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5, "ayanamsa": "kp-newcomb", "ayanamsaValue": 24 } ``` #### Responses ##### Status: 200 Successfully calculated Placidus house cusps ###### Content-Type: application/json - **`ayanamsa` (required)** `number` — Applied ayanamsa value in degrees - **`cusps` (required)** `array` **Items:** - **`house` (required)** `number` — House number (1-12) - **`kpNumber` (required)** `number` — KP horary number (1-249) - **`longitude` (required)** `number` — Cusp longitude in degrees (0-360) - **`nakshatra` (required)** `string` — Nakshatra at cusp position - **`nakshatraLord` (required)** `string` — Nakshatra ruling planet - **`pada` (required)** `number` — Nakshatra pada/quarter (1-4) - **`sign` (required)** `string` — Zodiac sign of the cusp - **`signLord` (required)** `string` — Ruling planet of the sign - **`starLord` (required)** `string` — Star-lord (nakshatra lord) - **`subLord` (required)** `string` — Sub-lord based on KP 249-level subdivision - **`houseSystem` (required)** `string` — House system used for calculations **Example:** ```json { "ayanamsa": 24, "houseSystem": "placidus", "cusps": [ { "house": 1, "longitude": 89.45, "sign": "Cancer", "signLord": "Moon", "nakshatra": "Ashlesha", "nakshatraLord": "Mercury", "pada": 3, "starLord": "Mercury", "subLord": "Venus", "kpNumber": 32 } ] } ``` ### Generate complete KP birth chart - **Method:** `POST` - **Path:** `/vedic-astrology/kp/chart` - **Tags:** Vedic Astrology Generate authentic Krishnamurti Paddhati birth charts with Placidus house cusps, star-lord and sub-lord calculations. Supports custom ayanamsa and dynamic KP-Newcomb ayanamsa calculation. Returns complete chart with all 9 planets (Sun through Ketu), Ascendant, 12 Placidus house cusps, nakshatra details, star-lords, sub-lords, and KP horary numbers (1-249). Perfect for KP astrology software, horary prediction apps, and event timing analysis. SEO: KP astrology chart API, Placidus house cusps planets, Krishnamurti Paddhati chart generator, KP birth chart calculator #### Request Body ##### Content-Type: application/json - **`ayanamsa` (required)** `string`, possible values: `"kp-newcomb", "custom"` — Ayanamsa type: "kp-newcomb" for dynamic KP-Newcomb calculation or "custom" for custom value - **`date` (required)** `string` — Birth date in YYYY-MM-DD format - **`latitude` (required)** `number` — Birth location latitude in decimal degrees - **`longitude` (required)** `number` — Birth location longitude in decimal degrees - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. CRITICAL for accurate Lagna and house calculations. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (e.g., India IST = 5.5) - **`ayanamsaValue`** `number` — Custom ayanamsa value in degrees (required if ayanamsa="custom") **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5, "ayanamsa": "kp-newcomb", "ayanamsaValue": 24 } ``` #### Responses ##### Status: 200 Successfully generated KP birth chart ###### Content-Type: application/json - **`ascendant` (required)** `object` - **`kpNumber` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`nakshatraLord` (required)** `string` - **`pada` (required)** `number` - **`sign` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` - **`cusps` (required)** `array` **Items:** - **`house` (required)** `number` - **`kpNumber` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`nakshatraLord` (required)** `string` - **`pada` (required)** `number` - **`sign` (required)** `string` - **`signLord` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` - **`meta` (required)** `object` - **`ayanamsa` (required)** `number` - **`ayanamsaType` (required)** `string` - **`date` (required)** `string` - **`houseSystem` (required)** `string` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` - **`nodes` (required)** `object` - **`ketu` (required)** `object` - **`house` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`sign` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` - **`rahu` (required)** `object` - **`house` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`sign` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` - **`planets` (required)** `array` **Items:** - **`house` (required)** `number` - **`kpNumber` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`nakshatraLord` (required)** `string` - **`pada` (required)** `number` - **`planet` (required)** `string` - **`retrograde` (required)** `boolean` - **`sign` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` **Example:** ```json { "meta": { "date": "", "time": "", "latitude": 1, "longitude": 1, "timezone": 1, "ayanamsa": 1, "ayanamsaType": "", "houseSystem": "" }, "ascendant": { "longitude": 1, "sign": "", "nakshatra": "", "nakshatraLord": "", "pada": 1, "starLord": "", "subLord": "", "kpNumber": 1 }, "cusps": [ { "house": 1, "longitude": 1, "sign": "", "signLord": "", "nakshatra": "", "nakshatraLord": "", "pada": 1, "starLord": "", "subLord": "", "kpNumber": 1 } ], "planets": [ { "planet": "", "longitude": 1, "sign": "", "house": 1, "nakshatra": "", "nakshatraLord": "", "pada": 1, "starLord": "", "subLord": "", "kpNumber": 1, "retrograde": true } ], "nodes": { "rahu": { "longitude": 1, "sign": "", "house": 1, "nakshatra": "", "starLord": "", "subLord": "" }, "ketu": { "longitude": 1, "sign": "", "house": 1, "nakshatra": "", "starLord": "", "subLord": "" } } } ``` ### List all 78 tarot cards - **Method:** `GET` - **Path:** `/tarot/cards` - **Tags:** Tarot Retrieve the complete Rider-Waite-Smith tarot deck of 78 cards: 22 Major Arcana (numbered 0-21, representing life lessons, spiritual themes, and karmic influences like The Fool, Death, The Tower) plus 56 Minor Arcana (4 suits × 14 cards each for daily situations and practical matters). Filter by arcana type (major for spiritual guidance, minor for everyday concerns), suit (cups for emotions and relationships, wands for creativity and passion, swords for intellect and conflict, pentacles for material wealth and finances), or card number (Ace=1 for new beginnings, 2-10 for progression, Page=11 for messages, Knight=12 for action, Queen=13 for mastery, King=14 for authority). Returns lightweight basic card data - use GET /cards/:id for full upright and reversed interpretations with keywords. Perfect for building tarot reference libraries, card databases, learning applications, or browsing the complete traditional deck used by professional tarot readers worldwide. #### Responses ##### Status: 200 List of tarot cards with basic information. Use GET /cards/:id for full details. ###### Content-Type: application/json - **`cards` (required)** `array` **Items:** - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`name` (required)** `string` - **`number` (required)** `number` - **`suit`** `string`, possible values: `"cups", "wands", "swords", "pentacles"` - **`total` (required)** `number` **Example:** ```json { "total": 1, "cards": [ { "id": "fool", "name": "The Fool", "arcana": "major", "suit": "cups", "number": 0, "imageUrl": "https://roxyapi.com/img/tarot/major/fool.jpg" } ] } ``` ### Get detailed tarot card information - **Method:** `GET` - **Path:** `/tarot/cards/{id}` - **Tags:** Tarot Retrieve comprehensive details for a specific tarot card from the traditional Rider-Waite-Smith deck including complete upright meanings (card drawn normally) and reversed meanings (inverted/upside down interpretations for nuanced guidance). Each card provides keywords for quick reference, full interpretations (400+ words each for upright and reversed orientations), and guidance across life domains: love and relationships, career and professional growth, finances and material success, health and wellbeing, spirituality and personal development. Major Arcana cards (0-21) reveal deep spiritual lessons and life-changing themes. Minor Arcana cards (Ace through King in Cups, Wands, Swords, Pentacles) address practical daily situations and specific challenges. Use card ID in kebab-case format: Major Arcana like "fool", "magician", "death", "tower", or Minor Arcana like "ace-of-cups", "seven-of-wands", "queen-of-swords", "king-of-pentacles". Essential for detailed tarot study, reading interpretations, divination apps, fortune-telling platforms, spiritual guidance tools, and professional tarot learning applications. #### Responses ##### Status: 200 Card details ###### Content-Type: application/json - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `object` - **`reversed` (required)** `array` **Items:** `string` - **`upright` (required)** `array` **Items:** `string` - **`name` (required)** `string` - **`number` (required)** `number` - **`reversed` (required)** `object` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`career`** `string` - **`finances`** `string` - **`health`** `string` - **`love`** `string` - **`spirituality`** `string` - **`upright` (required)** `object` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`career`** `string` - **`finances`** `string` - **`health`** `string` - **`love`** `string` - **`spirituality`** `string` - **`suit`** `string`, possible values: `"cups", "wands", "swords", "pentacles"` **Example:** ```json { "id": "fool", "name": "The Fool", "arcana": "major", "suit": "cups", "number": 0, "keywords": { "upright": [ "beginnings", "innocence", "spontaneity" ], "reversed": [ "recklessness", "fearlessness" ] }, "upright": { "keywords": [ "" ], "description": "", "love": "", "career": "", "finances": "", "health": "", "spirituality": "" }, "reversed": { "keywords": [ "" ], "description": "", "love": "", "career": "", "finances": "", "health": "", "spirituality": "" }, "imageUrl": "https://roxyapi.com/img/tarot/major/fool.jpg" } ``` ##### Status: 404 Card not found ###### Content-Type: application/json - **`error` (required)** `string` **Example:** ```json { "error": "" } ``` ### Draw random tarot cards with reproducible results - **Method:** `POST` - **Path:** `/tarot/draw` - **Tags:** Tarot Draw 1-78 tarot cards from the complete Rider-Waite-Smith deck with seeded reproducibility for consistent personalized readings. Provide an optional seed string (like "user123-2025-12-27" or "readingId") to ensure the same seed always returns identical cards in the exact same order - essential for daily tarot features, personalized user experiences, shareable readings, or reproducible testing. Omit seed for true random draws each time. Control card reversals (upright vs reversed/inverted orientations - reversed cards provide alternative meanings when drawn upside down) and duplicates (traditional deck draws each of 78 cards once, or oracle-style allows repeating same card). Each drawn card includes position number, reversal state (boolean), keywords for quick interpretation, full meaning text (400+ words), authentic Rider-Waite imagery, and card metadata. Perfect for custom spread builders, random card generators, automated tarot reading platforms, daily card features, meditation apps, journaling prompts, divination tools, and any application requiring reproducible or random tarot draws from the industry-standard 78-card deck (22 Major Arcana spiritual lessons + 56 Minor Arcana practical guidance across 4 suits). #### Request Body ##### Content-Type: application/json - **`count` (required)** `number` — Number of cards to draw (1-78). Common values: 1 for daily card, 3 for past-present-future, 5 for relationship spread, 10 for Celtic Cross. Drawing 78 returns the entire shuffled deck. - **`allowDuplicates`** `boolean`, default: `false` — Whether same card can be drawn multiple times. Set false for traditional deck behavior (each card drawn only once). Set true for statistical analysis or oracle-style readings. Default: false. - **`allowReversals`** `boolean`, default: `true` — Whether cards can appear reversed (upside down). Reversed cards have different meanings. Set false for upright-only readings. Default: true (50% chance of reversal per card). - **`seed`** `string` — Optional seed for reproducible results. Same seed = same cards in same order. Use format like "userId-date" for daily consistency, or "readingId" for shareable readings. Omit for true randomness. **Example:** ```json { "count": 3, "seed": "user123-2025-12-27", "allowReversals": true, "allowDuplicates": false } ``` #### Responses ##### Status: 200 Drawn cards ###### Content-Type: application/json - **`cards` (required)** `array` **Items:** - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`meaning` (required)** `string` - **`name` (required)** `string` - **`position` (required)** `number` - **`reversed` (required)** `boolean` - **`number`** `number` - **`suit`** `string`, possible values: `"cups", "wands", "swords", "pentacles"` - **`seed`** `string` **Example:** ```json { "seed": "", "cards": [ { "id": "", "name": "", "arcana": "major", "suit": "cups", "number": 1, "position": 1, "reversed": true, "keywords": [ "" ], "meaning": "", "imageUrl": "" } ] } ``` ### Get daily tarot card reading - **Method:** `POST` - **Path:** `/tarot/daily` - **Tags:** Tarot Receive a single tarot card for daily guidance and reflection. This endpoint uses date-based seeding to ensure the same user gets the same card on the same day - perfect for "Card of the Day" features. Optionally provide a userId for personalized consistency (user123 always gets the same card on Dec 27), or omit for anonymous daily draws. Returns card with keywords, full meaning, and a daily message summary. Great for tarot apps, wellness platforms, morning ritual apps, and journaling tools. #### Request Body ##### Content-Type: application/json - **`date`** `string` — Date for the reading in YYYY-MM-DD format. Defaults to today (UTC). Useful for viewing past daily cards or pre-generating future readings. Must be valid ISO date string. - **`userId`** `string` — Optional user identifier for personalized daily readings. Same userId + same date = same card every time. Use database user IDs, email hashes, or session tokens. Omit for anonymous daily cards. **Example:** ```json { "userId": "user123", "date": "2025-12-27" } ``` #### Responses ##### Status: 200 Daily card reading ###### Content-Type: application/json - **`card` (required)** `object` - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`meaning` (required)** `string` - **`name` (required)** `string` - **`position` (required)** `number` - **`reversed` (required)** `boolean` - **`dailyMessage` (required)** `string` - **`date` (required)** `string` - **`seed` (required)** `string` **Example:** ```json { "date": "", "seed": "", "card": { "id": "", "name": "", "arcana": "major", "position": 1, "reversed": true, "keywords": [ "" ], "meaning": "", "imageUrl": "" }, "dailyMessage": "" } ``` ##### Status: 500 Failed to draw card ###### Content-Type: application/json - **`error` (required)** `string` **Example:** ```json { "error": "" } ``` ### Get yes/no answer to your question - **Method:** `POST` - **Path:** `/tarot/yes-no` - **Tags:** Tarot Ask a specific question and receive a yes/no answer based on a single tarot card draw. Upright cards indicate "Yes" with positive energy, reversed cards indicate "No" with caution. Major Arcana cards (The Fool, Death, etc.) give strong definitive answers, while Minor Arcana cards give qualified nuanced answers. Returns the answer, strength level, drawn card details, and a contextual interpretation explaining why. Perfect for decision-making apps, quick guidance tools, fortune-telling chatbots, and interactive tarot experiences. Optionally provide a seed for reproducible answers. #### Request Body ##### Content-Type: application/json - **`question`** `string` — Your specific yes/no question. Be clear and focused. Good: "Should I move to a new city?" Bad: "What should I do about my life?" The more specific the question, the more useful the tarot guidance. - **`seed`** `string` — Optional seed for reproducible results. Same seed + same question = same answer. Useful for testing, sharing readings, or ensuring consistency. Omit for random draws each time. **Example:** ```json { "question": "Should I accept the job offer?", "seed": "optional-seed" } ``` #### Responses ##### Status: 200 Yes/No answer with interpretation ###### Content-Type: application/json - **`answer` (required)** `string`, possible values: `"Yes", "No", "Maybe"` - **`card` (required)** `object` - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`name` (required)** `string` - **`reversed` (required)** `boolean` - **`interpretation` (required)** `string` - **`strength` (required)** `string`, possible values: `"Strong", "Qualified"` - **`question`** `string` **Example:** ```json { "question": "", "answer": "Yes", "strength": "Strong", "card": { "id": "", "name": "", "arcana": "major", "reversed": true, "keywords": [ "" ], "imageUrl": "" }, "interpretation": "" } ``` ##### Status: 500 Failed to draw card ###### Content-Type: application/json - **`error` (required)** `string` **Example:** ```json { "error": "" } ``` ### Three-Card Spread: Past, Present, Future - **Method:** `POST` - **Path:** `/tarot/spreads/three-card` - **Tags:** Tarot Perform the classic three-card tarot spread revealing Past (what led to this situation), Present (current energy and circumstances), and Future (likely outcome if current path continues). The most popular beginner-friendly spread, perfect for quick insights, daily guidance, or exploring specific questions. Each position includes a drawn card with reversal state, keywords, full meaning, and position-specific interpretation. Returns a summary connecting all three cards. Ideal for tarot reading apps, decision-making tools, and personal growth platforms. Optionally provide a seed for reproducible readings. #### Request Body ##### Content-Type: application/json - **`question`** `string` — Optional specific question to focus the reading. Examples: "What should I know about my relationship?", "How can I improve my finances?", "What's blocking my creative growth?" Leave empty for general guidance. - **`seed`** `string` — Optional seed for reproducible results. Same seed = same 3 cards in same positions. Useful for sharing readings, testing, or ensuring users get consistent results. Omit for random draws. **Example:** ```json { "question": "What do I need to know about my career?", "seed": "optional-seed" } ``` #### Responses ##### Status: 200 Three-card spread reading ###### Content-Type: application/json - **`positions` (required)** `array` **Items:** - **`card` (required)** `object` - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`meaning` (required)** `string` - **`name` (required)** `string` - **`reversed` (required)** `boolean` - **`interpretation` (required)** `string` - **`name` (required)** `string` - **`position` (required)** `number` - **`spread` (required)** `string` - **`question`** `string` - **`seed`** `string` - **`summary`** `string` **Example:** ```json { "spread": "", "question": "", "seed": "", "positions": [ { "position": 1, "name": "", "interpretation": "", "card": { "id": "", "name": "", "arcana": "major", "reversed": true, "keywords": [ "" ], "meaning": "", "imageUrl": "" } } ], "summary": "" } ``` ### Celtic Cross Spread (10 cards) - **Method:** `POST` - **Path:** `/tarot/spreads/celtic-cross` - **Tags:** Tarot Perform the legendary Celtic Cross spread - the most comprehensive and detailed tarot reading available, used by professional tarot readers worldwide for over a century. This 10-card layout reveals the complete picture of any situation through distinct positions: Present Situation (what is happening now), Challenge (obstacles crossing your path), Distant Past (root causes), Recent Past (recent influences), Best Outcome (potential positive result), Near Future (what is approaching in weeks ahead), Your Approach (your attitude and self-perception), External Influences (environment and other people impact), Hopes and Fears (your desires and anxieties), and Final Outcome (where everything is headed). Perfect for life-changing decisions, complex relationship questions, career transitions, spiritual guidance, and deep self-discovery. Ideal for professional tarot apps, life coaching platforms, spiritual wellness websites, and divination tools requiring authoritative comprehensive readings. Each card position provides layered insight combining traditional tarot wisdom with modern psychological interpretation for actionable guidance. #### Request Body ##### Content-Type: application/json - **`question`** `string` - **`seed`** `string` **Example:** ```json { "question": "What should I know about this situation?", "seed": "optional-seed" } ``` #### Responses ##### Status: 200 Celtic Cross spread reading ###### Content-Type: application/json - **`positions` (required)** `array` **Items:** - **`card` (required)** `object` - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`meaning` (required)** `string` - **`name` (required)** `string` - **`reversed` (required)** `boolean` - **`interpretation` (required)** `string` - **`name` (required)** `string` - **`position` (required)** `number` - **`spread` (required)** `string` - **`question`** `string` - **`seed`** `string` - **`summary`** `string` **Example:** ```json { "spread": "", "question": "", "seed": "", "positions": [ { "position": 1, "name": "", "interpretation": "", "card": { "id": "", "name": "", "arcana": "major", "reversed": true, "keywords": [ "" ], "meaning": "", "imageUrl": "" } } ], "summary": "" } ``` ### Love Spread (5 cards) - **Method:** `POST` - **Path:** `/tarot/spreads/love` - **Tags:** Tarot Perform a specialized 5-card relationship tarot spread analyzing romantic connections, emotional dynamics, and partnership potential. This love-focused reading examines five crucial relationship aspects: You (your current emotional state, needs, and what you bring to the relationship), Partner/Other (their emotional perspective, desires, and energy), Relationship Dynamic (the current energy and connection between you both), Challenge (obstacles needing attention, healing, or communication), and Outcome (where this romantic connection is naturally heading). Perfect for dating apps, relationship counseling platforms, matchmaking services, wellness apps, and romantic guidance tools. Provides deep insight into new relationships, existing partnerships, potential connections, breakup recovery, or self-love journeys. Ideal for understanding compatibility, resolving conflicts, strengthening bonds, or deciding whether to pursue or continue a relationship. Each position reveals emotional truths combining traditional tarot relationship wisdom with modern relationship psychology. Use for individual readings or couples readings to gain perspective on romantic situations from singleness to marriage. #### Request Body ##### Content-Type: application/json - **`question`** `string` - **`seed`** `string` **Example:** ```json { "question": "What do I need to know about my relationship?", "seed": "optional-seed" } ``` #### Responses ##### Status: 200 Love spread reading ###### Content-Type: application/json - **`positions` (required)** `array` **Items:** - **`card` (required)** `object` - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`meaning` (required)** `string` - **`name` (required)** `string` - **`reversed` (required)** `boolean` - **`interpretation` (required)** `string` - **`name` (required)** `string` - **`position` (required)** `number` - **`spread` (required)** `string` - **`question`** `string` - **`seed`** `string` - **`summary`** `string` **Example:** ```json { "spread": "", "question": "", "seed": "", "positions": [ { "position": 1, "name": "", "interpretation": "", "card": { "id": "", "name": "", "arcana": "major", "reversed": true, "keywords": [ "" ], "meaning": "", "imageUrl": "" } } ], "summary": "" } ``` ### Career Spread (7 cards) - **Method:** `POST` - **Path:** `/tarot/spreads/career` - **Tags:** Tarot Perform a comprehensive 7-card career tarot spread using SWOT analysis framework (Strengths, Weaknesses, Opportunities, Threats) for professional guidance, business decisions, and vocational clarity. This career-focused reading examines seven strategic business aspects: Current Situation (your present professional position and workplace energy), Strengths (your professional assets, talents, and competitive advantages), Weaknesses (areas needing development, skill gaps, or limiting beliefs), Opportunities (potential growth paths, new ventures, or doors opening), Threats (obstacles, competition, or external challenges), Advice (actionable guidance for navigating your career path), and Outcome (where your professional journey is heading if you follow the guidance). Perfect for career coaching platforms, professional development apps, business consulting tools, job search websites, entrepreneurship platforms, and executive coaching services. Use for career transitions, job offers evaluation, promotion decisions, starting a business, workplace conflicts, finding your calling, or strategic career planning. Combines traditional tarot wisdom with modern SWOT business analysis for practical professional insight. Ideal for employees, entrepreneurs, freelancers, career changers, and anyone seeking vocational direction. #### Request Body ##### Content-Type: application/json - **`question`** `string` - **`seed`** `string` **Example:** ```json { "question": "What do I need to know about my career path?", "seed": "optional-seed" } ``` #### Responses ##### Status: 200 Career spread reading ###### Content-Type: application/json - **`positions` (required)** `array` **Items:** - **`card` (required)** `object` - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`meaning` (required)** `string` - **`name` (required)** `string` - **`reversed` (required)** `boolean` - **`interpretation` (required)** `string` - **`name` (required)** `string` - **`position` (required)** `number` - **`spread` (required)** `string` - **`question`** `string` - **`seed`** `string` - **`summary`** `string` **Example:** ```json { "spread": "", "question": "", "seed": "", "positions": [ { "position": 1, "name": "", "interpretation": "", "card": { "id": "", "name": "", "arcana": "major", "reversed": true, "keywords": [ "" ], "meaning": "", "imageUrl": "" } } ], "summary": "" } ``` ### Custom Spread Builder - **Method:** `POST` - **Path:** `/tarot/spreads/custom` - **Tags:** Tarot Build and perform your own custom tarot spread with personalized positions and interpretations (1-10 cards). This flexible endpoint lets you create unique spread layouts for any purpose - define your own position names, meanings, and card count to match your specific needs or therapeutic framework. Perfect for therapists using tarot in counseling, coaches creating signature spreads, app developers building custom reading features, spiritual practitioners with proprietary methods, or anyone wanting to design specialized layouts beyond traditional spreads. Create spreads for specific themes like chakra readings (7 cards), lunar phases (8 cards), elements (4 cards), goals setting (any count), shadow work, inner child healing, decision matrices, or creative problem-solving. Each position requires a name and interpretation - you define what each card position represents in your reading. The API draws the exact number of cards you specify and maps them to your custom positions. No pre-generated summary provided - you interpret the reading based on your framework. Ideal for innovative tarot apps, therapeutic tools, personal development platforms, spiritual coaching services, or experimental divination methods. Maximum 10 positions to maintain reading clarity and practical interpretation time. #### Request Body ##### Content-Type: application/json - **`positions` (required)** `array` **Items:** - **`interpretation` (required)** `string` - **`name` (required)** `string` - **`question`** `string` - **`seed`** `string` - **`spreadName`** `string` **Example:** ```json { "spreadName": "My Custom Spread", "positions": [ { "name": "Core Issue", "interpretation": "What is really going on" }, { "name": "Hidden Factor", "interpretation": "What you cannot see" }, { "name": "Best Action", "interpretation": "What to do next" } ], "question": "Optional question", "seed": "optional-seed" } ``` #### Responses ##### Status: 200 Custom spread reading ###### Content-Type: application/json - **`positions` (required)** `array` **Items:** - **`card` (required)** `object` - **`arcana` (required)** `string`, possible values: `"major", "minor"` - **`id` (required)** `string` - **`imageUrl` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`meaning` (required)** `string` - **`name` (required)** `string` - **`reversed` (required)** `boolean` - **`interpretation` (required)** `string` - **`name` (required)** `string` - **`position` (required)** `number` - **`spread` (required)** `string` - **`question`** `string` - **`seed`** `string` - **`summary`** `string` **Example:** ```json { "spread": "", "question": "", "seed": "", "positions": [ { "position": 1, "name": "", "interpretation": "", "card": { "id": "", "name": "", "arcana": "major", "reversed": true, "keywords": [ "" ], "meaning": "", "imageUrl": "" } } ], "summary": "" } ``` ### Calculate Life Path number - Most important numerology calculation - **Method:** `POST` - **Path:** `/numerology/life-path` - **Tags:** Numerology Calculate your Life Path number from your birth date using Pythagorean numerology. This is the most significant number in your numerology chart, revealing your life purpose, natural talents, and destiny path. Automatically detects Master Numbers (11, 22, 33) and Karmic Debt numbers (13, 14, 16, 19). Returns comprehensive interpretation including personality traits, strengths, challenges, career guidance, relationship compatibility, and spiritual insights. Perfect for numerology apps, birth chart calculators, life purpose discovery tools, personal development platforms, and astrology services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33. #### Request Body ##### Content-Type: application/json - **`day` (required)** `integer` — Birth day (1-31) - **`month` (required)** `integer` — Birth month (1-12) - **`year` (required)** `integer` — Birth year (1900-2100) **Example:** ```json { "year": 1990, "month": 7, "day": 15 } ``` #### Responses ##### Status: 200 Successfully calculated Life Path number with detailed interpretation ###### Content-Type: application/json - **`calculation` (required)** `string` — Step-by-step calculation breakdown - **`hasKarmicDebt` (required)** `boolean` — Whether this number has karmic debt (13, 14, 16, 19) - **`meaning` (required)** `object` - **`career` (required)** `string` — Career guidance and professional strengths - **`challenges` (required)** `array` — Common challenges and lessons to overcome **Items:** `string` - **`description` (required)** `string` — Comprehensive 300-500 word description - **`keywords` (required)** `array` — Key personality traits **Items:** `string` - **`relationships` (required)** `string` — Relationship dynamics and compatibility insights - **`spirituality` (required)** `string` — Spiritual path and higher purpose guidance - **`strengths` (required)** `array` — Core strengths and positive qualities **Items:** `string` - **`title` (required)** `string` — Archetype title - **`number` (required)** `number` — Life Path number (1-9, 11, 22, 33) - **`type` (required)** `string`, possible values: `"single", "master"` — Number type classification - **`karmicDebtNumber`** `number` — Karmic debt number if present (13, 14, 16, 19) **Example:** ```json { "number": 5, "calculation": "1990 + 7 + 15 = 2012 → 2+0+1+2 = 5", "type": "single", "hasKarmicDebt": false, "karmicDebtNumber": 14, "meaning": { "title": "The Freedom Seeker", "keywords": [ "adventurous", "freedom", "versatile", "dynamic", "curious" ], "description": "People with a 5 Life Path number are on a lifelong adventure. They are ready for anything and want to soak up every experience this world has to offer...", "strengths": [ "Adaptability", "Communication", "Curiosity", "Resourcefulness" ], "challenges": [ "Restlessness", "Commitment issues", "Impulsiveness" ], "career": "Suited for careers that offer variety and freedom: travel, sales, marketing, journalism, entrepreneurship...", "relationships": "In relationships, needs freedom and variety. Makes exciting partner but may struggle with long-term commitment...", "spirituality": "Spiritual growth comes through diverse experiences. Learns life lessons by exploring different philosophies and cultures..." } } ``` ### Calculate Expression number - Natural talents and life goals - **Method:** `POST` - **Path:** `/numerology/expression` - **Tags:** Numerology Calculate your Expression (Destiny) number from your full birth name using Pythagorean numerology. This number reveals your natural talents, abilities, and life goals. It shows what you came here to do and what tools you have to accomplish your life purpose. Returns comprehensive interpretation including personality traits, career paths, relationship dynamics, and spiritual insights. Automatically detects Master Numbers (11, 22, 33). Perfect for name numerology apps, career guidance tools, personal development platforms, and talent assessment services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33. #### Request Body ##### Content-Type: application/json - **`fullName` (required)** `string` — Full birth name (first, middle, last) **Example:** ```json { "fullName": "John William Smith" } ``` #### Responses ##### Status: 200 Successfully calculated Expression number with detailed interpretation ###### Content-Type: application/json - **`calculation` (required)** `string` — Step-by-step calculation breakdown showing all name values - **`hasKarmicDebt` (required)** `boolean` — Whether calculation passed through karmic debt number - **`meaning` (required)** `object` - **`career` (required)** `string` — Career guidance based on natural talents - **`challenges` (required)** `array` — Common challenges to overcome **Items:** `string` - **`description` (required)** `string` — Comprehensive 300-500 word description - **`keywords` (required)** `array` — Key personality traits **Items:** `string` - **`relationships` (required)** `string` — Relationship dynamics and compatibility - **`spirituality` (required)** `string` — Spiritual path and higher purpose - **`strengths` (required)** `array` — Core strengths and talents **Items:** `string` - **`title` (required)** `string` — Archetype title - **`number` (required)** `number` — Expression number (1-9, 11, 22, 33) - **`type` (required)** `string`, possible values: `"single", "master"` — Number type classification - **`karmicDebtNumber`** `number` — Karmic debt number if detected (13, 14, 16, 19) **Example:** ```json { "number": 7, "calculation": "1+6+8+5 + 5+9+3+3+9+1+4 + 1+4+9+2+8 = 78 → 7+8 = 15 → 1+5 = 6", "type": "single", "hasKarmicDebt": false, "karmicDebtNumber": 14, "meaning": { "title": "The Seeker", "keywords": [ "analytical", "spiritual", "wise", "introspective", "perfectionist" ], "description": "People with a 7 Expression number have a natural gift for analysis and investigation...", "strengths": [ "Deep thinking", "Intuition", "Research ability", "Spiritual insight" ], "challenges": [ "Aloofness", "Over-analysis", "Skepticism" ], "career": "Suited for research, science, spirituality, teaching, technology...", "relationships": "Needs intellectual connection and personal space in relationships...", "spirituality": "Natural spiritual seeker with deep connection to inner wisdom..." } } ``` ### Calculate Soul Urge number - Inner motivations and desires - **Method:** `POST` - **Path:** `/numerology/soul-urge` - **Tags:** Numerology Calculate your Soul Urge (Heart Desire) number from the vowels in your birth name using Pythagorean numerology. This number reveals your innermost desires, motivations, and what your soul truly wants to experience. It shows what drives you from within, your emotional needs, and what brings you fulfillment. Returns comprehensive interpretation including personality traits, emotional needs, relationship desires, and spiritual longings. Automatically detects Master Numbers (11, 22, 33). Perfect for self-discovery apps, emotional intelligence tools, relationship counseling platforms, and personal development services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33. #### Request Body ##### Content-Type: application/json - **`fullName` (required)** `string` — Full birth name (vowels will be extracted) **Example:** ```json { "fullName": "John William Smith" } ``` #### Responses ##### Status: 200 Successfully calculated Soul Urge number with detailed interpretation ###### Content-Type: application/json - **`calculation` (required)** `string` — Step-by-step calculation showing vowel values only - **`hasKarmicDebt` (required)** `boolean` — Whether calculation passed through karmic debt number - **`meaning` (required)** `object` - **`career` (required)** `string` — Career paths that satisfy inner needs - **`challenges` (required)** `array` — Inner challenges to balance **Items:** `string` - **`description` (required)** `string` — Comprehensive 300-500 word description of inner nature - **`keywords` (required)** `array` — Key inner traits and motivations **Items:** `string` - **`relationships` (required)** `string` — Relationship needs and emotional dynamics - **`spirituality` (required)** `string` — Spiritual desires and inner path - **`strengths` (required)** `array` — Core emotional strengths **Items:** `string` - **`title` (required)** `string` — Archetype title - **`number` (required)** `number` — Soul Urge number (1-9, 11, 22, 33) - **`type` (required)** `string`, possible values: `"single", "master"` — Number type classification - **`karmicDebtNumber`** `number` — Karmic debt number if detected (13, 14, 16, 19) **Example:** ```json { "number": 6, "calculation": "6+9+1 + 9+9+1 + 9 = 44 → 4+4 = 8", "type": "single", "hasKarmicDebt": false, "karmicDebtNumber": 13, "meaning": { "title": "The Nurturer", "keywords": [ "caring", "responsible", "harmonious", "protective", "service" ], "description": "People with a 6 Soul Urge number have a deep desire to nurture and care for others...", "strengths": [ "Compassion", "Responsibility", "Harmony creation", "Service orientation" ], "challenges": [ "Over-responsibility", "Martyrdom", "Interference" ], "career": "Emotionally fulfilling in healing, counseling, teaching, caregiving...", "relationships": "Seeks to create harmony and provide emotional support in relationships...", "spirituality": "Spiritual fulfillment through service and unconditional love..." } } ``` ### Calculate Personality number - How others perceive you - **Method:** `POST` - **Path:** `/numerology/personality` - **Tags:** Numerology Calculate your Personality number from the consonants in your birth name using Pythagorean numerology. This number reveals how others perceive you, your outer personality, and first impressions you make. It represents the mask you show the world and your social persona. Returns comprehensive interpretation including public image, social dynamics, professional presence, and relationship first impressions. Automatically detects Master Numbers (11, 22, 33). Perfect for personal branding apps, social skills training, professional development platforms, and communication coaching services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33. #### Request Body ##### Content-Type: application/json - **`fullName` (required)** `string` — Full birth name (consonants will be extracted) **Example:** ```json { "fullName": "John William Smith" } ``` #### Responses ##### Status: 200 Successfully calculated Personality number with detailed interpretation ###### Content-Type: application/json - **`calculation` (required)** `string` — Step-by-step calculation showing consonant values only - **`hasKarmicDebt` (required)** `boolean` — Whether calculation passed through karmic debt number - **`meaning` (required)** `object` - **`career` (required)** `string` — Professional presence and career guidance - **`challenges` (required)** `array` — Outer personality challenges **Items:** `string` - **`description` (required)** `string` — Comprehensive 300-500 word description of public persona - **`keywords` (required)** `array` — Key outer personality traits **Items:** `string` - **`relationships` (required)** `string` — Relationship first impressions and social dynamics - **`spirituality` (required)** `string` — Spiritual presence and public path - **`strengths` (required)** `array` — Core outer strengths **Items:** `string` - **`title` (required)** `string` — Public archetype - **`number` (required)** `number` — Personality number (1-9, 11, 22, 33) - **`type` (required)** `string`, possible values: `"single", "master"` — Number type classification - **`karmicDebtNumber`** `number` — Karmic debt number if detected (13, 14, 16, 19) **Example:** ```json { "number": 9, "calculation": "1+8+5 + 5+3+3+4 + 1+4+2+8 = 44 → 4+4 = 8", "type": "single", "hasKarmicDebt": false, "karmicDebtNumber": 16, "meaning": { "title": "The Humanitarian", "keywords": [ "compassionate", "charismatic", "idealistic", "generous", "wise" ], "description": "People with a 9 Personality number project warmth and compassion to others...", "strengths": [ "Charisma", "Compassion", "Wisdom", "Universal understanding" ], "challenges": [ "Emotional distance", "Impracticality", "Scattered energy" ], "career": "Public image suited for humanitarian work, counseling, arts, teaching...", "relationships": "First impression is warm and accepting, attracts many connections...", "spirituality": "Projects spiritual wisdom and universal love to the world..." } } ``` ### Calculate Birth Day number - Special talents from day of birth - **Method:** `POST` - **Path:** `/numerology/birth-day` - **Tags:** Numerology Calculate your Birth Day number from the day you were born (1-31) using Pythagorean numerology. This number reveals special talents and abilities you possess from birth. It shows natural gifts that can help you achieve your life purpose. Returns comprehensive interpretation including innate talents, natural abilities, career advantages, and how to leverage your special gifts. Automatically detects Master Numbers (11, 22) and reduces double-digit days. Perfect for talent discovery apps, career counseling platforms, personal development services, and skill assessment tools. Get detailed 300-500 word meanings for all numbers 1-9, 11, and 22. #### Request Body ##### Content-Type: application/json - **`day` (required)** `integer` — Day of birth (1-31) **Example:** ```json { "day": 23 } ``` #### Responses ##### Status: 200 Successfully calculated Birth Day number with detailed interpretation ###### Content-Type: application/json - **`calculation` (required)** `string` — Step-by-step calculation (single digit if 1-9) - **`hasKarmicDebt` (required)** `boolean` — Whether day number has karmic debt - **`meaning` (required)** `object` - **`career` (required)** `string` — Career paths that leverage natural abilities - **`challenges` (required)** `array` — Natural challenges to balance **Items:** `string` - **`description` (required)** `string` — Comprehensive 300-500 word description of special gifts - **`keywords` (required)** `array` — Key innate talents **Items:** `string` - **`relationships` (required)** `string` — Relationship dynamics based on innate nature - **`spirituality` (required)** `string` — Spiritual path and natural gifts application - **`strengths` (required)** `array` — Core innate strengths **Items:** `string` - **`title` (required)** `string` — Talent archetype - **`number` (required)** `number` — Birth Day number (1-9, 11, 22) - **`type` (required)** `string`, possible values: `"single", "master"` — Number type classification - **`karmicDebtNumber`** `number` — Karmic debt number if present (13, 14, 16, 19) **Example:** ```json { "number": 5, "calculation": "23 → 2+3 = 5", "type": "single", "hasKarmicDebt": false, "karmicDebtNumber": 19, "meaning": { "title": "The Freedom Seeker", "keywords": [ "versatile", "adaptable", "communicative", "adventurous", "dynamic" ], "description": "People born on a 5 Birth Day have natural versatility and adaptability...", "strengths": [ "Adaptability", "Communication", "Quick learning", "Versatility" ], "challenges": [ "Restlessness", "Scattered energy", "Commitment avoidance" ], "career": "Natural talents for travel, sales, communication, entrepreneurship...", "relationships": "Brings excitement and variety to relationships, needs freedom...", "spirituality": "Spiritual growth through diverse experiences and freedom..." } } ``` ### Calculate Maturity number - Who you become in later life - **Method:** `POST` - **Path:** `/numerology/maturity` - **Tags:** Numerology Calculate your Maturity (Realization) number by adding Life Path and Expression numbers using Pythagorean numerology. This number reveals who you become in the second half of life, typically manifesting after age 35-40. It shows the ultimate goal of personal development and mature self-expression. Returns comprehensive interpretation including life transformation, mature personality, later-life purpose, and wisdom development. Automatically detects Master Numbers (11, 22, 33). Perfect for life coaching apps, midlife guidance platforms, personal development services, and aging wisdom tools. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33. #### Request Body ##### Content-Type: application/json - **`expression` (required)** `integer` — Your Expression number (1-9, 11, 22, 33) - **`lifePath` (required)** `integer` — Your Life Path number (1-9, 11, 22, 33) **Example:** ```json { "lifePath": 5, "expression": 7 } ``` #### Responses ##### Status: 200 Successfully calculated Maturity number with detailed interpretation ###### Content-Type: application/json - **`calculation` (required)** `string` — Step-by-step calculation showing Life Path + Expression - **`hasKarmicDebt` (required)** `boolean` — Whether calculation passed through karmic debt number - **`meaning` (required)** `object` - **`career` (required)** `string` — Career paths for mature stage - **`challenges` (required)** `array` — Mature challenges to balance **Items:** `string` - **`description` (required)** `string` — Comprehensive 300-500 word description of mature self - **`keywords` (required)** `array` — Key mature personality traits **Items:** `string` - **`relationships` (required)** `string` — Relationship dynamics in later life - **`spirituality` (required)** `string` — Spiritual path in later life - **`strengths` (required)** `array` — Core mature strengths **Items:** `string` - **`title` (required)** `string` — Mature archetype - **`number` (required)** `number` — Maturity number (1-9, 11, 22, 33) - **`type` (required)** `string`, possible values: `"single", "master"` — Number type classification - **`karmicDebtNumber`** `number` — Karmic debt number if detected (13, 14, 16, 19) **Example:** ```json { "number": 3, "calculation": "5 + 7 = 12 → 1+2 = 3", "type": "single", "hasKarmicDebt": false, "karmicDebtNumber": 14, "meaning": { "title": "The Creative Communicator", "keywords": [ "expressive", "creative", "joyful", "communicative", "optimistic" ], "description": "People with a 3 Maturity number grow into creative and joyful expression...", "strengths": [ "Creative expression", "Communication", "Joy", "Social charm" ], "challenges": [ "Scattered energy", "Superficiality", "Over-sensitivity" ], "career": "Later-life fulfillment in creative fields, communication, arts, entertainment...", "relationships": "Mature relationships become more expressive and joyful...", "spirituality": "Spiritual maturity through creative expression and joy..." } } ``` ### Analyze Karmic Lessons - Life lessons from missing numbers - **Method:** `POST` - **Path:** `/numerology/karmic-lessons` - **Tags:** Numerology Analyze your Karmic Lessons from your birth name using Pythagorean numerology. Karmic lessons are indicated by numbers missing from your name (numbers 1-9 that do not appear). These represent challenges you came to learn and skills you need to develop in this lifetime. Returns comprehensive analysis including missing numbers, specific lessons for each, challenges to overcome, and practical guidance for development. Perfect for spiritual growth apps, personal development platforms, life coaching services, and self-improvement tools. Get detailed lesson descriptions, development strategies, and practical exercises for each missing number. #### Request Body ##### Content-Type: application/json - **`fullName` (required)** `string` — Full birth name to analyze for missing numbers **Example:** ```json { "fullName": "John William Smith" } ``` #### Responses ##### Status: 200 Successfully analyzed karmic lessons with development guidance ###### Content-Type: application/json - **`lessons` (required)** `array` **Items:** - **`description` (required)** `string` — Detailed lesson explanation - **`howToOvercome` (required)** `string` — Practical guidance for developing this quality - **`lesson` (required)** `string` — Core lesson summary - **`number` (required)** `number` — Missing number - **`missingNumbers` (required)** `array` — Numbers missing from name (karmic lessons) **Items:** `number` - **`presentNumbers` (required)** `object` — Count of each number present in name **Example:** ```json { "missingNumbers": [ 2, 4, 8 ], "lessons": [ { "number": 2, "lesson": "Learn cooperation, patience, and sensitivity", "description": "Missing number 2 indicates challenges with teamwork and relationships...", "howToOvercome": "Practice active listening, work on group projects, develop empathy..." } ], "presentNumbers": { "1": 3, "3": 2, "5": 4, "6": 1, "7": 2, "9": 2 } } ``` ### Detect Karmic Debt numbers - Past life challenges (13, 14, 16, 19) - **Method:** `POST` - **Path:** `/numerology/karmic-debt` - **Tags:** Numerology Check for Karmic Debt numbers (13, 14, 16, 19) in Life Path, Expression, Soul Urge, or Personality calculations using Pythagorean numerology. Karmic debt indicates challenges carried from past lives that must be resolved in this lifetime. These numbers appear during reduction and represent specific lessons and tests. Returns comprehensive analysis including debt descriptions, challenges to overcome, and resolution guidance. Perfect for spiritual growth apps, karmic astrology platforms, past life exploration services, and personal transformation tools. Get detailed meanings for all four karmic debt numbers with practical resolution strategies. #### Request Body ##### Content-Type: application/json - **`day`** `integer` — Birth day (checks Life Path) - **`fullName`** `string` — Full birth name (checks Expression, Soul Urge, Personality) - **`month`** `integer` — Birth month (checks Life Path) - **`year`** `integer` — Birth year (checks Life Path) **Example:** ```json { "year": 1990, "month": 7, "day": 15, "fullName": "John William Smith" } ``` #### Responses ##### Status: 200 Successfully detected karmic debt with detailed meanings ###### Content-Type: application/json - **`debtNumbers` (required)** `array` — All karmic debt numbers found (13, 14, 16, 19) **Items:** `number` - **`hasKarmicDebt` (required)** `boolean` — Whether any karmic debt numbers were detected - **`meanings` (required)** `array` **Items:** - **`challenge` (required)** `string` — Detailed explanation of past life issue and current challenges - **`description` (required)** `string` — Debt title and nature - **`number` (required)** `number` — Karmic debt number - **`resolution` (required)** `string` — Guidance for resolving karmic debt in this lifetime **Example:** ```json { "hasKarmicDebt": true, "debtNumbers": [ 14, 16 ], "meanings": [ { "number": 14, "description": "Karmic Debt of Abuse of Freedom", "challenge": "Past life misuse of personal freedom through excess or manipulation...", "resolution": "Learn balance, moderation, and responsible use of freedom..." } ] } ``` ### Calculate Personal Year - Annual cycle and forecast for current year - **Method:** `POST` - **Path:** `/numerology/personal-year` - **Tags:** Numerology Calculate your Personal Year number from your birth month, day, and current year using Pythagorean numerology. Personal Year runs in 9-year cycles (1-9) and reveals the theme, opportunities, and challenges for the current year. Each year has a specific energy and lessons. Returns comprehensive annual forecast including year theme, opportunities, challenges, and actionable advice. Perfect for yearly planning apps, life coaching platforms, astrology services, and personal development tools. Get detailed forecasts for all 9 Personal Year cycles with practical guidance. #### Request Body ##### Content-Type: application/json - **`day` (required)** `integer` — Birth day (1-31) - **`month` (required)** `integer` — Birth month (1-12) - **`year`** `integer` — Year to calculate (defaults to current year) **Example:** ```json { "month": 7, "day": 15, "year": 2025 } ``` #### Responses ##### Status: 200 Successfully calculated Personal Year with forecast ###### Content-Type: application/json - **`advice` (required)** `string` — Practical guidance for navigating the year - **`challenges` (required)** `array` — Challenges to navigate **Items:** `string` - **`cycle` (required)** `string` — Position in the 9-year cycle - **`forecast` (required)** `string` — Detailed year forecast (200-300 words) - **`opportunities` (required)** `array` — Key opportunities in this year **Items:** `string` - **`personalYear` (required)** `number` — Personal Year number (1-9) - **`theme` (required)** `string` — Main theme of the year **Example:** ```json { "personalYear": 5, "cycle": "Year 5 of 9", "theme": "Freedom and Change", "forecast": "This is a year of freedom, change, and unexpected opportunities. You will feel restless and eager for new experiences...", "opportunities": [ "Travel and adventure", "Career changes", "New connections", "Learning" ], "challenges": [ "Restlessness", "Scattered energy", "Impulsive decisions" ], "advice": "Embrace change and new experiences but maintain some stability. Stay flexible and open-minded..." } ``` ### Calculate Compatibility - Relationship dynamics between two people - **Method:** `POST` - **Path:** `/numerology/compatibility` - **Tags:** Numerology Calculate numerology compatibility between two people using their Life Path, Expression, and Soul Urge numbers based on Pythagorean numerology. Provides comprehensive relationship analysis with overall compatibility score (0-100), individual aspect compatibility (Life Path 50% weight, Expression 30%, Soul Urge 20%), relationship strengths, challenges, and practical advice. Uses detailed compatibility matrix for all number combinations. Perfect for dating apps, relationship counseling platforms, matchmaking services, and compatibility tools. Get actionable insights for improving relationship dynamics. #### Request Body ##### Content-Type: application/json - **`person1` (required)** `object` - **`expression` (required)** `integer` — Person 1 Expression number (1-9, 11, 22, 33) - **`lifePath` (required)** `integer` — Person 1 Life Path number (1-9, 11, 22, 33) - **`soulUrge` (required)** `integer` — Person 1 Soul Urge number (1-9, 11, 22, 33) - **`person2` (required)** `object` - **`expression` (required)** `integer` — Person 2 Expression number (1-9, 11, 22, 33) - **`lifePath` (required)** `integer` — Person 2 Life Path number (1-9, 11, 22, 33) - **`soulUrge` (required)** `integer` — Person 2 Soul Urge number (1-9, 11, 22, 33) **Example:** ```json { "person1": { "lifePath": 5, "expression": 7, "soulUrge": 6 }, "person2": { "lifePath": 3, "expression": 9, "soulUrge": 2 } } ``` #### Responses ##### Status: 200 Successfully calculated compatibility with detailed analysis ###### Content-Type: application/json - **`advice` (required)** `string` — Practical relationship advice - **`challenges` (required)** `array` — Potential relationship challenges **Items:** `string` - **`expression` (required)** `object` - **`compatibility` (required)** `number` — Expression compatibility score (0-100) - **`description` (required)** `string` — Detailed Expression compatibility analysis - **`person1` (required)** `number` — Person 1 Expression number - **`person2` (required)** `number` — Person 2 Expression number - **`lifePath` (required)** `object` - **`compatibility` (required)** `number` — Life Path compatibility score (0-100) - **`description` (required)** `string` — Detailed Life Path compatibility analysis - **`person1` (required)** `number` — Person 1 Life Path number - **`person2` (required)** `number` — Person 2 Life Path number - **`overallScore` (required)** `number` — Overall compatibility score (0-100) - **`rating` (required)** `string` — Compatibility rating (Poor/Fair/Good/Excellent/Exceptional) - **`soulUrge` (required)** `object` - **`compatibility` (required)** `number` — Soul Urge compatibility score (0-100) - **`description` (required)** `string` — Detailed Soul Urge compatibility analysis - **`person1` (required)** `number` — Person 1 Soul Urge number - **`person2` (required)** `number` — Person 2 Soul Urge number - **`strengths` (required)** `array` — Key relationship strengths **Items:** `string` **Example:** ```json { "overallScore": 78, "rating": "Good", "lifePath": { "person1": 5, "person2": 3, "compatibility": 85, "description": "5 and 3 create an exciting dynamic partnership..." }, "expression": { "person1": 7, "person2": 9, "compatibility": 70, "description": "7 and 9 share spiritual depth..." }, "soulUrge": { "person1": 6, "person2": 2, "compatibility": 90, "description": "6 and 2 have complementary emotional needs..." }, "strengths": [ "Complementary personalities", "Shared values", "Mutual growth support", "Emotional harmony" ], "challenges": [ "Different communication styles", "Need for independence vs togetherness", "Pace of life differences" ], "advice": "This relationship thrives on mutual respect and space for individual growth. Focus on..." } ``` ### Generate Complete Numerology Chart - Full profile analysis - **Method:** `POST` - **Path:** `/numerology/chart` - **Tags:** Numerology Generate a comprehensive numerology chart combining all major calculations: Life Path, Expression, Soul Urge, Personality, Birth Day, Maturity, Karmic Lessons, Karmic Debt, and Personal Year. This single endpoint provides everything needed for a full numerology reading. Returns detailed interpretations for all numbers, karmic analysis, yearly forecast, and holistic summary. Perfect for numerology apps, complete reading services, birth chart generators, and comprehensive analysis tools. Save multiple API calls by getting the full chart in one request. Ideal for generating PDF reports or detailed user profiles. #### Request Body ##### Content-Type: application/json - **`day` (required)** `integer` — Birth day (1-31) - **`fullName` (required)** `string` — Full birth name - **`month` (required)** `integer` — Birth month (1-12) - **`year` (required)** `integer` — Birth year (1900-2100) - **`currentYear`** `integer` — Year for Personal Year calculation (defaults to current year) **Example:** ```json { "fullName": "John William Smith", "year": 1990, "month": 7, "day": 15, "currentYear": 2025 } ``` #### Responses ##### Status: 200 Successfully generated complete numerology chart ###### Content-Type: application/json - **`additionalInsights` (required)** `object` - **`karmicDebt` (required)** `object` - **`debtNumbers` (required)** `array` **Items:** `number` - **`hasKarmicDebt` (required)** `boolean` - **`meanings` (required)** `array` **Items:** - **`challenge` (required)** `string` - **`description` (required)** `string` - **`number` (required)** `number` - **`resolution` (required)** `string` - **`karmicLessons` (required)** `object` - **`lessons` (required)** `array` **Items:** - **`description` (required)** `string` - **`howToOvercome` (required)** `string` - **`lesson` (required)** `string` - **`number` (required)** `number` - **`missingNumbers` (required)** `array` **Items:** `number` - **`presentNumbers` (required)** `object` - **`personalYear` (required)** `object` - **`advice` (required)** `string` - **`challenges` (required)** `array` **Items:** `string` - **`cycle` (required)** `string` - **`forecast` (required)** `string` - **`opportunities` (required)** `array` **Items:** `string` - **`personalYear` (required)** `number` - **`theme` (required)** `string` - **`coreNumbers` (required)** `object` - **`birthDay` (required)** `object` - **`meaning` (required)** `object` - **`career` (required)** `string` - **`challenges` (required)** `array` **Items:** `string` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`relationships` (required)** `string` - **`spirituality` (required)** `string` - **`strengths` (required)** `array` **Items:** `string` - **`title` (required)** `string` - **`number` (required)** `number` - **`expression` (required)** `object` - **`calculation` (required)** `string` - **`hasKarmicDebt` (required)** `boolean` - **`meaning` (required)** `object` - **`career` (required)** `string` - **`challenges` (required)** `array` **Items:** `string` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`relationships` (required)** `string` - **`spirituality` (required)** `string` - **`strengths` (required)** `array` **Items:** `string` - **`title` (required)** `string` - **`number` (required)** `number` - **`type` (required)** `string`, possible values: `"single", "master"` - **`karmicDebtNumber`** `number` - **`lifePath` (required)** `object` - **`calculation` (required)** `string` - **`hasKarmicDebt` (required)** `boolean` - **`meaning` (required)** `object` - **`career` (required)** `string` - **`challenges` (required)** `array` **Items:** `string` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`relationships` (required)** `string` - **`spirituality` (required)** `string` - **`strengths` (required)** `array` **Items:** `string` - **`title` (required)** `string` - **`number` (required)** `number` - **`type` (required)** `string`, possible values: `"single", "master"` - **`karmicDebtNumber`** `number` - **`maturity` (required)** `object` - **`calculation` (required)** `string` - **`hasKarmicDebt` (required)** `boolean` - **`meaning` (required)** `object` - **`career` (required)** `string` - **`challenges` (required)** `array` **Items:** `string` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`relationships` (required)** `string` - **`spirituality` (required)** `string` - **`strengths` (required)** `array` **Items:** `string` - **`title` (required)** `string` - **`number` (required)** `number` - **`type` (required)** `string`, possible values: `"single", "master"` - **`karmicDebtNumber`** `number` - **`personality` (required)** `object` - **`calculation` (required)** `string` - **`hasKarmicDebt` (required)** `boolean` - **`meaning` (required)** `object` - **`career` (required)** `string` - **`challenges` (required)** `array` **Items:** `string` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`relationships` (required)** `string` - **`spirituality` (required)** `string` - **`strengths` (required)** `array` **Items:** `string` - **`title` (required)** `string` - **`number` (required)** `number` - **`type` (required)** `string`, possible values: `"single", "master"` - **`karmicDebtNumber`** `number` - **`soulUrge` (required)** `object` - **`calculation` (required)** `string` - **`hasKarmicDebt` (required)** `boolean` - **`meaning` (required)** `object` - **`career` (required)** `string` - **`challenges` (required)** `array` **Items:** `string` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`relationships` (required)** `string` - **`spirituality` (required)** `string` - **`strengths` (required)** `array` **Items:** `string` - **`title` (required)** `string` - **`number` (required)** `number` - **`type` (required)** `string`, possible values: `"single", "master"` - **`karmicDebtNumber`** `number` - **`profile` (required)** `object` - **`birthdate` (required)** `string` - **`name` (required)** `string` - **`summary` (required)** `string` — Holistic summary of the complete chart **Example:** ```json { "profile": { "name": "John William Smith", "birthdate": "1990-07-15" }, "coreNumbers": { "lifePath": { "number": 1, "calculation": "", "type": "single", "hasKarmicDebt": true, "karmicDebtNumber": 1, "meaning": { "title": "", "keywords": [ "" ], "description": "", "strengths": [ "" ], "challenges": [ "" ], "career": "", "relationships": "", "spirituality": "" } }, "expression": { "number": 1, "calculation": "", "type": "single", "hasKarmicDebt": true, "karmicDebtNumber": 1, "meaning": { "title": "", "keywords": [ "" ], "description": "", "strengths": [ "" ], "challenges": [ "" ], "career": "", "relationships": "", "spirituality": "" } }, "soulUrge": { "number": 1, "calculation": "", "type": "single", "hasKarmicDebt": true, "karmicDebtNumber": 1, "meaning": { "title": "", "keywords": [ "" ], "description": "", "strengths": [ "" ], "challenges": [ "" ], "career": "", "relationships": "", "spirituality": "" } }, "personality": { "number": 1, "calculation": "", "type": "single", "hasKarmicDebt": true, "karmicDebtNumber": 1, "meaning": { "title": "", "keywords": [ "" ], "description": "", "strengths": [ "" ], "challenges": [ "" ], "career": "", "relationships": "", "spirituality": "" } }, "birthDay": { "number": 1, "meaning": { "title": "", "keywords": [ "" ], "description": "", "strengths": [ "" ], "challenges": [ "" ], "career": "", "relationships": "", "spirituality": "" } }, "maturity": { "number": 1, "calculation": "", "type": "single", "hasKarmicDebt": true, "karmicDebtNumber": 1, "meaning": { "title": "", "keywords": [ "" ], "description": "", "strengths": [ "" ], "challenges": [ "" ], "career": "", "relationships": "", "spirituality": "" } } }, "additionalInsights": { "karmicLessons": { "missingNumbers": [ 1 ], "lessons": [ { "number": 1, "lesson": "", "description": "", "howToOvercome": "" } ], "presentNumbers": { "propertyName*": 1 } }, "karmicDebt": { "hasKarmicDebt": true, "debtNumbers": [ 1 ], "meanings": [ { "number": 1, "description": "", "challenge": "", "resolution": "" } ] }, "personalYear": { "personalYear": 1, "cycle": "", "theme": "", "forecast": "", "opportunities": [ "" ], "challenges": [ "" ], "advice": "" } }, "summary": "Your numerology chart reveals a Life Path 5 personality seeking freedom and adventure..." } ``` ### Get Number Meaning - Interpretation for any number 1-9, 11, 22, 33 - **Method:** `GET` - **Path:** `/numerology/meanings/{number}` - **Tags:** Numerology Get the complete meaning and interpretation for any numerology number (1-9, 11, 22, 33) using Pythagorean numerology. Returns comprehensive description including archetype title, keywords, personality traits, strengths, weaknesses, career guidance, relationship dynamics, and spiritual insights. Master numbers (11, 22, 33) include amplified meanings with their reduced base number. Perfect for numerology reference tools, educational apps, quick lookups, and building custom numerology calculators. Get detailed 300-500 word meanings from authoritative source (Hans Decoz - 50+ years experience). #### Responses ##### Status: 200 Successfully retrieved number meaning ###### Content-Type: application/json - **`meaning` (required)** `object` - **`career` (required)** `string` — Career guidance and professional strengths - **`challenges` (required)** `array` — Common challenges and growth areas **Items:** `string` - **`description` (required)** `string` — Comprehensive 300-500 word description - **`keywords` (required)** `array` — Key personality traits and qualities **Items:** `string` - **`relationships` (required)** `string` — Relationship dynamics and compatibility insights - **`spirituality` (required)** `string` — Spiritual path and higher purpose guidance - **`strengths` (required)** `array` — Core strengths and positive qualities **Items:** `string` - **`title` (required)** `string` — Archetype title - **`number` (required)** `number` — Requested number - **`type` (required)** `string`, possible values: `"single", "master"` — Number type **Example:** ```json { "number": 5, "type": "single", "meaning": { "title": "The Freedom Seeker", "keywords": [ "freedom", "adventure", "versatile", "dynamic", "curious" ], "description": "People with a 5 energy are on a lifelong adventure seeking freedom and variety...", "strengths": [ "Adaptability", "Communication", "Curiosity", "Resourcefulness" ], "challenges": [ "Restlessness", "Commitment issues", "Impulsiveness" ], "career": "Suited for careers offering variety and freedom: travel, sales, marketing, journalism...", "relationships": "Needs freedom and variety in relationships, makes exciting partner...", "spirituality": "Spiritual growth through diverse experiences and exploring different philosophies..." } } ``` ##### Status: 400 Invalid number (must be 1-9, 11, 22, or 33) ###### Content-Type: application/json - **`error` (required)** `string` **Example:** ```json { "error": "" } ``` ##### Status: 404 Number meaning not found ###### Content-Type: application/json - **`error` (required)** `string` **Example:** ```json { "error": "" } ``` ### Get API usage statistics - **Method:** `GET` - **Path:** `/usage` - **Tags:** Usage Returns current usage and plan limits for your subscription. #### Responses ##### Status: 200 Usage statistics retrieved ###### Content-Type: application/json - **`data` (required)** `object` - **`email` (required)** `string`, format: `email` - **`endDate` (required)** `string`, format: `date-time` - **`plan` (required)** `string` - **`remainingThisMonth` (required)** `number` - **`requestsPerMonth` (required)** `number` - **`status` (required)** `string` - **`usedThisMonth` (required)** `number` - **`success` (required)** `boolean`, possible values: `true` **Example:** ```json { "success": true, "data": { "plan": "Pro", "usedThisMonth": 1523, "requestsPerMonth": 10000, "remainingThisMonth": 8477, "email": "", "status": "active", "endDate": "" } } ``` ##### Status: 404 Subscription not found ###### Content-Type: application/json - **`error` (required)** `object` - **`code` (required)** `string` - **`message` (required)** `string` - **`success` (required)** `boolean`, possible values: `false` **Example:** ```json { "success": false, "error": { "code": "", "message": "" } } ``` ## Schemas ### NatalChartResponse - **Type:**`object` * **`ascendant` (required)** `object` - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` * **`aspects` (required)** `array` **Items:** - **`angle` (required)** `number` - **`interpretation` (required)** `string` - **`isApplying` (required)** `boolean` - **`orb` (required)** `number` - **`planet1` (required)** `string` - **`planet2` (required)** `string` - **`strength` (required)** `number` - **`type` (required)** `string` * **`aspectsInterpretation` (required)** `object` - **`challenging` (required)** `number` - **`dominant` (required)** `string` - **`harmonious` (required)** `number` - **`neutral` (required)** `number` - **`summary` (required)** `string` * **`birthDetails` (required)** `object` - **`date` (required)** `string` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` * **`houses` (required)** `array` **Items:** - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`number` (required)** `number` - **`sign` (required)** `string` * **`houseSystem` (required)** `string` * **`midheaven` (required)** `object` - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` * **`planets` (required)** `array` **Items:** - **`degree` (required)** `number` - **`house` (required)** `number` - **`isRetrograde` (required)** `boolean` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`name` (required)** `string` - **`sign` (required)** `string` - **`speed` (required)** `number` - **`interpretation`** `object` - **`detailed` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`summary` (required)** `string` * **`summary` (required)** `object` - **`dominantElement` (required)** `string` - **`dominantModality` (required)** `string` - **`elementDistribution` (required)** `object` - **`modalityDistribution` (required)** `object` - **`retrogradePlanets` (required)** `array` **Items:** `string` **Example:** ```json { "birthDetails": { "date": "", "time": "", "latitude": 1, "longitude": 1, "timezone": 1 }, "planets": [ { "name": "Sun", "longitude": 112.45, "latitude": 0.01, "sign": "Cancer", "degree": 22.45, "house": 7, "speed": 0.9571, "isRetrograde": false, "interpretation": { "summary": "Your Sun in Cancer in The Seventh House reveals how you express self-awareness & ego with ambitious and independent energy in the realm of partnerships", "detailed": "Sun represents self-awareness & ego. In Cancer, this energy becomes ambitious, independent, impatient...", "keywords": [ "Leader", "Bright", "Fire", "ambitious", "independent" ] } } ], "houses": [ { "number": 1, "longitude": 45.32, "sign": "Taurus", "degree": 15.32 } ], "houseSystem": "placidus", "aspects": [ { "planet1": "Sun", "planet2": "Moon", "type": "TRINE", "angle": 120, "orb": 2.5, "isApplying": true, "strength": 75, "interpretation": "harmonious" } ], "aspectsInterpretation": { "summary": "Your chart contains 15 aspects: 8 harmonious, 5 challenging, and 2 neutral. This creates a harmonious overall pattern.", "dominant": "harmonious", "harmonious": 8, "challenging": 5, "neutral": 2 }, "ascendant": { "sign": "Taurus", "degree": 15.32, "longitude": 45.32 }, "midheaven": { "sign": "Aquarius", "degree": 8.76, "longitude": 308.76 }, "summary": { "dominantElement": "Water", "dominantModality": "Cardinal", "retrogradePlanets": [ "Mercury", "Saturn" ], "elementDistribution": { "Fire": 2, "Earth": 3, "Air": 1, "Water": 4 }, "modalityDistribution": { "Cardinal": 4, "Fixed": 3, "Mutable": 3 } } } ``` ### NatalChartRequest - **Type:**`object` * **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. This is the exact calendar date when the person was born, used to calculate planetary positions for that specific day. Format must be YYYY-MM-DD (e.g., 1990-07-15 for July 15, 1990). * **`latitude` (required)** `number` — Birth location latitude in decimal degrees (-90 to 90). Positive values are North, negative are South. This affects house cusps and local horizon calculations. Example: 40.7128 for New York City. Use geocoding APIs or location services to convert addresses to coordinates. * **`longitude` (required)** `number` — Birth location longitude in decimal degrees (-180 to 180). Positive values are East, negative are West. This affects house cusps and local time. Example: -74.006 for New York City. Use geocoding APIs to convert addresses to coordinates. * **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. This precise time determines the Ascendant (rising sign) and house cusps. Even small time differences (minutes) can change house placements. Use 12:00:00 if birth time is unknown (solar chart). Format: HH:MM:SS (e.g., 14:30:00 for 2:30 PM). * **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for Western Hemisphere (west of UTC), positive for Eastern Hemisphere (east of UTC). Examples: New York EST = -5, Los Angeles PST = -8, London GMT = 0, Paris CET = 1, India IST = 5.5 (NOT 5:30), Tokyo JST = 9. IMPORTANT: Use decimal format for half-hour zones (India = 5.5, not 5:30). This converts LOCAL birth time to UTC for astronomical calculations (e.g., 14:30 with timezone 5.5 → 09:00 UTC). Calculations are timezone-independent - server timezone does NOT affect results. * **`houseSystem`** `string`, possible values: `"placidus", "whole-sign", "equal", "koch"`, default: `"placidus"` — House system for dividing the chart into 12 houses. Placidus (default) is most popular in Western astrology and time-sensitive. Whole Sign assigns one sign per house (simpler, ancient). Equal houses divide chart into 30° segments from Ascendant. Koch emphasizes houses in high latitudes. Choose based on astrological tradition or user preference. **Example:** ```json { "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5, "houseSystem": "placidus" } ``` ### HousesResponse - **Type:**`object` * **`data` (required)** `object` - **`ascendant` (required)** `object` - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`date` (required)** `string` - **`houses` (required)** `array` **Items:** - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`number` (required)** `number` - **`sign` (required)** `string` - **`houseSystem` (required)** `string` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`midheaven` (required)** `object` - **`degree` (required)** `number` - **`longitude` (required)** `number` - **`sign` (required)** `string` - **`time` (required)** `string` - **`timezone` (required)** `number` - **`comparison`** `object` — House cusp comparison across all systems (only when houseSystem="all") * **`success` (required)** `boolean`, possible values: `true` **Example:** ```json { "success": true, "data": { "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5, "houseSystem": "placidus", "ascendant": { "sign": "Taurus", "degree": 15.32, "longitude": 45.32 }, "midheaven": { "sign": "Aquarius", "degree": 8.76, "longitude": 308.76 }, "houses": [ { "number": 1, "longitude": 45.32, "sign": "Taurus", "degree": 15.32 } ], "comparison": { "propertyName*": { "houses": [ { "number": 1, "longitude": 1, "sign": "", "degree": 1 } ] } } } } ``` ### AspectsResponse - **Type:**`object` * **`aspects` (required)** `array` **Items:** - **`angle` (required)** `number` - **`interpretation` (required)** `string` - **`isApplying` (required)** `boolean` - **`orb` (required)** `number` - **`planet1` (required)** `string` - **`planet2` (required)** `string` - **`strength` (required)** `number` - **`type` (required)** `string` - **`meaning`** `object` - **`description` (required)** `object` - **`long` (required)** `string` - **`short` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`name` (required)** `string` - **`nature` (required)** `string` * **`aspectsFound` (required)** `number` * **`date` (required)** `string` * **`summary` (required)** `object` - **`byType` (required)** `object` - **`challenging` (required)** `number` - **`harmonious` (required)** `number` - **`neutral` (required)** `number` - **`totalAspects` (required)** `number` * **`time` (required)** `string` * **`timezone` (required)** `number` **Example:** ```json { "date": "1990-07-15", "time": "14:30:00", "timezone": -5, "aspectsFound": 12, "aspects": [ { "planet1": "Sun", "planet2": "Moon", "type": "TRINE", "angle": 120, "orb": 2.5, "isApplying": true, "strength": 75, "interpretation": "harmonious", "meaning": { "name": "", "description": { "short": "", "long": "" }, "keywords": [ "" ], "nature": "" } } ], "summary": { "totalAspects": 12, "harmonious": 7, "challenging": 4, "neutral": 1, "byType": { "CONJUNCTION": 2, "TRINE": 3, "SQUARE": 2, "SEXTILE": 2, "OPPOSITION": 1 } } } ``` ### AspectsRequest - **Type:**`object` * **`date` (required)** `string`, format: `date` — Date in YYYY-MM-DD format * **`time` (required)** `string` — Time in HH:MM:SS format (24-hour) * **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Examples: New York EST = -5, India IST = 5.5 (NOT 5:30), Tokyo JST = 9. IMPORTANT: Use decimal format (5.5, not 5:30). * **`aspectTypes`** `array` — Optional: specific aspect types to find (defaults to all 9) **Items:** `string` * **`planets`** `array` — Optional: specific planets to calculate aspects for (defaults to all 10) **Items:** `string` **Example:** ```json { "date": "1990-07-15", "time": "14:30:00", "timezone": -5, "planets": [ "Sun", "Moon", "Mercury", "Venus", "Mars" ], "aspectTypes": [ "CONJUNCTION", "OPPOSITION", "TRINE", "SQUARE" ] } ``` ### TransitsResponse - **Type:**`object` * **`timezone` (required)** `number` * **`transitDate` (required)** `string` * **`transitPlanets` (required)** `array` **Items:** - **`degree` (required)** `number` - **`isRetrograde` (required)** `boolean` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`name` (required)** `string` - **`sign` (required)** `string` - **`speed` (required)** `number` * **`transitTime` (required)** `string` * **`summary`** `object` — Transit aspect summary (only when natalChart provided) - **`challenging` (required)** `number` - **`harmonious` (required)** `number` - **`neutral` (required)** `number` - **`totalAspects` (required)** `number` * **`transitAspects`** `array` — Transit-to-natal aspects (only when natalChart provided) **Items:** - **`angle` (required)** `number` - **`interpretation` (required)** `string` - **`isApplying` (required)** `boolean` - **`natalPlanet` (required)** `string` - **`orb` (required)** `number` - **`strength` (required)** `number` - **`transitPlanet` (required)** `string` - **`type` (required)** `string` **Example:** ```json { "transitDate": "2025-12-19", "transitTime": "12:00:00", "timezone": 0, "transitPlanets": [ { "name": "Sun", "longitude": 267.45, "latitude": 0.01, "sign": "Sagittarius", "degree": 27.45, "speed": 0.9571, "isRetrograde": false } ], "transitAspects": [ { "transitPlanet": "Sun", "natalPlanet": "Mars", "type": "CONJUNCTION", "angle": 0, "orb": 1.2, "isApplying": true, "strength": 88, "interpretation": "challenging" } ], "summary": { "totalAspects": 8, "harmonious": 4, "challenging": 3, "neutral": 1 } } ``` ### TransitsRequest - **Type:**`object` * **`date`** `string`, format: `date` — Transit date in YYYY-MM-DD format (defaults to current date) * **`natalChart`** `object` — Optional natal chart data to compare transits against - **`date` (required)** `string`, format: `date` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` * **`time`** `string` — Transit time in HH:MM:SS format (defaults to current time) * **`timezone`** `number`, default: `0` — Timezone offset from UTC in hours (defaults to 0 = UTC) **Example:** ```json { "date": "2025-12-19", "time": "12:00:00", "timezone": 0, "natalChart": { "date": "1990-07-15", "time": "14:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5 } } ``` ### BirthChartResponse - **Type:**`object` * **`aries` (required)** `object` - **`rashi` (required)** `string` - **`signs` (required)** `array` **Items:** - **`graha` (required)** `string` - **`isRetrograde` (required)** `boolean` - **`longitude` (required)** `number` - **`nakshatra` (required)** `object` - **`key` (required)** `number` - **`name` (required)** `string` - **`pada` (required)** `number` * **`meta` (required)** `object` **Example:** ```json { "aries": { "rashi": "aries", "signs": [] }, "meta": { "Sun": { "graha": "Sun", "rashi": "Leo", "longitude": 132.45, "nakshatra": { "name": "Magha", "pada": 2, "key": 9 }, "isRetrograde": false }, "Moon": { "graha": "Moon", "rashi": "Cancer", "longitude": 98.32, "nakshatra": { "name": "Punarvasu", "pada": 4, "key": 6 }, "isRetrograde": false } } } ``` ### BirthChartRequest - **Type:**`object` * **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). * **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. * **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. * **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. * **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` ### NavamsaResponse - **Type:**`object` * **`vargottama` (required)** `array` — Planets that are Vargottama (same sign in D1 and D9) **Items:** `string` * **`vargottamaExplanation` (required)** `string` — Explanation of Vargottama significance * **`chart`** `object` — Navamsa chart with same structure as birth chart **Example:** ```json { "chart": null, "vargottama": [ "Sun", "Moon" ], "vargottamaExplanation": "Vargottama planets occupy the same zodiac sign in both D1 (birth chart) and D9 (Navamsa chart), indicating exceptional strength and purity. These planets deliver their full results with minimal affliction, bringing stability and success in their significations. Vargottama is considered highly auspicious, especially for benefics like Jupiter and Venus, as it doubles the positive effects in marriage, spirituality, and overall life prosperity." } ``` ### NavamsaRequest - **Type:**`object` * **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). * **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. * **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. * **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. * **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` ### CompatibilityResponse - **Type:**`object` * **`breakdown` (required)** `array` — Detailed breakdown of compatibility scores across 8 categories: Nakshatra (4), Gana (6), Yoni (4), Rashi Lord (5), Vasya (2), Tara (3), Nadi (8), Bhakoot (7) **Items:** - **`category` (required)** `string` - **`description` (required)** `string` - **`score` (required)** `number` * **`isCompatible` (required)** `boolean` — Compatible if >= 50% * **`maxScore` (required)** `number` — Maximum possible score * **`percentage` (required)** `number` — Compatibility percentage * **`total` (required)** `number` — Total compatibility score **Example:** ```json { "total": 24.5, "maxScore": 36, "percentage": 68.1, "isCompatible": true, "breakdown": [ { "category": "Nakshatra", "score": 4, "description": "Excellent nakshatra match" }, { "category": "Gana", "score": 6, "description": "Perfect temperament match" }, { "category": "Yoni", "score": 2, "description": "Moderate nature compatibility" } ] } ``` ### CompatibilityRequest - **Type:**`object` * **`person1` (required)** `object` — First person birth data - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). - **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. * **`person2` (required)** `object` — Second person birth data - **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). - **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. - **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. - **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. - **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. **Example:** ```json { "person1": { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 }, "person2": { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } } ``` ### PlanetaryPositionsResponse - **Type:**`object` **Example:** ```json { "Sun": { "graha": "Sun", "rashi": "Leo", "longitude": 132.45, "nakshatra": { "name": "Magha", "pada": 2, "key": 9, "deity": "Pitris (Ancestors)", "symbol": "Royal Throne", "characteristics": "Leadership, ancestral pride, regal nature" }, "rashiDetails": { "vedicName": "Simha", "symbol": "Lion", "energy": "Masculine, Fire", "characteristics": "Natural leadership, confidence, creativity" }, "isRetrograde": false }, "Moon": { "graha": "Moon", "rashi": "Cancer", "longitude": 98.32, "nakshatra": { "name": "Punarvasu", "pada": 4, "key": 6, "deity": "Aditi", "symbol": "Bow and Quiver", "characteristics": "Renewal, optimism, spiritual growth" }, "rashiDetails": { "vedicName": "Karka", "symbol": "Crab", "energy": "Feminine, Water", "characteristics": "Nurturing, emotional depth, protective" }, "isRetrograde": false } } ``` ### PlanetaryPositionsRequest - **Type:**`object` * **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format. Date determines planetary positions and nakshatra calculations for Vedic kundli (janam patri). Accurate birth date is essential for dashas, yoga calculations, and divisional charts (vargas). * **`latitude` (required)** `number` — Birth location latitude in decimal degrees. Location determines local sidereal time for Lagna calculation and affects bhava (house) cusps. Example: Delhi 28.6139, Mumbai 19.0760, Kathmandu 27.7172. * **`longitude` (required)** `number` — Birth location longitude in decimal degrees. Affects local time calculations and ayanamsha adjustments. Example: Delhi 77.2090, Mumbai 72.8777, Kathmandu 85.3240. * **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. Time is CRITICAL for Lagna (Ascendant) calculation and house divisions - changes every \~2 hours. Even minutes matter for accurate nakshatra pada and divisional chart (D9, D10) calculations. Without exact time, Lagna and house-based predictions will be incorrect. * **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (NOT minutes format). Negative for west of UTC, positive for east. Examples: India IST = 5.5 (NOT 5:30), Nepal NPT = 5.75 (NOT 5:45), New York EST = -5. IMPORTANT: Use decimal format (5.5, not 5:30). Server timezone does NOT affect results - calculations are timezone-independent. **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` ### ManglikResponse - **Type:**`object` * **`description` (required)** `string` — Detailed description of the dosha * **`present` (required)** `boolean` — Whether the dosha is present * **`exceptions`** `array` — Exceptions or cancellations that reduce severity **Items:** `string` * **`severity`** `string`, possible values: `"Mild", "Moderate", "Severe"` — Severity level of the dosha * **`type`** `string` — Type or phase of the dosha **Example:** ```json { "present": true, "severity": "Moderate", "type": "Ananta Kalsarpa", "description": "Manglik Dosha present. Mars in house 7 creates matrimonial afflictions.", "exceptions": [ "Mars in own sign (reduces severity)" ] } ``` ### ManglikRequest - **Type:**`object` * **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format * **`latitude` (required)** `number` — Birth location latitude * **`longitude` (required)** `number` — Birth location longitude * **`time` (required)** `string` — Birth time in HH:MM:SS format (24-hour) * **`timezone` (required)** `number` — Timezone offset from UTC in hours (e.g., 5.5 for IST) **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` ### KalsarpaResponse - **Type:**`object` * **`description` (required)** `string` — Detailed description of the dosha * **`present` (required)** `boolean` — Whether the dosha is present * **`exceptions`** `array` — Exceptions or cancellations that reduce severity **Items:** `string` * **`severity`** `string`, possible values: `"Mild", "Moderate", "Severe"` — Severity level of the dosha * **`type`** `string` — Type or phase of the dosha **Example:** ```json { "present": true, "severity": "Moderate", "type": "Ananta Kalsarpa", "description": "Manglik Dosha present. Mars in house 7 creates matrimonial afflictions.", "exceptions": [ "Mars in own sign (reduces severity)" ] } ``` ### KalsarpaRequest - **Type:**`object` * **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format * **`latitude` (required)** `number` — Birth location latitude * **`longitude` (required)** `number` — Birth location longitude * **`time` (required)** `string` — Birth time in HH:MM:SS format (24-hour) * **`timezone` (required)** `number` — Timezone offset from UTC in hours (e.g., 5.5 for IST) **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` ### SadhesatiResponse - **Type:**`object` * **`description` (required)** `string` — Detailed description of the dosha * **`present` (required)** `boolean` — Whether the dosha is present * **`exceptions`** `array` — Exceptions or cancellations that reduce severity **Items:** `string` * **`severity`** `string`, possible values: `"Mild", "Moderate", "Severe"` — Severity level of the dosha * **`type`** `string` — Type or phase of the dosha **Example:** ```json { "present": true, "severity": "Moderate", "type": "Ananta Kalsarpa", "description": "Manglik Dosha present. Mars in house 7 creates matrimonial afflictions.", "exceptions": [ "Mars in own sign (reduces severity)" ] } ``` ### SadhesatiRequest - **Type:**`object` * **`date` (required)** `string`, format: `date` — Birth date in YYYY-MM-DD format * **`latitude` (required)** `number` — Birth location latitude * **`longitude` (required)** `number` — Birth location longitude * **`time` (required)** `string` — Birth time in HH:MM:SS format (24-hour) * **`timezone` (required)** `number` — Timezone offset from UTC in hours (e.g., 5.5 for IST) **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5 } ``` ### KPAyanamsaResponse - **Type:**`object` * **`ayanamsa` (required)** `number` — KP-Newcomb ayanamsa value in degrees * **`calculated` (required)** `string` — UTC timestamp when calculation was performed * **`date` (required)** `string` — Date for which ayanamsa was calculated * **`formula` (required)** `string` — Mathematical basis for ayanamsa calculation * **`type` (required)** `string` — Ayanamsa type identifier **Example:** ```json { "date": "2025-12-26", "ayanamsa": 24.22233926, "type": "kp-newcomb", "formula": "Newcomb precession theory", "calculated": "2025-12-26T10:30:00Z" } ``` ### KPPlanetsResponse - **Type:**`object` * **`ayanamsa` (required)** `number` — Applied ayanamsa value in degrees * **`planets` (required)** `array` **Items:** - **`kpNumber` (required)** `number` — KP horary number (1-249) - **`longitude` (required)** `number` — Sidereal ecliptic longitude (0-360°) - **`nakshatra` (required)** `string` — Nakshatra (lunar mansion) - **`nakshatraLord` (required)** `string` — Nakshatra ruling planet - **`nakshatraNumber` (required)** `number` — Nakshatra number (1-27) - **`pada` (required)** `number` — Nakshatra pada/quarter (1-4) - **`planet` (required)** `string` — Planet name - **`retrograde` (required)** `boolean` — Whether planet is in retrograde motion - **`sign` (required)** `string` — Zodiac sign - **`signLord` (required)** `string` — Ruling planet of the sign - **`starLord` (required)** `string` — Star-lord (same as nakshatra lord in KP system) - **`subLord` (required)** `string` — Sub-lord based on 249-level KP subdivision **Example:** ```json { "ayanamsa": 24.22233926, "planets": [ { "planet": "Sun", "longitude": 108.23, "sign": "Cancer", "signLord": "Moon", "nakshatra": "Pushya", "nakshatraNumber": 8, "nakshatraLord": "Saturn", "pada": 2, "starLord": "Saturn", "subLord": "Mercury", "kpNumber": 45, "retrograde": false } ] } ``` ### KPPlanetsRequest - **Type:**`object` * **`ayanamsa` (required)** `string`, possible values: `"kp-newcomb", "custom"` — Ayanamsa type: "kp-newcomb" for dynamic calculation or "custom" to provide your own value * **`date` (required)** `string` — Birth date in YYYY-MM-DD format * **`latitude` (required)** `number` — Birth location latitude in decimal degrees * **`longitude` (required)** `number` — Birth location longitude in decimal degrees * **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format * **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours * **`ayanamsaValue`** `number` — Custom ayanamsa value in degrees (required if ayanamsa="custom") **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5, "ayanamsa": "kp-newcomb", "ayanamsaValue": 24 } ``` ### KPCuspsResponse - **Type:**`object` * **`ayanamsa` (required)** `number` — Applied ayanamsa value in degrees * **`cusps` (required)** `array` **Items:** - **`house` (required)** `number` — House number (1-12) - **`kpNumber` (required)** `number` — KP horary number (1-249) - **`longitude` (required)** `number` — Cusp longitude in degrees (0-360) - **`nakshatra` (required)** `string` — Nakshatra at cusp position - **`nakshatraLord` (required)** `string` — Nakshatra ruling planet - **`pada` (required)** `number` — Nakshatra pada/quarter (1-4) - **`sign` (required)** `string` — Zodiac sign of the cusp - **`signLord` (required)** `string` — Ruling planet of the sign - **`starLord` (required)** `string` — Star-lord (nakshatra lord) - **`subLord` (required)** `string` — Sub-lord based on KP 249-level subdivision * **`houseSystem` (required)** `string` — House system used for calculations **Example:** ```json { "ayanamsa": 24, "houseSystem": "placidus", "cusps": [ { "house": 1, "longitude": 89.45, "sign": "Cancer", "signLord": "Moon", "nakshatra": "Ashlesha", "nakshatraLord": "Mercury", "pada": 3, "starLord": "Mercury", "subLord": "Venus", "kpNumber": 32 } ] } ``` ### KPCuspsRequest - **Type:**`object` * **`ayanamsa` (required)** `string`, possible values: `"kp-newcomb", "custom"` — Ayanamsa type: "kp-newcomb" for dynamic calculation or "custom" for custom value * **`date` (required)** `string` — Birth date in YYYY-MM-DD format * **`latitude` (required)** `number` — Birth location latitude in decimal degrees * **`longitude` (required)** `number` — Birth location longitude in decimal degrees * **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format * **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours * **`ayanamsaValue`** `number` — Custom ayanamsa value in degrees (required if ayanamsa="custom") **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5, "ayanamsa": "kp-newcomb", "ayanamsaValue": 24 } ``` ### KPChartResponse - **Type:**`object` * **`ascendant` (required)** `object` - **`kpNumber` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`nakshatraLord` (required)** `string` - **`pada` (required)** `number` - **`sign` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` * **`cusps` (required)** `array` **Items:** - **`house` (required)** `number` - **`kpNumber` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`nakshatraLord` (required)** `string` - **`pada` (required)** `number` - **`sign` (required)** `string` - **`signLord` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` * **`meta` (required)** `object` - **`ayanamsa` (required)** `number` - **`ayanamsaType` (required)** `string` - **`date` (required)** `string` - **`houseSystem` (required)** `string` - **`latitude` (required)** `number` - **`longitude` (required)** `number` - **`time` (required)** `string` - **`timezone` (required)** `number` * **`nodes` (required)** `object` - **`ketu` (required)** `object` - **`house` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`sign` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` - **`rahu` (required)** `object` - **`house` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`sign` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` * **`planets` (required)** `array` **Items:** - **`house` (required)** `number` - **`kpNumber` (required)** `number` - **`longitude` (required)** `number` - **`nakshatra` (required)** `string` - **`nakshatraLord` (required)** `string` - **`pada` (required)** `number` - **`planet` (required)** `string` - **`retrograde` (required)** `boolean` - **`sign` (required)** `string` - **`starLord` (required)** `string` - **`subLord` (required)** `string` **Example:** ```json { "meta": { "date": "", "time": "", "latitude": 1, "longitude": 1, "timezone": 1, "ayanamsa": 1, "ayanamsaType": "", "houseSystem": "" }, "ascendant": { "longitude": 1, "sign": "", "nakshatra": "", "nakshatraLord": "", "pada": 1, "starLord": "", "subLord": "", "kpNumber": 1 }, "cusps": [ { "house": 1, "longitude": 1, "sign": "", "signLord": "", "nakshatra": "", "nakshatraLord": "", "pada": 1, "starLord": "", "subLord": "", "kpNumber": 1 } ], "planets": [ { "planet": "", "longitude": 1, "sign": "", "house": 1, "nakshatra": "", "nakshatraLord": "", "pada": 1, "starLord": "", "subLord": "", "kpNumber": 1, "retrograde": true } ], "nodes": { "rahu": { "longitude": 1, "sign": "", "house": 1, "nakshatra": "", "starLord": "", "subLord": "" }, "ketu": { "longitude": 1, "sign": "", "house": 1, "nakshatra": "", "starLord": "", "subLord": "" } } } ``` ### KPChartRequest - **Type:**`object` * **`ayanamsa` (required)** `string`, possible values: `"kp-newcomb", "custom"` — Ayanamsa type: "kp-newcomb" for dynamic KP-Newcomb calculation or "custom" for custom value * **`date` (required)** `string` — Birth date in YYYY-MM-DD format * **`latitude` (required)** `number` — Birth location latitude in decimal degrees * **`longitude` (required)** `number` — Birth location longitude in decimal degrees * **`time` (required)** `string` — Birth time in 24-hour HH:MM:SS format. CRITICAL for accurate Lagna and house calculations. * **`timezone` (required)** `number` — Timezone offset from UTC in decimal hours (e.g., India IST = 5.5) * **`ayanamsaValue`** `number` — Custom ayanamsa value in degrees (required if ayanamsa="custom") **Example:** ```json { "date": "1990-07-04", "time": "10:12:00", "latitude": 28.6139, "longitude": 77.209, "timezone": 5.5, "ayanamsa": "kp-newcomb", "ayanamsaValue": 24 } ``` ### BasicCard - **Type:**`object` * **`arcana` (required)** `string`, possible values: `"major", "minor"` * **`id` (required)** `string` * **`imageUrl` (required)** `string` * **`name` (required)** `string` * **`number` (required)** `number` * **`suit`** `string`, possible values: `"cups", "wands", "swords", "pentacles"` **Example:** ```json { "id": "fool", "name": "The Fool", "arcana": "major", "suit": "cups", "number": 0, "imageUrl": "https://roxyapi.com/img/tarot/major/fool.jpg" } ``` ### Card - **Type:**`object` * **`arcana` (required)** `string`, possible values: `"major", "minor"` * **`id` (required)** `string` * **`imageUrl` (required)** `string` * **`keywords` (required)** `object` - **`reversed` (required)** `array` **Items:** `string` - **`upright` (required)** `array` **Items:** `string` * **`name` (required)** `string` * **`number` (required)** `number` * **`reversed` (required)** `object` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`career`** `string` - **`finances`** `string` - **`health`** `string` - **`love`** `string` - **`spirituality`** `string` * **`upright` (required)** `object` - **`description` (required)** `string` - **`keywords` (required)** `array` **Items:** `string` - **`career`** `string` - **`finances`** `string` - **`health`** `string` - **`love`** `string` - **`spirituality`** `string` * **`suit`** `string`, possible values: `"cups", "wands", "swords", "pentacles"` **Example:** ```json { "id": "fool", "name": "The Fool", "arcana": "major", "suit": "cups", "number": 0, "keywords": { "upright": [ "beginnings", "innocence", "spontaneity" ], "reversed": [ "recklessness", "fearlessness" ] }, "upright": { "keywords": [ "" ], "description": "", "love": "", "career": "", "finances": "", "health": "", "spirituality": "" }, "reversed": { "keywords": [ "" ], "description": "", "love": "", "career": "", "finances": "", "health": "", "spirituality": "" }, "imageUrl": "https://roxyapi.com/img/tarot/major/fool.jpg" } ``` ### DrawnCard - **Type:**`object` * **`arcana` (required)** `string`, possible values: `"major", "minor"` * **`id` (required)** `string` * **`imageUrl` (required)** `string` * **`keywords` (required)** `array` **Items:** `string` * **`meaning` (required)** `string` * **`name` (required)** `string` * **`position` (required)** `number` * **`reversed` (required)** `boolean` * **`number`** `number` * **`suit`** `string`, possible values: `"cups", "wands", "swords", "pentacles"` **Example:** ```json { "id": "", "name": "", "arcana": "major", "suit": "cups", "number": 1, "position": 1, "reversed": true, "keywords": [ "" ], "meaning": "", "imageUrl": "" } ```