# Western Astrology API > Production-ready Western astrology API + remote MCP for AI agents and developers. Hosted MCP server, no local setup, connect Claude Code, Cursor, VS Code, Windsurf in seconds. Natal birth charts, publisher-grade daily/weekly/monthly horoscopes with unique content per sign (house-based transit system, active transits, Moon sign, Moon phase, energy rating), synastry compatibility scores, composite charts, solar and lunar returns, real-time transit aspects, and moon phases. 4 house systems (Placidus, Koch, Whole Sign, Equal) with accurate tropical ephemeris. 23+ endpoints optimized for horoscope platforms, astrology dating apps, AI chatbots, wellness products, and zodiac content engines. Schedule future horoscopes with date parameter for editorial workflows. No astronomy expertise needed. Ship your astrology app this weekend. Not this quarter. - Product page: https://roxyapi.com/products/astrology-api - OpenAPI spec: https://roxyapi.com/api/v2/astrology/openapi.json - Remote MCP server: https://roxyapi.com/mcp/astrology - Authentication: `X-API-Key` header on every request - Pricing: https://roxyapi.com/pricing (all domains included in every plan) ## Stats - latency: <50ms - uptime: 99.9% - endpoints: 23+ ## Features - Natal birth charts with 4 house systems (Placidus, Koch, Whole Sign, Equal) covering all 14 celestial bodies (the 10 classical planets, the lunar nodes, Chiron, and Black Moon Lilith), the Ascendant, Midheaven, Part of Fortune, and Vertex, all major aspects, planetary dignities, and element/modality analysis - Synastry compatibility and composite charts with relationship scoring, aspect patterns, Venus-Mars connections, and partnership dynamics - Publisher-grade daily, weekly, and monthly horoscopes with unique content per sign via whole-sign house system. Love, career, health, finance, advice sections, active transits, Moon data, energy rating, and date scheduling for editorial workflows - Solar returns, lunar returns, and planetary return charts for annual and monthly forecasting with customizable house systems - Detect classical aspect configurations including Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, and Stellium with apex identification, element and modality coherence, dissociate flagging, and tightness scoring for chart pattern callouts - Real-time transit calculations and transit aspect analysis with current planetary positions, applying/separating aspects, and personalized forecasts - Moon phase tracking with current phase, upcoming phases calendar, and lunar cycle data for wellness, gardening, and ritual timing apps - Multi-language responses in 8 languages (EN, TR, DE, ES, HI, PT, FR, RU) via ?lang= query parameter ## Use Cases - Launch natal chart apps with professional-grade accuracy: birth charts, planet positions, house placements, aspects, and element analysis ready for your UI in days - Add zodiac compatibility scoring to dating apps: synastry analysis, composite charts, and compatibility scores with detailed relationship dynamics - Ship personalized horoscope platforms: publisher-grade daily, weekly, and monthly forecasts with unique content per sign, active transit metadata, Moon phase data, and date scheduling for editorial pre-publishing - Build AI astrology chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers and calls all 23+ astrology endpoints with zero integration code - Power wellness and lifestyle apps with real-time transits, moon phase calendars, solar returns, and planetary movement alerts for self-discovery features - Create astrology content engines: automated zodiac content with house-based uniqueness per sign, horoscope newsletters with real lunar event dates, transit alerts, and seasonal forecasts at scale ## Endpoints - `GET /api/v2/astrology/signs` Get all zodiac signs - Complete zodiac signs list with dates and elements - `GET /api/v2/astrology/signs/{id}` Get zodiac sign details - Complete astrology sign profile with personality traits - `GET /api/v2/astrology/planet-meanings` Get all planet meanings - Complete astrology planet interpretations list - `GET /api/v2/astrology/planet-meanings/{id}` Get planet meaning details - Complete astrology planet interpretation - `POST /api/v2/astrology/natal-chart` Generate natal chart - Birth chart calculator API with houses and aspects - `POST /api/v2/astrology/planets` Get planetary positions - Ephemeris calculator for all planets - `GET /api/v2/astrology/moon-phase/current` Get current moon phase - Lunar phase calculator with zodiac sign - `GET /api/v2/astrology/moon-phase/upcoming` Get upcoming moon phases - Next new moon, full moon, quarters - `GET /api/v2/astrology/moon-phase/calendar/{year}/{month}` Get lunar calendar - Moon phases for entire month - `POST /api/v2/astrology/synastry` Calculate synastry - Relationship compatibility analysis API - `POST /api/v2/astrology/houses` Calculate house cusps - House system calculator with comparison - `POST /api/v2/astrology/aspects` Calculate planetary aspects - Aspect finder for any date and time - `POST /api/v2/astrology/aspect-patterns` Detect aspect patterns - Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium - `POST /api/v2/astrology/transits` Calculate planetary transits - Current transits with natal chart comparison - `POST /api/v2/astrology/transit-aspects` Transit Aspects - Detailed transit-to-natal aspect analysis with interpretations - `POST /api/v2/astrology/solar-return` Solar Return Chart - Annual birthday forecast with relocated chart - `POST /api/v2/astrology/lunar-return` Lunar Return Chart - Monthly emotional forecast with Moon cycle chart - `POST /api/v2/astrology/composite-chart` Composite Chart - Midpoint relationship chart with interpretations - `POST /api/v2/astrology/compatibility-score` Compatibility Score. Relationship compatibility analysis with category breakdown - `GET /api/v2/astrology/horoscope/{sign}/daily` Daily horoscope by zodiac sign - Transit-based forecast with house activations - `GET /api/v2/astrology/horoscope/{sign}/weekly` Weekly horoscope by zodiac sign - 7-day transit forecast - `GET /api/v2/astrology/horoscope/{sign}/monthly` Monthly horoscope by zodiac sign - 30-day transit forecast with key dates - `POST /api/v2/astrology/planetary-returns` Planetary Return Chart - Saturn return, Jupiter return, and inner planet cycles ### Western Astrology (`/astrology/`) - `POST /astrology/natal-chart` — Western birth chart with planets, houses, aspects, ascendant, midheaven. - `GET /astrology/horoscope/{sign}/daily` — Daily horoscope. Also `/weekly` and `/monthly` variants. - `POST /astrology/synastry` — Inter-chart aspect analysis between two people. - `POST /astrology/compatibility-score` — Percent plus category breakdowns and archetype. - `POST /astrology/transits` — Current sky. Pass optional `natalChart` for personalized aspects. - `GET /astrology/moon-phase/current` — Current moon phase, illumination, sign. ## Example Response ``` POST /api/v2/astrology/natal-chart ``` ```json { "birthDetails": { "date": "1990-07-15", "time": "13:30:00", "latitude": 40.7128, "longitude": -74.006, "timezone": -5 }, "planets": [ { "name": "Sun", "longitude": 113.01012297464763, "latitude": -0.000023757319263795868, "sign": "Cancer", "degree": 23.01012297464763, "speed": 0.9541023962147364, "isRetrograde": false, "house": 9, "interpretation": { "summary": "Your Sun in Cancer in The Ninth House reveals how you express self-awareness and ego with intuitive and nurturing energy in the realm of exploration.", "detailed": "Sun represents self-awareness and ego. In Cancer (Crab), this energy becomes intuitive, nurturing, protective. Located in The Ninth House, you direct this Cancer Sun energy toward exploration and religious beliefs and personal philosophy. This creates a unique expression where your self-awareness and ego naturally manifests through intuitive, nurturing, protective approaches in matters related to the ninth house.", "keywords": [ "active", "awareness", "bright", "confidence", "consciousness", "intuitive", "nurturing", "protective" ] } }, { "name": "Moon", "longitude": 27.069104206098757, "latitude": 5.181836887962161, "sign": "Aries", "degree": 27.069104206098757, "speed": 14.229731173744796, "isRetrograde": false, "house": 6, "interpretation": { "summary": "Your Moon in Aries in The Sixth House reveals how you express inner emotional life with ambitious and independent energy in the realm of work and job.", "detailed": "Moon represents inner emotional life. In Aries (Ram), this energy becomes ambitious, independent, impatient. Located in The Sixth House, you direct this Aries Moon energy toward work and job and techniques and methods. This creates a unique expression where your inner emotional life naturally manifests through ambitious, independent, impatient approaches in matters related to the sixth house.", "keywords": [ "caretaker", "comfort", "emotion", "feeling", "femininity", "ambitious", "independent", "impatient" ] } } ], "houses": [ { "number": 1, "longitude": 216.94758165419276, "sign": "Scorpio", "degree": 6.9475816541927315 }, { "number": 2, "longitude": 245.70493298442574, "sign": "Sagittarius", "degree": 5.704932984425795 }, { "number": 3, "longitude": 278.86478584928255, "sign": "Capricorn", "degree": 8.864785849282498 }, { "number": 4, "longitude": 314.37573350548865, "sign": "Aquarius", "degree": 14.375733505488597 } ], "houseSystem": "placidus", "aspects": [ { "planet1": "North Node", "planet2": "South Node", "type": "OPPOSITION", "angle": 180, "orb": 0, "isApplying": false, "strength": 100, "interpretation": "challenging" }, { "planet1": "Sun", "planet2": "Jupiter", "type": "CONJUNCTION", "angle": 0, "orb": 0.39442371250532915, "isApplying": false, "strength": 95.06970359368339, "interpretation": "neutral" }, { "planet1": "Jupiter", "planet2": "Saturn", "type": "OPPOSITION", "angle": 180, "orb": 0.6778443722118368, "isApplying": false, "strength": 91.52694534735204, "interpretation": "challenging" }, { "planet1": "Mercury", "planet2": "North Node", "type": "OPPOSITION", "angle": 180, "orb": 0.804916363861139, "isApplying": false, "strength": 89.93854545173576, "interpretation": "challenging" }, { "planet1": "Mercury", "planet2": "South Node", "type": "CONJUNCTION", "angle": 0, "orb": 0.804916363861139, "isApplying": false, "strength": 89.93854545173576, "interpretation": "neutral" }, { "planet1": "Mercury", "planet2": "Uranus", "type": "QUINCUNX", "angle": 150, "orb": 0.33677933831427254, "isApplying": false, "strength": 88.77402205619092, "interpretation": "neutral" } ], "ascendant": { "longitude": 216.94758165419276, "sign": "Scorpio", "degree": 6.9475816541927315 }, "midheaven": { "longitude": 134.37573350548865, "sign": "Leo", "degree": 14.375733505488654 }, "partOfFortune": { "sign": "Leo", "degree": 11.006562885643916, "longitude": 131.00656288564392, "sect": "day" }, "vertex": { "longitude": 77.23573150642028, "sign": "Gemini", "degree": 17.23573150642028 }, "patterns": [ { "kind": "T_SQUARE", "name": "T-Square", "planets": [ "Moon", "Sun", "Saturn" ], "apex": "Moon", "modality": "cardinal", "dissociate": false, "tightness": 61, "interpretationKey": "aspectPattern.tSquare", "interpretationVars": { "apex": "Moon", "apexSign": "Aries", "end1": "Sun", "end2": "Saturn" }, "interpretation": "T-Square focused on Moon in Aries, tension between Sun and Saturn demands resolution at the apex, the primary growth engine of the chart." }, { "kind": "T_SQUARE", "name": "T-Square", "planets": [ "Moon", "Jupiter", "Saturn" ], "apex": "Moon", "modality": "cardinal", "dissociate": false, "tightness": 62, "interpretationKey": "aspectPattern.tSquare", "interpretationVars": { "apex": "Moon", "apexSign": "Aries", "end1": "Jupiter", "end2": "Saturn" }, "interpretation": "T-Square focused on Moon in Aries, tension between Jupiter and Saturn demands resolution at the apex, the primary growth engine of the chart." } ], "aspectsInterpretation": { "summary": "Your chart contains 37 aspects: 7 harmonious, 17 challenging, and 13 neutral. This creates a balanced overall pattern. The balanced mix of aspects suggests a well-rounded chart with both natural talents and growth opportunities.", "dominant": "balanced", "harmonious": 7, "challenging": 17, "neutral": 13 }, "summary": { "dominantElement": "Water", "dominantModality": "Cardinal", "retrogradePlanets": [ "Saturn", "Uranus", "Neptune", "Pluto", "North Node", "South Node" ], "elementDistribution": { "Fire": 3, "Earth": 4, "Air": 2, "Water": 5 }, "modalityDistribution": { "Cardinal": 7, "Fixed": 6, "Mutable": 1 } } } ``` ## SDK Quick Start ```typescript // npm install @roxyapi/sdk import { createRoxy } from '@roxyapi/sdk'; const roxy = createRoxy(process.env.ROXY_API_KEY!); const { data, error } = await roxy.astrology.generateNatalChart({ body: { date: '1990-06-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York' } }); ``` ```python # pip install roxy-sdk import os from roxy_sdk import create_roxy roxy = create_roxy(api_key=os.environ["ROXY_API_KEY"]) result = roxy.astrology.generate_natal_chart(date="1990-06-15", time="14:30:00", latitude=40.7128, longitude=-74.006, timezone="America/New_York") ``` ```php // composer require roxyapi/sdk (PHP 8.2+, built on Saloon) use function RoxyAPI\Sdk\createRoxy; $roxy = createRoxy(getenv('ROXY_API_KEY')); $result = $roxy->astrology->generateNatalChart(date: '1990-06-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York'); ``` Method names come from OpenAPI `operationId` (camelCase in TS and PHP, snake_case in Python). TS returns `{ data, error, response }` — check `error` first. Python raises `RoxyAPIError`; PHP throws `RoxyApiException` (catch and switch on `$e->errorCode`). ## MCP Tool Naming Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/astrology`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`: ``` GET /astrology/signs -> get_astrology_signs GET /astrology/signs/{id} -> get_astrology_signs_id GET /astrology/planet-meanings -> get_astrology_planet_meanings ``` `tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call). ## Common Mistakes (verified from production) LLMs frequently produce broken Astrology code. These are the correct patterns. - Horoscope path is `GET /astrology/horoscope/{sign}/daily` (weekly and monthly too). Sign is a PATH param, not a query param. Never `?sign=aries`. - Birth chart is `POST /astrology/natal-chart` (not `/birth-chart`). POST with JSON body, not GET. - Daily horoscope response fields: `overview`, `love`, `career`, `health`, `finance`, `advice`, `luckyNumber`, `luckyColor`. No `horoscope`, `lucky_number`, or `mood` fields. - Western `timezone` is REQUIRED (no default). Vedic `timezone` is optional with default `5.5` (IST). ## Domain Gotchas LLMs hallucinate confidently in this category. These are the specific traps. - **Retrograde is per-planet, not "global".** Natal chart planets include `isRetrograde: boolean` per planet. Never generate "Mercury retrograde globally" UI copy — check the specific planet in the response. - **Timezone affects Western calculations more than Vedic.** Western natal charts must respect DST at time of birth. Use the timezone from the Location API, not the user's current clock. - **Sign in horoscope path is lowercase.** `/astrology/horoscope/aries/daily`, never `/Aries/daily` or zodiac symbols. ## Multi-language Support Append `?lang=` to translated endpoints. Supported on this domain: `en, de, es, fr, hi, pt, ru, tr`. English is the default. The `lang` param is ignored on endpoints that have no translatable text. ## Error Contract Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable): - `validation_error` (400, returns `issues[]` with all field errors at once) - `api_key_required` (401), `invalid_api_key` (401) - `subscription_inactive` (403), `subscription_not_found` (404) - `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field) - `rate_limit_exceeded` (429) - `internal_error` (500) Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff. ## Related Surfaces - **Guide:** [Astrology integration guide](https://roxyapi.com/docs/guides/astrology.md) - **Starter app:** [Western Astrology App](https://github.com/RoxyAPI/astrology-starter-app) — clone, add an API key, deploy. - [RoxyAPI for Advanced Use Cases: Simple Surface, Deep Control](https://roxyapi.com/blogs/roxyapi-advanced-use-cases.md) - [Is It Hard to Build Your Own Astrology API?](https://roxyapi.com/blogs/is-it-hard-to-build-your-own-astrology-api.md) - [Cache Astrology API Calls to Cut Costs at Scale](https://roxyapi.com/blogs/cache-astrology-api-calls-reduce-costs-at-scale.md) - [Build a Memory Layer for an AI Astrology Companion](https://roxyapi.com/blogs/build-memory-layer-ai-astrology-companion.md) ## Full Reference For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/astrology/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.