{"openapi":"3.1.0","info":{"title":"Astrology API","version":"2.0.0","description":"Western astrology API for natal birth charts, daily, weekly, and monthly horoscopes with unique content per sign, 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, aspect-pattern detection (Grand Trine, T-Square, Yod), astrocartography planetary lines, relocation charts, and local space maps for location based astrology, plus classical and professional points like fixed star conjunctions, Arabic lots, the asteroid goddesses (Ceres, Pallas, Juno, Vesta), mean and true Black Moon Lilith, and timing techniques like secondary progressions, solar arc directions, and annual profections. Built for horoscope platforms, astrology dating apps, AI chatbots, wellness products, and zodiac content engines. Schedule future horoscopes with a date parameter for editorial workflows, no astronomy expertise needed. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.\n\n# RoxyAPI: AI-Native Insight Infrastructure\n\n> **Base URL:** `https://roxyapi.com/api/v2`\n> All endpoint paths below are relative to this base URL.\n\nThe only multi-domain spiritual intelligence API. 12 domains (astrology, Vedic astrology, forecast, human design, numerology, tarot, biorhythm, I-Ching, crystals, dreams, angel numbers, location), 178+ endpoints, one API key, instant activation. Remote MCP server per domain plus AGENTS.md for AI coding agents.\n\n## Who uses RoxyAPI\n\n- **Developers** building astrology apps, tarot platforms, numerology calculators, or dream journals\n- **AI agent builders** connecting Claude, GPT, or Gemini to real calculation engines via MCP\n- **Vibe coders** shipping insight apps with Cursor, Bolt, or Replit using zero domain knowledge\n- **Founders and brands** launching branded spiritual experiences for their audience\n\n## Quick start (60 seconds)\n\n**1. Get your API key** at [roxyapi.com/pricing](https://roxyapi.com/pricing). Instant delivery, no account required.\n\n**2. Make your first call:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/tarot/draw -X POST -H \"Content-Type: application/json\" -d '{\"count\": 3}'\n```\n\n**3. Monitor usage:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/usage\n```\n\n## AI agent integration (Remote MCP)\n\nRoxyAPI ships a Remote MCP server per product over Streamable HTTP, with no local setup and no Docker. Your AI agent auto-discovers all 178+ endpoints as callable tools with zero configuration:\n- **Claude Desktop, Cursor, Windsurf**: Add MCP server URL in settings\n- **OpenAI Agents, Gemini ADK**: Connect via Streamable HTTP transport\n- **Custom agents**: Use the MCP Python/TypeScript SDK\n\nMCP endpoints: `https://roxyapi.com/mcp/{domain}` (e.g., `/mcp/astrology`, `/mcp/tarot`)\n\nSetup guide: [roxyapi.com/docs/mcp](https://roxyapi.com/docs/mcp)\n\n## Authentication\n\nAll endpoints require an API key via header or query param:\n- **Header (recommended):** `X-API-Key: YOUR_KEY`\n- **Query param (testing):** `?api_key=YOUR_KEY`\n\n## Response format\n\nClean JSON, no wrapper objects. Errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable (stable — safe to switch on programmatically).\n\nRate limit headers on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`\n\n## Errors\n\nAll errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`:\n\n| Status | Code | When |\n|--------|------|------|\n| 400 | `validation_error` | Missing or invalid parameters. Response includes `issues[]` with per-field `path`, `message`, `code`, `expected`, `minimum`, `maximum`, `format`, `pattern`. |\n| 401 | `api_key_required` | No API key provided |\n| 401 | `invalid_api_key` | Key format invalid or tampered |\n| 401 | `subscription_not_found` | Key references non-existent subscription |\n| 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |\n| 404 | `not_found` | Resource not found. Response may include a ranked `suggestions[]` array (each with `endpoint`, `hint`, and a `docs` deep link) for typo recovery. |\n| 405 | `method_not_allowed` | Path exists for a different HTTP method. Response includes `allow[]` and the `Allow` header lists valid methods. |\n| 429 | `rate_limit_exceeded` | Monthly quota reached |\n| 500 | `internal_error` | Server error |\n\n## Pricing\n\nFlat per-request pricing. Every call counts the same, whether a planet position or a full birth chart with aspects. No credit systems, no variable costs. Plans from $39 per month for 50K requests, up to 3M requests, with custom volume above that.\n\nSee [roxyapi.com/pricing](https://roxyapi.com/pricing)\n\n## Resources\n\n- [Quickstart guide](https://roxyapi.com/docs/quickstart) - first API call in 60 seconds\n- [Documentation](https://roxyapi.com/docs) - guides, tutorials, domain reference\n- [MCP setup](https://roxyapi.com/docs/mcp) - connect AI agents\n- [Starter apps](https://roxyapi.com/starters) - clone and deploy in 30 minutes\n- [FAQ](https://roxyapi.com/faq) - common questions\n- [Contact](https://roxyapi.com/contact) - support and API key recovery\n","contact":{"name":"RoxyAPI Support","url":"https://roxyapi.com/contact"},"license":{"name":"Proprietary","url":"https://roxyapi.com/policy/terms"}},"externalDocs":{"description":"Complete API Documentation with Examples","url":"https://roxyapi.com/docs"},"servers":[{"url":"/api/v2","description":"Production API v2"}],"security":[{"apiKey":[]}],"tags":[{"name":"Western Astrology","description":"Western astrology API for natal birth charts, daily, weekly, and monthly horoscopes with unique content per sign, 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, aspect-pattern detection (Grand Trine, T-Square, Yod), astrocartography planetary lines, relocation charts, and local space maps for location based astrology, plus classical and professional points like fixed star conjunctions, Arabic lots, the asteroid goddesses (Ceres, Pallas, Juno, Vesta), mean and true Black Moon Lilith, and timing techniques like secondary progressions, solar arc directions, and annual profections. Built for horoscope platforms, astrology dating apps, AI chatbots, wellness products, and zodiac content engines. Schedule future horoscopes with a date parameter for editorial workflows, no astronomy expertise needed. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your API key for accessing RoxyAPI. Alternatively, you can pass the API key as a query parameter \"api_key\"."}},"schemas":{"NatalChartResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-15","description":"Birth date used for this chart (YYYY-MM-DD)."},"time":{"type":"string","example":"14:30:00","description":"Birth time used for this chart (HH:MM:SS, 24-hour)."},"latitude":{"type":"number","example":40.7128,"description":"Birth latitude in decimal degrees."},"longitude":{"type":"number","example":-74.006,"description":"Birth longitude in decimal degrees."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC in decimal hours."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details echoed back from the request. Confirms the input used for this chart calculation."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet or point name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith). Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The lunar nodes are the mean node; software using the true node may show node positions up to 1.75 degrees different."},"nameLocalized":{"type":"string","example":"Sol","description":"Planet or point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360)."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":22.45,"description":"Degree within the zodiac sign (0-29.999)."},"house":{"type":"number","example":7,"description":"House placement (1-12) based on the selected house system."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is in retrograde motion."},"dignity":{"type":"string","enum":["domicile","exaltation","detriment","fall","peregrine"],"example":"domicile","description":"Essential dignity of this body in the sign it occupies: domicile (the sign it rules, its strongest placement), exaltation (honoured and amplified), detriment (opposite its rulership, where it struggles), fall (opposite its exaltation, where it is weakened), or peregrine (in none of its own dignity signs). Absent for the lunar nodes, Chiron and Black Moon Lilith, which rule no sign and therefore hold no dignity at all, so an absent field and peregrine are different answers. Derived by sign only, so triplicity, bounds and face are not considered. Always English, whatever the lang parameter says, so it stays safe to compare against in code. The four dignity signs behind it are published per body by GET /planet-meanings/{id}."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","description":"One-sentence interpretation of this planet in its sign and house placement.","example":"Your Sun in Cancer in The Seventh House reveals how you express self-awareness and ego in the realm of partnerships."},"detailed":{"type":"string","description":"Multi-sentence detailed interpretation with personality insights.","example":"Sun represents self-awareness and ego. In Cancer, this energy becomes nurturing, protective, emotionally intelligent..."},"keywords":{"type":"array","items":{"type":"string"},"description":"Key personality traits and themes for this placement.","example":["Nurturing","Protective","Emotional","Intuitive","Home-oriented"]}},"required":["summary","detailed","keywords"],"description":"Planet-in-sign-in-house interpretation. Narrative analysis of what this placement means in the natal chart."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) with zodiac signs, house placements, and interpretations."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"House number (1-12)."},"longitude":{"type":"number","example":45.32,"description":"Ecliptic longitude of this house cusp (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Tauro","description":"Zodiac sign name on this cusp in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":15.32,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps with zodiac positions. House cusps divide the chart into life areas."},"houseSystem":{"type":"string","example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Sun","description":"First planet in the aspect pair. Always English, whatever the lang parameter says. Use planet1Localized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Sol","description":"First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2":{"type":"string","example":"Moon","description":"Second planet in the aspect pair. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees."},"planet2Localized":{"type":"string","example":"Luna","description":"Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angle":{"type":"number","example":120,"description":"Exact angle of this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Distance from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (growing stronger) or separating (fading)."},"strength":{"type":"number","example":75,"description":"Aspect strength percentage (0-100) based on orb tightness."},"interpretation":{"type":"string","example":"harmonious","description":"Aspect nature: harmonious, challenging, or neutral. Always English, whatever the lang parameter says, because it is an identifier to compare and style on. Read aspectInterpretation for the sentence a reader sees."},"aspectInterpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Your Sun forms a very strong conjunction (0) with Jupiter, currently separating (weakening). This neutral aspect creates Planets and points that form a conjunction are energies that are united. They are blended; therefore...","description":"One-sentence read of THIS pair: which two bodies, how tight the aspect is, whether it is applying or separating, and how it is classified. Translated in place, so it arrives in the requested language."},"keywords":{"type":"array","items":{"type":"string"},"example":["blend","difficult","unite","united"],"description":"Themes this aspect activates between the two bodies. Translated in place, so they arrive in the requested language."}},"required":["summary","keywords"],"description":"Narrative interpretation of this aspect for this chart. The reference description of the aspect TYPE is not repeated per row, use GET or POST /astrology/aspects for that card."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation","aspectInterpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and interpretation."},"patterns":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["GRAND_TRINE","KITE","T_SQUARE","GRAND_CROSS","YOD","MYSTIC_RECTANGLE","STELLIUM"],"example":"GRAND_TRINE","description":"Pattern kind identifier. GRAND_TRINE (3 trines, harmonious flow), KITE (Grand Trine with a focal outlet planet), T_SQUARE (opposition with squared apex, growth engine), GRAND_CROSS (4 planets in 2 oppositions and 4 squares, peak tension), YOD (Finger of Fate, fated adjustment), MYSTIC_RECTANGLE (oppositions softened by trines and sextiles), STELLIUM (3+ planets clustered in a sign or 10-degree arc)."},"name":{"type":"string","example":"Grand Trine","description":"Human-readable name of the configuration as used in astrological literature."},"planets":{"type":"array","items":{"type":"string"},"example":["Sun","Moon","Mars"],"description":"Participating bodies in canonical order. For Kite, T-Square, and Yod the apex planet appears first."},"apex":{"type":"string","example":"Mars","description":"Focal planet for Kite, T-Square, and Yod patterns. Receives the released energy of the configuration and is the recommended integration point."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"water","description":"Dominant element when the pattern is element-coherent (Grand Trine, Kite). Reported lowercase. Absent for patterns whose meaning does not pivot on element."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"cardinal","description":"Dominant modality for tension-based patterns (T-Square, Grand Cross). Cardinal initiates, Fixed sustains, Mutable adapts."},"dissociate":{"type":"boolean","example":false,"description":"True if the pattern is out-of-sign (one or more planets in a neighboring element or modality). Dissociate patterns are still valid but operate with weakened thematic coherence."},"tightness":{"type":"number","minimum":0,"maximum":100,"example":78,"description":"Tightness score (0-100) derived from the average orb tightness across all defining aspects. Higher means closer to exact and stronger thematic expression."},"interpretation":{"type":"string","example":"Grand Trine in Water signs binds Sun, Moon, and Mars in flowing harmony, gifts that come easily but ask to be activated.","description":"Concise one-line interpretation naming the participating planets and theme. Localized to the requested language via the lang query parameter (defaults to English)."},"interpretationKey":{"type":"string","example":"aspectPattern.grandTrine","description":"Stable template identifier used to render the interpretation. Useful for clients that wish to swap in a custom narrative template while preserving the structured variables."},"interpretationVars":{"type":"object","additionalProperties":{"type":"string","example":"Water","description":"One value interpolated into the interpretation template, keyed by the placeholder name it fills. Which keys are present depends on the pattern: a Grand Trine carries an element plus three planets, a T-Square carries an apex."},"example":{"element":"Water","planet1":"Sun","planet2":"Moon","planet3":"Mars"},"description":"Variables that were interpolated into the interpretation template. Names already resolved to the requested language where appropriate."}},"required":["kind","name","planets","tightness","interpretation","interpretationKey","interpretationVars"]},"description":"Detected multi-planet aspect configurations (Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium). Grand Cross suppresses contained T-Squares, Kite suppresses underlying Grand Trine."},"aspectsInterpretation":{"type":"object","properties":{"summary":{"type":"string","description":"Narrative summary of the overall aspect pattern in this chart.","example":"Your chart contains 15 aspects: 8 harmonious, 5 challenging, and 2 neutral. This creates a harmonious overall pattern."},"dominant":{"type":"string","example":"harmonious","description":"Whether the chart is predominantly harmonious, challenging, or balanced."},"harmonious":{"type":"number","example":8,"description":"Count of harmonious aspects (trine, sextile)."},"challenging":{"type":"number","example":5,"description":"Count of challenging aspects (square, opposition)."},"neutral":{"type":"number","example":2,"description":"Count of neutral aspects (conjunction)."}},"required":["summary","dominant","harmonious","challenging","neutral"],"description":"Aspect pattern analysis showing the balance of harmonious vs challenging energies in the chart."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on the Ascendant (rising sign). Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Tauro","description":"Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":15.32,"description":"Degree within the Ascendant sign (0-29.999)."},"longitude":{"type":"number","example":45.32,"description":"Absolute ecliptic longitude of the Ascendant (0-360)."}},"required":["sign","degree","longitude"],"description":"Ascendant (rising sign). The eastern horizon at birth, defining outward personality and physical appearance."},"midheaven":{"type":"object","properties":{"sign":{"type":"string","example":"Aquarius","description":"Zodiac sign on the Midheaven (MC). Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Acuario","description":"Midheaven sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":8.76,"description":"Degree within the Midheaven sign (0-29.999)."},"longitude":{"type":"number","example":308.76,"description":"Absolute ecliptic longitude of the Midheaven (0-360)."}},"required":["sign","degree","longitude"],"description":"Midheaven (MC). The highest point of the ecliptic at birth, representing career direction and public image."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."},"signLocalized":{"type":"string","example":"Leo","description":"Part of Fortune sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"signLocalized":{"type":"string","example":"Cáncer","description":"Vertex sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."},"summary":{"type":"object","properties":{"dominantElement":{"type":"string","example":"Water","description":"Most represented element in the chart (Fire, Earth, Air, Water). Always English, whatever the lang parameter says. Use dominantElementLocalized for anything a reader sees."},"dominantElementLocalized":{"type":"string","example":"Agua","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"dominantModality":{"type":"string","example":"Cardinal","description":"Most represented modality in the chart (Cardinal, Fixed, Mutable). Always English, whatever the lang parameter says. Use dominantModalityLocalized for anything a reader sees."},"dominantModalityLocalized":{"type":"string","example":"Cardinal","description":"Modality name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"retrogradePlanets":{"type":"array","items":{"type":"string"},"example":["Mercury","Saturn"],"description":"Planets in retrograde motion at the time of birth. Always English, whatever the lang parameter says. Use retrogradePlanetsLocalized for anything a reader sees."},"retrogradePlanetsLocalized":{"type":"array","items":{"type":"string"},"example":["Mercurio","Saturno"],"description":"The same retrograde bodies in the requested language, for display only. Index aligned with retrogradePlanets, so entry n of one names entry n of the other. Present only when lang is set to a language other than English, since in English it would repeat retrogradePlanets exactly."},"elementDistribution":{"type":"object","additionalProperties":{"type":"number","example":3,"description":"Number of planets placed in this element (Fire, Earth, Air, Water). Read the four counts together to spot an emphasis or a missing element."},"example":{"Fire":2,"Earth":3,"Air":1,"Water":4},"description":"Count of planets in each element. Shows elemental emphasis in the personality."},"modalityDistribution":{"type":"object","additionalProperties":{"type":"number","example":4,"description":"Number of planets placed in this modality (Cardinal, Fixed, Mutable). The largest count is the dominant operating mode."},"example":{"Cardinal":4,"Fixed":3,"Mutable":3},"description":"Count of planets in each modality. Shows the dominant operating mode."}},"required":["dominantElement","dominantModality","retrogradePlanets","elementDistribution","modalityDistribution"],"description":"Chart summary with dominant element, modality, retrograde planets, and distribution analysis."}},"required":["birthDetails","planets","houses","houseSystem","aspects","aspectsInterpretation","ascendant","midheaven","partOfFortune","vertex","summary"]},"NatalChartRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"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."}},"required":["date","time","latitude","longitude","timezone"]},"HousesResponse":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-15","description":"Input date used for this house cusp calculation."},"time":{"type":"string","example":"14:30:00","description":"Input time used for this house cusp calculation."},"latitude":{"type":"number","example":40.7128,"description":"Observer latitude used for horizon-based house calculations."},"longitude":{"type":"number","example":-74.006,"description":"Observer longitude used for local sidereal time."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to this calculation."},"houseSystem":{"type":"string","example":"placidus","description":"House system used for this calculation (placidus, whole-sign, equal, koch, or all)."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on the Ascendant (rising sign). Determines the first house cusp."},"degree":{"type":"number","example":15.32,"description":"Degree within the Ascendant sign (0-29.999)."},"longitude":{"type":"number","example":45.32,"description":"Absolute ecliptic longitude of the Ascendant in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Ascendant (rising sign) position. The eastern horizon point at the moment of birth, defining personality expression and physical appearance in Western astrology."},"midheaven":{"type":"object","properties":{"sign":{"type":"string","example":"Aquarius","description":"Zodiac sign on the Midheaven (MC). Indicates career direction and public reputation."},"degree":{"type":"number","example":8.76,"description":"Degree within the Midheaven sign (0-29.999)."},"longitude":{"type":"number","example":308.76,"description":"Absolute ecliptic longitude of the Midheaven in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Midheaven (MC) position. The highest point of the ecliptic at birth, representing career aspirations and public image in natal astrology."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"House number (1-12). Each house governs specific life areas."},"longitude":{"type":"number","example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp."},"degree":{"type":"number","example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps with their zodiac positions. House cusps divide the chart into life areas: identity (1st), resources (2nd), communication (3rd), home (4th), creativity (5th), health (6th), partnerships (7th), transformation (8th), philosophy (9th), career (10th), community (11th), spirituality (12th)."},"comparison":{"type":"object","additionalProperties":{"type":"object","properties":{"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"House number (1-12). Each house governs specific life areas."},"longitude":{"type":"number","example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360), as this house system places it."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp in this house system."},"degree":{"type":"number","example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps as this system computes them. Compare the same house number across the four keys to see how far the systems disagree, which is largest at high latitudes and for the intermediate cusps."}},"required":["houses"]},"description":"Side-by-side house cusp comparison across all four systems (Placidus, Whole Sign, Equal, Koch). Only included when houseSystem is set to \"all\". Useful for educational tools and system comparison."}},"required":["date","time","latitude","longitude","timezone","houseSystem","ascendant","midheaven","houses"]},"AspectsResponse":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-15","description":"Date used for this aspect calculation (YYYY-MM-DD)."},"time":{"type":"string","example":"14:30:00","description":"Time used for this calculation (HH:MM:SS)."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC in decimal hours."},"aspectsFound":{"type":"number","example":12,"description":"Total number of aspects found after any filters applied."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Sun","description":"First planet in the aspect pair. Always English, whatever the lang parameter says. Use planet1Localized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Sol","description":"First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2":{"type":"string","example":"Moon","description":"Second planet in the aspect pair. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees."},"planet2Localized":{"type":"string","example":"Luna","description":"Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angle":{"type":"number","example":120,"description":"Exact angle defining this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Distance from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (growing stronger) or separating (fading)."},"strength":{"type":"number","example":75,"description":"Aspect strength (0-100) based on orb tightness."},"interpretation":{"type":"string","example":"harmonious","description":"Aspect nature for this pair: harmonious, challenging, or neutral. Always English, whatever the lang parameter says, because it is an identifier to compare and style on. This is the field to branch on; meaning.nature is the reference card characterisation of the aspect type and is translated for display."},"meaning":{"type":"object","properties":{"name":{"type":"string","example":"Trine","description":"Aspect display name."},"description":{"type":"object","properties":{"short":{"type":"string","example":"Planets in trine support each other. Trines, by nature, are accepting. They allow us to accept others, ourselves, and situations. The talents that trines offer a native are so natural that they are almost unconscious.","description":"Brief aspect description."},"long":{"type":"string","example":"These talents are second nature and completely natural. So, for example, if a chart has Venus trine Neptune, the native may be poetic, romantic, or artistic, and may easily accept a romantic partner for who they are. With Venus square Neptune the same qualities exist, but expressing them takes conscious work rather than coming naturally.","description":"Detailed aspect description with astrological context."}},"required":["short","long"],"description":"Aspect meaning in short and long form."},"keywords":{"type":"array","items":{"type":"string"},"example":["accept","accepting","difficult","natural","support","talent"],"description":"Keywords associated with this aspect type."},"nature":{"type":"string","example":"harmonious","description":"How this aspect type is characterised in its reference card, in the requested language, exactly like the name, description and keywords beside it. This is a property of the aspect TYPE, so branch on the aspect-level interpretation field instead, which is always English and is the classification applied to this particular pair."}},"required":["name","description","keywords","nature"],"description":"Aspect meaning with keywords, description, and nature classification."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All aspects found between the specified planets, with strength, orb, and interpretation."},"patterns":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["GRAND_TRINE","KITE","T_SQUARE","GRAND_CROSS","YOD","MYSTIC_RECTANGLE","STELLIUM"],"example":"GRAND_TRINE","description":"Pattern kind identifier. GRAND_TRINE (3 trines, harmonious flow), KITE (Grand Trine with a focal outlet planet), T_SQUARE (opposition with squared apex, growth engine), GRAND_CROSS (4 planets in 2 oppositions and 4 squares, peak tension), YOD (Finger of Fate, fated adjustment), MYSTIC_RECTANGLE (oppositions softened by trines and sextiles), STELLIUM (3+ planets clustered in a sign or 10-degree arc)."},"name":{"type":"string","example":"Grand Trine","description":"Human-readable name of the configuration as used in astrological literature."},"planets":{"type":"array","items":{"type":"string"},"example":["Sun","Moon","Mars"],"description":"Participating bodies in canonical order. For Kite, T-Square, and Yod the apex planet appears first."},"apex":{"type":"string","example":"Mars","description":"Focal planet for Kite, T-Square, and Yod patterns. Receives the released energy of the configuration and is the recommended integration point."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"water","description":"Dominant element when the pattern is element-coherent (Grand Trine, Kite). Reported lowercase. Absent for patterns whose meaning does not pivot on element."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"cardinal","description":"Dominant modality for tension-based patterns (T-Square, Grand Cross). Cardinal initiates, Fixed sustains, Mutable adapts."},"dissociate":{"type":"boolean","example":false,"description":"True if the pattern is out-of-sign (one or more planets in a neighboring element or modality). Dissociate patterns are still valid but operate with weakened thematic coherence."},"tightness":{"type":"number","minimum":0,"maximum":100,"example":78,"description":"Tightness score (0-100) derived from the average orb tightness across all defining aspects. Higher means closer to exact and stronger thematic expression."},"interpretation":{"type":"string","example":"Grand Trine in Water signs binds Sun, Moon, and Mars in flowing harmony, gifts that come easily but ask to be activated.","description":"Concise one-line interpretation naming the participating planets and theme. Localized to the requested language via the lang query parameter (defaults to English)."},"interpretationKey":{"type":"string","example":"aspectPattern.grandTrine","description":"Stable template identifier used to render the interpretation. Useful for clients that wish to swap in a custom narrative template while preserving the structured variables."},"interpretationVars":{"type":"object","additionalProperties":{"type":"string","example":"Water","description":"One value interpolated into the interpretation template, keyed by the placeholder name it fills. Which keys are present depends on the pattern: a Grand Trine carries an element plus three planets, a T-Square carries an apex."},"example":{"element":"Water","planet1":"Sun","planet2":"Moon","planet3":"Mars"},"description":"Variables that were interpolated into the interpretation template. Names already resolved to the requested language where appropriate."}},"required":["kind","name","planets","tightness","interpretation","interpretationKey","interpretationVars"]},"description":"Detected multi-planet aspect configurations (Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium)."},"summary":{"type":"object","properties":{"totalAspects":{"type":"number","example":12,"description":"Total aspects found."},"harmonious":{"type":"number","example":7,"description":"Count of harmonious aspects (trine, sextile)."},"challenging":{"type":"number","example":4,"description":"Count of challenging aspects (square, opposition)."},"neutral":{"type":"number","example":1,"description":"Count of neutral aspects (conjunction)."},"byType":{"type":"object","additionalProperties":{"type":"number","example":3,"description":"Number of aspects of this type found in the chart. An aspect type with no hits is absent from the map rather than reported as zero."},"example":{"CONJUNCTION":2,"TRINE":3,"SQUARE":2,"SEXTILE":2,"OPPOSITION":1},"description":"Aspect count grouped by type."}},"required":["totalAspects","harmonious","challenging","neutral","byType"],"description":"Aspect summary with counts by nature and type."}},"required":["date","time","timezone","aspectsFound","aspects","summary"]},"AspectsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Date in YYYY-MM-DD format"},"time":{"type":"string","format":"time","example":"14:30:00","description":"Time in HH:MM:SS format (24-hour)"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"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).","example":-5},"planets":{"type":"array","items":{"type":"string"},"example":["Sun","Moon","Mercury","Venus","Mars"],"description":"Optional: specific bodies to calculate aspects for (defaults to all 14: the 10 classical planets, the lunar nodes, Chiron, and Black Moon Lilith)"},"aspectTypes":{"type":"array","items":{"type":"string"},"example":["CONJUNCTION","OPPOSITION","TRINE","SQUARE"],"description":"Optional: specific aspect types to find (defaults to all 9)"}},"required":["date","time","timezone"]},"AspectPatternsResponse":{"type":"object","properties":{"patterns":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["GRAND_TRINE","KITE","T_SQUARE","GRAND_CROSS","YOD","MYSTIC_RECTANGLE","STELLIUM"],"example":"GRAND_TRINE","description":"Pattern kind identifier. GRAND_TRINE (3 trines, harmonious flow), KITE (Grand Trine with a focal outlet planet), T_SQUARE (opposition with squared apex, growth engine), GRAND_CROSS (4 planets in 2 oppositions and 4 squares, peak tension), YOD (Finger of Fate, fated adjustment), MYSTIC_RECTANGLE (oppositions softened by trines and sextiles), STELLIUM (3+ planets clustered in a sign or 10-degree arc)."},"name":{"type":"string","example":"Grand Trine","description":"Human-readable name of the configuration as used in astrological literature."},"planets":{"type":"array","items":{"type":"string"},"example":["Sun","Moon","Mars"],"description":"Participating bodies in canonical order. For Kite, T-Square, and Yod the apex planet appears first."},"apex":{"type":"string","example":"Mars","description":"Focal planet for Kite, T-Square, and Yod patterns. Receives the released energy of the configuration and is the recommended integration point."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"water","description":"Dominant element when the pattern is element-coherent (Grand Trine, Kite). Reported lowercase. Absent for patterns whose meaning does not pivot on element."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"cardinal","description":"Dominant modality for tension-based patterns (T-Square, Grand Cross). Cardinal initiates, Fixed sustains, Mutable adapts."},"dissociate":{"type":"boolean","example":false,"description":"True if the pattern is out-of-sign (one or more planets in a neighboring element or modality). Dissociate patterns are still valid but operate with weakened thematic coherence."},"tightness":{"type":"number","minimum":0,"maximum":100,"example":78,"description":"Tightness score (0-100) derived from the average orb tightness across all defining aspects. Higher means closer to exact and stronger thematic expression."},"interpretation":{"type":"string","example":"Grand Trine in Water signs binds Sun, Moon, and Mars in flowing harmony, gifts that come easily but ask to be activated.","description":"Concise one-line interpretation naming the participating planets and theme. Localized to the requested language via the lang query parameter (defaults to English)."},"interpretationKey":{"type":"string","example":"aspectPattern.grandTrine","description":"Stable template identifier used to render the interpretation. Useful for clients that wish to swap in a custom narrative template while preserving the structured variables."},"interpretationVars":{"type":"object","additionalProperties":{"type":"string","example":"Water","description":"One value interpolated into the interpretation template, keyed by the placeholder name it fills. Which keys are present depends on the pattern: a Grand Trine carries an element plus three planets, a T-Square carries an apex."},"example":{"element":"Water","planet1":"Sun","planet2":"Moon","planet3":"Mars"},"description":"Variables that were interpolated into the interpretation template. Names already resolved to the requested language where appropriate."}},"required":["kind","name","planets","tightness","interpretation","interpretationKey","interpretationVars"]},"description":"All aspect patterns detected in the chart, in detection order: Grand Cross first, then Kite, Grand Trine, T-Square, Yod, Mystic Rectangle, Stellium. Patterns absorbed by a higher-priority detection (T-Squares inside a Grand Cross, Grand Trines absorbed by a Kite) are not reported separately."},"total":{"type":"number","example":3,"description":"Total number of detected aspect patterns in this chart."},"options":{"type":"object","properties":{"strictOrbs":{"type":"boolean","example":false,"description":"Whether the strict (Pontopia-style) orb budget was used. False uses industry-standard orbs (8 for major aspects, 9 for square, 6 for sextile, 3 for quincunx)."},"include":{"type":"array","items":{"type":"string","enum":["chiron","northNode"]},"example":[],"description":"Optional bodies included beyond the default Sun-Pluto set. Empty means classical 10-planet detection only."}},"required":["strictOrbs","include"],"description":"Echo of the options used for this detection run. Useful for reproducibility and for downstream UI display."}},"required":["patterns","total","options"]},"AspectPatternsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"example":{"date":"1955-02-24","time":"19:15:00","latitude":37.77,"longitude":-122.42,"timezone":-8}},"TransitsResponse":{"type":"object","properties":{"transitDate":{"type":"string","example":"2025-12-19","description":"Date of the transit calculation (YYYY-MM-DD)."},"transitTime":{"type":"string","example":"12:00:00","description":"Time of the transit calculation (HH:MM:SS, 24-hour)."},"timezone":{"type":"number","example":0,"description":"Timezone offset from UTC in hours used for this calculation."},"transitPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith). Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees. The lunar nodes are the mean node; software using the true node may show node positions up to 1.75 degrees different."},"nameLocalized":{"type":"string","example":"Sol","description":"Planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","example":267.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for sign and aspect calculation."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets except Moon and Pluto."},"sign":{"type":"string","example":"Sagittarius","description":"Tropical zodiac sign the planet currently occupies. Changes when longitude crosses a 30-degree boundary. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Sagitario","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":27.45,"description":"Degree within the current zodiac sign (0-29.999). Indicates how far into the sign the planet has progressed."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is currently in apparent retrograde motion. Retrograde transits are considered more introspective and revisionary."}},"required":["name","longitude","latitude","sign","degree","speed","isRetrograde"]},"description":"Current positions of all 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) in the tropical zodiac. Use for daily transit tracking, horoscope generation, and aspect monitoring."},"transitAspects":{"type":"array","items":{"type":"object","properties":{"transitPlanet":{"type":"string","example":"Sun","description":"Transiting planet forming the aspect. Always English, whatever the lang parameter says. Use transitPlanetLocalized for anything a reader sees."},"transitPlanetLocalized":{"type":"string","example":"Sol","description":"Transiting planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"natalPlanet":{"type":"string","example":"Mars","description":"Natal planet being aspected. Always English, whatever the lang parameter says. Use natalPlanetLocalized for anything a reader sees."},"natalPlanetLocalized":{"type":"string","example":"Marte","description":"Natal planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"type":{"type":"string","example":"CONJUNCTION","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Conjunción","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angle":{"type":"number","example":0,"description":"Exact angle of this aspect type in degrees."},"orb":{"type":"number","example":1.2,"description":"Distance from exact aspect in degrees. Tighter orb = stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the transiting planet is moving toward exactitude (applying) or away from it (separating). Applying aspects grow stronger."},"strength":{"type":"number","example":88,"description":"Aspect strength percentage (0-100) based on orb tightness, where 100 is exact."},"nature":{"type":"string","example":"neutral","description":"Aspect nature: harmonious (trine, sextile), challenging (square, opposition), or neutral (conjunction)."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun activates your natal Mars neutrally","description":"Narrative interpretation of what this transit aspect means and how it manifests."},"timing":{"type":"string","example":"Active for a few days","description":"How long this transit influence lasts, localized. The bucket follows the speed of the transiting body: a few hours for the Moon, a few days for the Sun, Mercury, Venus and Mars, one to two weeks for Jupiter, several weeks for Saturn, and an extended period for Uranus, Neptune and Pluto."},"impact":{"type":"string","example":"Self-awareness and ego merges with Assertiveness and aggression. Intensifies this energy.","description":"Strength and nature of the transit impact on your natal chart."},"guidance":{"type":"string","example":"Pay attention to how this combination manifests. Strong energy requires conscious direction.","description":"Practical advice for working with or navigating this transit energy."},"keywords":{"type":"array","items":{"type":"string"},"example":["blend","difficult","unite","united"],"description":"Key themes activated by this transit aspect."}},"required":["summary","timing","impact","guidance","keywords"],"description":"Rich interpretation of the transit aspect including narrative summary, timing, impact assessment, practical guidance, and keywords."}},"required":["transitPlanet","natalPlanet","type","angle","orb","isApplying","strength","nature","interpretation"]},"description":"Transit-to-natal aspects (only included when natalChart is provided in the request). Shows which transiting planets are aspecting natal planets."},"summary":{"type":"object","properties":{"totalAspects":{"type":"number","example":8,"description":"Total transit-to-natal aspects found."},"harmonious":{"type":"number","example":4,"description":"Count of harmonious aspects (trine, sextile)."},"challenging":{"type":"number","example":3,"description":"Count of challenging aspects (square, opposition)."},"neutral":{"type":"number","example":1,"description":"Count of neutral aspects (conjunction)."}},"required":["totalAspects","harmonious","challenging","neutral"],"description":"Transit aspect summary counts (only included when natalChart is provided). Quick overview of the current transit weather."}},"required":["transitDate","transitTime","timezone","transitPlanets"]},"TransitsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2025-12-19","description":"Transit date in YYYY-MM-DD format (defaults to current date)"},"time":{"type":"string","format":"time","example":"12:00:00","description":"Transit time in HH:MM:SS format (defaults to current time)"},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"default":0,"description":"Transit timezone: decimal hours from UTC OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the transit date. Defaults to 0 (UTC).","example":0},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"natalChart":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Date in YYYY-MM-DD format. A single-digit month or day is accepted and zero-padded (2026-3-5 becomes 2026-03-05). Impossible calendar dates are rejected."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Time in 24-hour format. Seconds are optional and default to 00 (14:30 becomes 14:30:00); a single-digit hour is zero-padded. Out-of-range values are rejected."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Natal birth latitude in decimal degrees, positive north. Sets the local sidereal time behind the natal Ascendant and house cusps that the transits are measured against."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Natal birth longitude in decimal degrees, positive east and negative west. Example: New York -74.0060, London -0.1276, Sydney 151.2093."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Natal timezone: decimal hours OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the natal date.","example":-5}},"required":["date","time","latitude","longitude","timezone"],"description":"Optional natal chart data to compare transits against"}}},"AstrocartographyResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute every planetary line."},"lines":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Celestial body this set of planetary lines belongs to. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol for this body."},"rightAscension":{"type":"number","example":90.66,"description":"Equatorial right ascension of the body in degrees (0 to 360), the basis for every line."},"declination":{"type":"number","example":23.44,"description":"Equatorial declination of the body in degrees (-90 to 90), which sets how far the rising and setting lines curve."},"mc":{"type":"object","properties":{"longitude":{"type":"number","example":-111.0142,"description":"Constant geographic longitude of this vertical meridian line in decimal degrees. The body culminates (MC) along it, so plot it as a straight north to south line."},"interpretation":{"type":"string","example":"Your Sun Midheaven line runs through places where Self-awareness and ego comes forward in your public life, career, and reputation. Living or working along this line tends to push this part of you into the spotlight.","description":"Plain language meaning of this Midheaven planetary line for relocation, suitable for chart reports and AI agents."}},"required":["longitude","interpretation"],"description":"Midheaven (MC) line. Places along this meridian where the body was culminating overhead, tied to public life, career, and reputation."},"ic":{"type":"object","properties":{"longitude":{"type":"number","example":68.9858,"description":"Constant geographic longitude of this vertical meridian line in decimal degrees. The body anti-culminates (IC) along it, so plot it as a straight north to south line."},"interpretation":{"type":"string","example":"Your Sun Imum Coeli line runs through places where Self-awareness and ego settles into your home, family, and inner foundations. This line deepens your sense of roots and private life.","description":"Plain language meaning of this Imum Coeli planetary line for relocation, suitable for chart reports and AI agents."}},"required":["longitude","interpretation"],"description":"Imum Coeli (IC) line, opposite the MC. Places where the body was anti-culminating, tied to home, family, and inner foundations."},"ascendant":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","example":40,"description":"Geographic latitude of this sampled point in decimal degrees."},"longitude":{"type":"number","example":139.7118,"description":"Geographic longitude in decimal degrees where the body sits exactly on the eastern (rising) horizon at this latitude."}},"required":["latitude","longitude"]},"description":"Sampled geographic points tracing this rising line from 70 South to 70 North. Join them in latitude order to draw the curved planetary line on a world map."},"circumpolarBeyond":{"type":["number","null"],"example":68.5262,"description":"Absolute latitude in degrees beyond which the body never crosses the horizon, so the line has no points past it. Null when the line spans the full sampled range."},"interpretation":{"type":"string","example":"Your Sun Ascendant line runs through places where Self-awareness and ego colors your identity, vitality, and how you first come across to others. This part of you feels switched on here.","description":"Plain language meaning of this rising (Ascendant) planetary line for relocation, suitable for chart reports and AI agents."}},"required":["points","circumpolarBeyond","interpretation"],"description":"Ascendant (rising) line. Places where the body was on the eastern horizon, tied to identity, vitality, and self-expression."},"descendant":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","example":40,"description":"Geographic latitude of this sampled point in decimal degrees."},"longitude":{"type":"number","example":-1.7402,"description":"Geographic longitude in decimal degrees where the body sits exactly on the western (setting) horizon at this latitude."}},"required":["latitude","longitude"]},"description":"Sampled geographic points tracing this setting line from 70 South to 70 North. Join them in latitude order to draw the curved planetary line on a world map."},"circumpolarBeyond":{"type":["number","null"],"example":68.5262,"description":"Absolute latitude in degrees beyond which the body never crosses the horizon, so the line has no points past it. Null when the line spans the full sampled range."},"interpretation":{"type":"string","example":"Your Sun Descendant line runs through places where Self-awareness and ego shapes your close relationships, partnerships, and the people you attract. Connection themes stand out along this line.","description":"Plain language meaning of this setting (Descendant) planetary line for relocation, suitable for chart reports and AI agents."}},"required":["points","circumpolarBeyond","interpretation"],"description":"Descendant (setting) line. Places where the body was on the western horizon, tied to relationships and partnerships."}},"required":["planet","rightAscension","declination","mc","ic","ascendant","descendant"]},"description":"One entry per body, each carrying its Midheaven, Imum Coeli, Ascendant, and Descendant planetary lines for relocation mapping."},"summary":{"type":"string","example":"Astrocartography lines for 1990-07-15. 10 bodies, each with Midheaven, Imum Coeli, Ascendant, and Descendant lines mapping where their themes turn angular worldwide for relocation planning.","description":"Short overview of the astrocartography map for previews and report intros."}},"required":["birthDetails","lines","summary"]},"RelocationChartResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","example":"1961-08-04","description":"Birth date used for this chart (YYYY-MM-DD)."},"time":{"type":"string","example":"19:24:00","description":"Birth time used for this chart (HH:MM:SS, 24-hour)."},"latitude":{"type":"number","example":21.3069,"description":"Birthplace latitude in decimal degrees."},"longitude":{"type":"number","example":-157.8583,"description":"Birthplace longitude in decimal degrees."},"timezone":{"type":"number","example":-10,"description":"Birth timezone offset from UTC in decimal hours."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birthplace details echoed back. The birth instant is unchanged by relocation."},"relocation":{"type":"object","properties":{"latitude":{"type":"number","example":40.7167,"description":"New location latitude in decimal degrees."},"longitude":{"type":"number","example":-74.006,"description":"New location longitude in decimal degrees."}},"required":["latitude","longitude"],"description":"New location the chart was recomputed for."},"planets":{"type":"array","items":{"$ref":"#/components/schemas/RelocationPlanet"},"description":"All 14 celestial bodies with their unchanged natal signs and degrees, reassigned to the houses they occupy in the relocated chart."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."},"signLocalized":{"type":"string","example":"Tauro","description":"Zodiac sign name on this cusp in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["number","longitude","sign","degree"]},"description":"All 12 relocated house cusps with zodiac positions for the new location."},"houseSystem":{"type":"string","example":"placidus","description":"House system used for the relocated chart (placidus, whole-sign, equal, or koch). Quadrant systems fall back to whole-sign above the polar circle."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Gemini","description":"Tropical zodiac sign on this relocated angle. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Géminis","description":"Zodiac sign name on this angle in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":12.67,"description":"Degree within the zodiac sign on this angle (0-29.999)."},"longitude":{"type":"number","example":72.67,"description":"Absolute ecliptic longitude of this angle in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Relocated Ascendant (rising sign). The eastern horizon at the new place, defining how you come across there."},"midheaven":{"type":"object","properties":{"sign":{"type":"string","example":"Gemini","description":"Tropical zodiac sign on this relocated angle. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Géminis","description":"Zodiac sign name on this angle in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":12.67,"description":"Degree within the zodiac sign on this angle (0-29.999)."},"longitude":{"type":"number","example":72.67,"description":"Absolute ecliptic longitude of this angle in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Relocated Midheaven (MC). The highest point of the ecliptic at the new place, tied to career and public image there."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"signLocalized":{"type":"string","example":"Sagitario","description":"Vertex sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["sign","degree","longitude","house"],"description":"Relocated Vertex. The western prime-vertical and ecliptic intersection at the new place, read as a point of fated encounters."},"changes":{"type":"object","properties":{"ascendantSignChanged":{"type":"boolean","example":true,"description":"Whether the Ascendant sign differs between the birthplace chart and the relocated chart."},"planetsChangedHouse":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Body that occupies a different house after relocation. Always English, whatever the lang parameter says. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"natalHouse":{"type":"number","example":5,"description":"House this body occupied in the birthplace chart (1-12)."},"relocatedHouse":{"type":"number","example":3,"description":"House this body occupies in the relocated chart (1-12)."}},"required":["planet","natalHouse","relocatedHouse"]},"description":"Bodies whose house placement shifts from the birthplace chart to the relocated chart. Empty when nothing changes house."},"angularPlanets":{"type":"array","items":{"type":"string"},"example":["Venus"],"description":"Bodies within three degrees of a relocated angle (Ascendant, Imum Coeli, Descendant, or Midheaven), where their influence is strongest at this location. Always English, whatever the lang parameter says. Use angularPlanetsLocalized for anything a reader sees."},"angularPlanetsLocalized":{"type":"array","items":{"type":"string"},"example":["Venus"],"description":"The same angular bodies in the requested language, for display only. Index aligned with angularPlanets. Present only when lang is set to a language other than English."},"distanceKm":{"type":"number","example":7983.4,"description":"Great-circle distance from the birthplace to the new location in kilometers."},"direction":{"type":"string","example":"northeast","description":"Compass direction (16-point) from the birthplace to the new location."}},"required":["ascendantSignChanged","planetsChangedHouse","angularPlanets","distanceKm","direction"],"description":"How relocation reshapes the chart: Ascendant shift, planets that change house, angular planets, and the move geometry from the birthplace."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Relocated to this place, your chart angles shift while the planets keep their birth positions. The Ascendant moves to Gemini and the Midheaven to Aquarius, and Venus moves close to the angles, where its influence grows strongest in daily life here.","description":"Narrative summary of the relocation: the new Ascendant and Midheaven signs and any planets that move onto the angles. Localized via the lang query parameter."}},"required":["summary"],"description":"Relocation interpretation summary."}},"required":["birthDetails","relocation","planets","houses","houseSystem","ascendant","midheaven","vertex","changes","interpretation"]},"RelocationPlanet":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."},"nameLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Your Sun in Leo in The Third House reveals how you express self-awareness and ego in the realm of communication.","description":"One-sentence interpretation of this planet in its sign and relocated house."},"detailed":{"type":"string","example":"Sun represents self-awareness and ego. In Leo, this energy becomes confident and expressive...","description":"Multi-sentence interpretation of this relocated placement."},"keywords":{"type":"array","items":{"type":"string"},"example":["Confident","Expressive","Communicative"],"description":"Key themes for this relocated placement."}},"required":["summary","detailed","keywords"],"description":"Relocated placement interpretation. The planet keeps its natal sign, so this reads its meaning through the new house it occupies at this location."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"RelocationChartRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1961-08-04","description":"Birth date in YYYY-MM-DD format. The birth moment is unchanged by relocation, so this still defines the planetary positions of the chart."},"time":{"type":"string","format":"time","example":"19:24:00","description":"Birth time in 24-hour HH:MM:SS format. Combined with the timezone it fixes the exact birth instant, which the relocated angles and houses are recomputed for."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Birth timezone: decimal hours from UTC (e.g. -5 for EST, 5.5 for IST) OR IANA name (e.g. \"America/New_York\"). Resolved to the DST-correct offset for the birth date. This is the birthplace timezone, not the new location timezone.","example":-10},"birthLatitude":{"type":"number","minimum":-90,"maximum":90,"example":21.3069,"description":"Birthplace latitude in decimal degrees (-90 to 90). Used for the original natal angles and houses that the relocated chart is compared against."},"birthLongitude":{"type":"number","minimum":-180,"maximum":180,"example":-157.8583,"description":"Birthplace longitude in decimal degrees (-180 to 180). Positive East, negative West."},"relocationLatitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7167,"description":"New location latitude in decimal degrees (-90 to 90). The relocated Ascendant and house cusps are most sensitive to north-south movement."},"relocationLongitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"New location longitude in decimal degrees (-180 to 180). The relocated Midheaven shifts roughly one degree per degree of longitude moved."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for dividing the relocated chart into 12 houses. Placidus (default) is time-sensitive and most popular in Western astrology. Whole Sign assigns one sign per house. Equal divides into 30 degree segments from the Ascendant. Koch emphasizes higher latitudes. Quadrant systems fall back to Whole Sign above the polar circle."}},"required":["date","time","timezone","birthLatitude","birthLongitude","relocationLatitude","relocationLongitude"]},"LocalSpaceResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","example":"1990-07-15","description":"Birth date echoed from the request."},"time":{"type":"string","example":"14:30:00","description":"Birth time echoed from the request."},"latitude":{"type":"number","example":40.7128,"description":"Birthplace latitude, the origin of every local space line."},"longitude":{"type":"number","example":-74.006,"description":"Birthplace longitude, the origin of every local space line."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to the birth instant."}},"required":["date","time","latitude","longitude","timezone"],"description":"The birthplace and birth instant the map was computed for."},"bodies":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Sun","description":"Body name (Sun, Moon, Mercury through Pluto, plus North Node, Chiron, or Black Moon Lilith when requested). Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol for this body."},"azimuth":{"type":"number","example":113.63,"description":"Compass bearing of the body as seen from the birthplace, in degrees clockwise from true north (0 = north, 90 = east, 180 = south, 270 = west). This is the direction the local space line points."},"altitude":{"type":"number","example":59.48,"description":"Angular height of the body above (positive) or below (negative) the local horizon at birth, in degrees (-90 to 90)."},"compassDirection":{"type":"string","example":"ESE","description":"Nearest 16-point compass abbreviation for the azimuth (N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW)."},"aboveHorizon":{"type":"boolean","example":true,"description":"True when the body is above the local horizon (altitude greater than 0) at the birth moment."},"line":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","example":39.42,"description":"Waypoint latitude in decimal degrees."},"longitude":{"type":"number","example":-72.71,"description":"Waypoint longitude in decimal degrees."}},"required":["latitude","longitude"]},"description":"Ordered latitude and longitude waypoints tracing the great-circle local space line from the birthplace along the body azimuth. The first point is the birthplace itself."}},"required":["points"],"description":"The great-circle directional line for this body, ready to plot on a map."},"interpretation":{"type":"string","example":"Your Sun line points southeast from your birthplace. Travelling or facing this direction tends to emphasize Self-awareness and ego in your daily experience.","description":"Plain-language reading of what travelling or facing along this body line tends to emphasize. Localized when a translation exists."}},"required":["planet","azimuth","altitude","compassDirection","aboveHorizon","line","interpretation"]},"description":"Every requested body with its horizon direction, altitude, compass direction, great-circle line, and interpretation."},"summary":{"type":"string","example":"Local space directional map of 10 celestial bodies seen from latitude 40.7128, longitude -74.006. 6 of them sit above the horizon at the birth moment.","description":"One-line overview of the local space map."}},"required":["birthDetails","bodies","summary"]},"FixedStarsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to precess every star."},"orb":{"type":"number","example":1,"description":"Conjunction orb in degrees applied to detect contacts between stars and natal points."},"stars":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"regulus","description":"Lowercase identifier for the fixed star."},"name":{"type":"string","example":"Regulus","description":"Proper name of the fixed star."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":150.06,"description":"Tropical ecliptic longitude of the star in degrees (0-360), precessed from its J2000 position to the chart date."},"sign":{"type":"string","example":"Virgo","description":"Tropical zodiac sign the star currently occupies."},"degree":{"type":"number","minimum":0,"maximum":30,"example":0.06,"description":"Degree within the zodiac sign (0-29.999)."},"magnitude":{"type":"number","example":1.4,"description":"Apparent visual magnitude. Lower is brighter, and the brightest stars are negative."},"nature":{"type":"string","example":"Mars and Jupiter","description":"Traditional planetary nature of the star in classical astrology."},"keywords":{"type":"array","items":{"type":"string"},"example":["royalty","honor","power","ambition","downfall"],"description":"Traditional astrological keywords associated with the star."},"conjunctions":{"type":"array","items":{"type":"object","properties":{"point":{"type":"string","example":"Sun","description":"Natal point conjunct this star: a planet name, or the chart angles MC and ASC. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use pointLocalized for anything a reader sees."},"pointLocalized":{"type":"string","example":"Sol","description":"Natal point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"pointLongitude":{"type":"number","example":149.21,"description":"Tropical ecliptic longitude of the natal point in degrees (0-360)."},"orb":{"type":"number","example":0.62,"description":"Angular separation in degrees between the star and the natal point. Smaller means a tighter, stronger contact."}},"required":["point","pointLongitude","orb"]},"description":"Natal points within the chosen orb of this star. Empty when no planet or angle contacts the star."}},"required":["id","name","longitude","sign","degree","magnitude","nature","keywords","conjunctions"]},"description":"Every catalog star with its precessed tropical position, magnitude, traditional nature, and any conjunctions to the natal chart."},"conjunctions":{"type":"array","items":{"type":"object","properties":{"star":{"type":"string","example":"Regulus","description":"Proper name of the conjunct fixed star."},"point":{"type":"string","example":"Sun","description":"Natal point conjunct the star: a planet name, or the chart angles MC and ASC. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use pointLocalized for anything a reader sees."},"pointLocalized":{"type":"string","example":"Sol","description":"Natal point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"orb":{"type":"number","example":0.62,"description":"Angular separation in degrees between the star and the natal point."},"interpretation":{"type":"string","example":"The fixed star Regulus sits within 0.6 degrees of your Sun, a star of Mars and Jupiter nature in classical astrology. A star this close to a chart point colors how that point expresses itself with its traditional meaning.","description":"Plain language meaning of this star contact, blending the star traditional nature with the chart point. Localized to the requested language."}},"required":["star","point","orb","interpretation"]},"description":"Flat list of every star to natal point conjunction, sorted tightest first, each with an interpretation. The high-value summary of where fixed stars touch the chart."},"summary":{"type":"string","example":"Fixed star positions for 1990-07-15 with 3 conjunctions within 1 degrees across the major named stars including Regulus, Spica, and Algol.","description":"Short overview of the fixed-star report for previews and report intros."}},"required":["birthDetails","orb","stars","conjunctions","summary"]},"ArabicLotsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute every lot."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect that selected each formula. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Every lot swaps its two non-Ascendant terms between day and night."},"lots":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"fortune","description":"Stable machine identifier for the lot (fortune, spirit, eros, necessity, courage, victory, nemesis). Use this for lookups."},"name":{"type":"string","example":"Part of Fortune","description":"Name of the lot. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Parte de la Fortuna","description":"Lot name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute tropical ecliptic longitude of the lot in degrees (0 to 360)."},"sign":{"type":"string","example":"Aries","description":"Tropical zodiac sign the lot falls in."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree of the lot within its zodiac sign (0 to 29.999)."},"formula":{"type":"string","example":"Ascendant + Sun - Moon","description":"Human readable arc used for this chart, with the day or night term order already applied by sect."},"interpretation":{"type":"string","example":"Your Part of Fortune falls in Aries, marking the body, health, material wellbeing, and the flow of fortune through your life. Lots are sensitive points derived by arc from the Ascendant, Sun, Moon, and planets, with the formula reversed between day and night charts.","description":"Plain language meaning of this lot in its sign, suitable for chart reports and AI agents. Localized to the requested language."}},"required":["id","name","longitude","sign","degree","formula","interpretation"]},"description":"The seven Hermetic lots in canonical order: Part of Fortune and Part of Spirit from the luminaries, then Eros, Necessity, Courage, Victory, and Nemesis from a planet paired with Fortune or Spirit."},"summary":{"type":"string","example":"Seven Hermetic lots for 1990-07-15 cast from a night chart: Fortune, Spirit, Eros, Necessity, Courage, Victory, and Nemesis, each projected by arc from the Ascendant.","description":"Short overview of the lot set for previews and report intros."}},"required":["birthDetails","sect","lots","summary"]},"ArabicLotsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used to place the Sun, which determines the chart sect (day when the Sun is above the horizon, night when below) and therefore which lot formula applies. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["date","time","latitude","longitude","timezone"]},"AsteroidsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute every asteroid."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system actually used to place the asteroids, after any polar fallback to Whole Sign."},"asteroids":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Ceres","description":"Name of the asteroid: Ceres, Pallas, Juno, or Vesta. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Palas","description":"Asteroid name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":64.72,"description":"Absolute tropical ecliptic longitude of the asteroid in degrees (0 to 360)."},"latitude":{"type":"number","example":-2.83,"description":"Ecliptic latitude in degrees, the angular distance north or south of the ecliptic plane."},"sign":{"type":"string","example":"Gemini","description":"Tropical zodiac sign the asteroid falls in."},"degree":{"type":"number","minimum":0,"maximum":30,"example":4.72,"description":"Degree of the asteroid within its zodiac sign (0 to 29.999)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Natal house placement (1 to 12) from the selected house system and birth location."},"speed":{"type":"number","example":0.409,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the asteroid appears to move backward from Earth, true when the daily speed is negative."},"interpretation":{"type":"string","example":"Your Ceres in Gemini speaks to how you nurture and are nurtured, the cycles of nourishment, loss, and return, and the bond between caretaker and cared-for.","description":"Plain language meaning of this asteroid in its sign, suitable for chart reports and AI agents. Localized to the requested language."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde","interpretation"]},"description":"The four classical asteroid goddesses in canonical order: Ceres, Pallas, Juno, and Vesta, each with its tropical position, house, motion, and interpretation."},"summary":{"type":"string","example":"Asteroid goddess positions for 1990-07-15: Ceres, Pallas, Juno, and Vesta placed by sign, house, and retrograde motion.","description":"Short overview of the asteroid set for previews and report intros."}},"required":["birthDetails","houseSystem","asteroids","summary"]},"AsteroidsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used to assign each asteroid to a natal house. Placidus (default), Whole Sign, Equal, or Koch. Above the polar circle, quadrant systems fall back to Whole Sign and the echoed houseSystem reports the system actually used."}},"required":["date","time","latitude","longitude","timezone"]},"LilithResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute both Lilith variants."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system applied when placing each variant in a house."},"lilith":{"type":"array","items":{"type":"object","properties":{"variant":{"type":"string","enum":["mean","true"],"example":"mean","description":"Which lunar apogee this entry describes. The mean variant is the smoothed average apogee; the true variant is the instantaneous osculating apogee. Always one of these two English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use variantLocalized for anything a reader sees."},"variantLocalized":{"type":"string","example":"media","description":"Apogee variant label in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":140.58,"description":"Absolute tropical ecliptic longitude of the apogee in degrees (0 to 360)."},"latitude":{"type":"number","example":-0.66,"description":"Ecliptic latitude in degrees, the projection of the apogee off the ecliptic plane. Reaches up to about 5 degrees because the lunar orbit is inclined."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign the apogee falls in, naming where the suppressed instinct lives."},"degree":{"type":"number","minimum":0,"maximum":30,"example":20.58,"description":"Degree of the apogee within its zodiac sign (0 to 29.999)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1 to 12) in the selected house system, the area of life where the Lilith theme plays out."},"speed":{"type":"number","example":0.1108,"description":"Daily motion in degrees per day. The mean apogee is always positive (direct); the true apogee can be negative (retrograde)."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the apogee is moving backward. Always false for the mean apogee; the true apogee turns retrograde when the osculating ellipse swings the apogee direction backward."},"interpretation":{"type":"string","example":"Your mean Black Moon Lilith in Leo marks where you meet the wild, untamed, and unapologetic in yourself, the instincts you were taught to suppress and the line past which you refuse to be tamed or shamed.","description":"Plain language meaning of this Lilith variant in its sign, suitable for chart reports and AI agents. Localized to the requested language."},"note":{"type":"string","example":"The mean apogee is the smoothed average position, steadier and the most widely used for psychological reading.","description":"Short explanation of how this variant is defined and how it differs from the other, localized to the requested language."}},"required":["variant","longitude","latitude","sign","degree","house","speed","isRetrograde","interpretation","note"]},"description":"Both Black Moon Lilith variants, the mean lunar apogee first and the true (osculating) apogee second."},"summary":{"type":"string","example":"Black Moon Lilith for 1961-08-04: mean apogee in Leo and true osculating apogee in Leo, each with sign, degree, house, and interpretation.","description":"Short overview of both variants for previews and report intros."}},"required":["birthDetails","houseSystem","lilith","summary"]},"LilithRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used to place each Lilith variant in a house. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["date","time","latitude","longitude","timezone"]},"ProgressionsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place the progressed chart is built from."},"targetDate":{"type":"string","example":"2025-07-15","description":"The requested date the chart was progressed to."},"progressedDate":{"type":"string","example":"1990-08-17","description":"UTC calendar date of the progressed moment, the ephemeris day whose real positions stand in for the target date. One day after birth per year of elapsed life."},"elapsedYears":{"type":"number","example":35,"description":"Years elapsed between birth and the target date, measured in mean tropical years. Drives both the progressed planets and the Naibod progression of the angles. Negative values progress the chart converse (before birth)."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Body name in canonical English. One of the 10 classical planets, the lunar nodes, Chiron, or Black Moon Lilith. Unchanged by the lang parameter, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":165.18,"description":"Progressed tropical ecliptic longitude in degrees (0 to 360)."},"sign":{"type":"string","example":"Virgo","description":"Tropical zodiac sign the progressed body falls in. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Virgo","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.18,"description":"Degree of the progressed body within its zodiac sign (0 to 29.999)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":2,"description":"Whole-sign house (1 to 12) counted from the progressed Ascendant sign. The 1st house is the entire sign the progressed Ascendant falls in."},"speed":{"type":"number","example":0.985,"description":"Daily motion of the body at the progressed instant in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the body is retrograde at the progressed instant, true when the daily speed is negative."},"interpretation":{"type":"string","example":"Your progressed Sun in Virgo reflects how self-awareness and ego has matured and shifted since birth.","description":"Plain language meaning of this progressed body in its sign, suitable for chart reports and AI agents. Localized to the requested language."}},"required":["name","longitude","sign","degree","house","speed","isRetrograde","interpretation"]},"description":"Every progressed body in canonical order: the 10 classical planets, the lunar nodes, Chiron, and Black Moon Lilith. The progressed Sun moves about one degree per year and the progressed Moon about one sign per two and a half years, so these two are the headline movers in any progressed reading."},"ascendant":{"type":"object","properties":{"longitude":{"type":"number","minimum":0,"maximum":360,"example":134.27,"description":"Absolute tropical ecliptic longitude of the progressed angle in degrees (0 to 360)."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign the progressed angle falls in. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Leo","description":"Zodiac sign name on this angle in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","minimum":0,"maximum":30,"example":14.27,"description":"Degree of the progressed angle within its zodiac sign (0 to 29.999)."}},"required":["longitude","sign","degree"],"description":"Progressed Ascendant, the rising degree advanced by the Naibod arc per year. Marks the evolving outward style and immediate environment."},"midheaven":{"type":"object","properties":{"longitude":{"type":"number","minimum":0,"maximum":360,"example":134.27,"description":"Absolute tropical ecliptic longitude of the progressed angle in degrees (0 to 360)."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign the progressed angle falls in. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Leo","description":"Zodiac sign name on this angle in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","minimum":0,"maximum":30,"example":14.27,"description":"Degree of the progressed angle within its zodiac sign (0 to 29.999)."}},"required":["longitude","sign","degree"],"description":"Progressed Midheaven, the culminating degree advanced by the Naibod arc per year. Marks the evolving vocation and public direction."},"summary":{"type":"string","example":"Your secondary progressed chart advances the birth chart by one day for each year of life.","description":"Short overview of the progressed chart led by the progressed Sun and Moon. Localized to the requested language."}},"required":["birthDetails","targetDate","progressedDate","elapsedYears","planets","ascendant","midheaven","summary"]},"ProgressionsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"targetDate":{"type":"string","format":"date","example":"2025-07-15","description":"Date to progress the chart to, in YYYY-MM-DD format. Usually today or a forecast date. The day-for-a-year key turns the elapsed years since birth into the same number of ephemeris days after the birth moment."}},"required":["date","time","latitude","longitude","timezone","targetDate"]},"SolarArcResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to compute the natal chart and the solar arc."},"targetDate":{"type":"string","format":"date","example":"2025-07-15","description":"Echo of the date the chart was directed to."},"solarArc":{"type":"number","minimum":0,"maximum":360,"example":34.52,"description":"The solar arc in degrees: the secondary-progressed Sun longitude minus the natal Sun longitude. Approximately one degree per year of life. Every natal point is advanced by exactly this arc."},"summary":{"type":"string","example":"Solar arc directions move every point in your chart forward by the same arc the Sun has travelled by progression, about one degree per year.","description":"Short overview of the directed chart for previews and report intros. Localized to the requested language."},"directed":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Name of the directed point, covering the planets and the two angles, the Ascendant and the Midheaven, alike. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sol","description":"Directed point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"natalLongitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Absolute tropical ecliptic longitude of the point in the natal chart, in degrees (0 to 360)."},"directedLongitude":{"type":"number","minimum":0,"maximum":360,"example":143.78,"description":"Absolute tropical ecliptic longitude after directing, in degrees (0 to 360). Equals the natal longitude plus the solar arc, normalized to a full circle."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign the directed point falls in. A directed point crossing into a new sign marks a developmental turning point."},"degree":{"type":"number","minimum":0,"maximum":30,"example":23.78,"description":"Degree of the directed point within its zodiac sign (0 to 29.999)."},"interpretation":{"type":"string","example":"Your solar arc directed Sun has moved to Leo, carrying self-awareness and ego forward by the 31 degree arc.","description":"Plain language meaning of this directed point, suitable for chart reports and AI agents. Localized to the requested language."}},"required":["name","natalLongitude","directedLongitude","sign","degree","interpretation"]},"description":"Every natal point advanced by the solar arc: the planets and bodies in canonical order first, then the Ascendant and the Midheaven."}},"required":["birthDetails","targetDate","solarArc","summary","directed"]},"SolarArcRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"targetDate":{"type":"string","format":"date","example":"2025-07-15","description":"Date to direct the chart to, in YYYY-MM-DD format. Every natal point is advanced by the solar arc accumulated from birth to this date, about one degree for each year of life."}},"required":["date","time","latitude","longitude","timezone","targetDate"]},"ProfectionsResponse":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Echo of the birth moment and place used to derive the natal Ascendant and the lord of the year placement."},"targetDate":{"type":"string","format":"date","example":"2025-08-04","description":"Target date whose profection year was computed, echoed from the request."},"age":{"type":"integer","minimum":0,"example":30,"description":"Completed whole years from birth to the target date. Age 0 is the birth year and profects the first house."},"profectedHouse":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"Profected whole sign house activated for the year (1 to 12), computed as age modulo 12 plus 1. House 1 is the rising sign and the cycle repeats every twelve years."},"profectedSign":{"type":"string","example":"Leo","description":"Tropical zodiac sign on the profected house: the rising sign advanced by one whole sign for each completed year."},"lordOfYear":{"type":"string","example":"Sun","description":"Lord of the year (annual time lord): the traditional ruling planet of the profected sign whose natal condition and transits color the themes of the year."},"lordNatalPosition":{"type":"object","properties":{"sign":{"type":"string","example":"Leo","description":"Zodiac sign the lord of the year occupies in the natal chart."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"Natal house the lord of the year occupies (1 to 12), in the requested house system."}},"required":["sign","house"],"description":"Where the lord of the year sits in the birth chart: the natal sign and house that ground the theme of the profection year."},"interpretation":{"type":"string","example":"This profection year activates The Seventh House in Leo, making Sun your lord of the year. The year takes its tone from partnerships and relationships and from how Sun sits in your birth chart.","description":"Plain language reading of the profection year, combining the profected house theme, the profected sign, and the lord of the year. Localized to the requested language."},"summary":{"type":"string","example":"At age 30, the annual profection activates house 7 in Leo, making Sun the lord of the year for 2025-08-04.","description":"Short overview of the profection year for previews and report intros."}},"required":["birthDetails","targetDate","age","profectedHouse","profectedSign","lordOfYear","lordNatalPosition","interpretation","summary"]},"ProfectionsRequest":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"targetDate":{"type":"string","format":"date","example":"2025-08-04","description":"Date whose profection year you want, in YYYY-MM-DD format. The completed whole years from the birth date to this date select the profected house and sign. Must fall on or after the birth date."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used only to report where the lord of the year sits in the natal chart. The profected house and sign always use whole sign profection from the rising sign. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["date","time","latitude","longitude","timezone","targetDate"]}},"parameters":{}},"paths":{"/signs":{"get":{"operationId":"listZodiacSigns","tags":["Western Astrology"],"summary":"Get all zodiac signs - Complete zodiac signs list with dates and elements","description":"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/{id} for complete zodiac sign profiles with personality traits, compatibility, and detailed characteristics.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved all 12 zodiac signs","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"aries","description":"Lowercase sign identifier (e.g., aries, taurus, gemini)."},"name":{"type":"string","example":"Aries","description":"Display name of the zodiac sign."},"symbol":{"type":"string","example":"♈","description":"Unicode zodiac symbol for this sign."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"fire","description":"Elemental classification: fire, earth, air, or water. Always one of these four English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"dates":{"type":"object","properties":{"start":{"type":"string","example":"Mar 21","description":"Start date of this sign in the tropical zodiac."},"end":{"type":"string","example":"Apr 19","description":"End date of this sign in the tropical zodiac."}},"required":["start","end"],"description":"Tropical zodiac date range for this sign."},"description":{"type":"string","example":"Ambitious, independent, impatient","description":"Brief overview of this zodiac sign personality and themes."}},"required":["id","name","element","dates","description"]},"description":"All 12 tropical zodiac signs with names, symbols, elements, date ranges, and descriptions."}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/signs/{id}":{"get":{"operationId":"getZodiacSign","tags":["Western Astrology"],"summary":"Get zodiac sign details - Complete astrology sign profile with personality traits","description":"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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"aries","description":"Sign ID (lowercase, e.g., aries, taurus) or display name (case-insensitive, e.g., Aries, TAURUS)."},"required":true,"description":"Sign ID (lowercase, e.g., aries, taurus) or display name (case-insensitive, e.g., Aries, TAURUS).","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved zodiac sign","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"aries","description":"Lowercase sign identifier."},"name":{"type":"string","example":"Aries","description":"Display name of the zodiac sign."},"symbol":{"type":"string","example":"♈","description":"Unicode zodiac symbol."},"symbolName":{"type":"string","example":"The Ram","description":"Symbol name or mascot associated with this sign."},"element":{"type":"string","enum":["fire","earth","air","water"],"example":"fire","description":"Elemental classification: fire, earth, air, or water. Determines temperament and compatibility group. Always one of these four English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use elementLocalized for anything a reader sees."},"elementLocalized":{"type":"string","example":"Fuego","description":"Element name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"modality":{"type":"string","enum":["cardinal","fixed","mutable"],"example":"cardinal","description":"Quality/modality: cardinal (initiating), fixed (sustaining), or mutable (adapting). Always one of these three English literals, whatever the lang parameter says, so it stays safe to compare against in code. Use modalityLocalized for anything a reader sees."},"modalityLocalized":{"type":"string","example":"Cardinal","description":"Modality name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"rulingPlanet":{"type":"string","example":"Mars","description":"Traditional ruling planet that governs this sign. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use rulingPlanetLocalized for anything a reader sees."},"rulingPlanetLocalized":{"type":"string","example":"Marte","description":"Ruling planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"dates":{"type":"object","properties":{"start":{"type":"string","example":"Mar 21","description":"Start date of this sign season."},"end":{"type":"string","example":"Apr 19","description":"End date of this sign season."}},"required":["start","end"],"description":"Tropical zodiac date range for this sign."},"keywords":{"type":"array","items":{"type":"string"},"example":["ambitious","courageous","energetic"],"description":"Key personality traits and descriptive words for this sign."},"description":{"type":"object","properties":{"short":{"type":"string","example":"Ambitious, independent, impatient","description":"Brief 1-2 sentence personality overview."},"long":{"type":"string","example":"Aries, the first sign in the zodiac, belongs to those born between March 21 and April 19. Aries are the trailblazers. Passionate and independent, an Aries will never do something just because everyone else is doing it. Competitive to the max, the best way to motivate an Aries is to turn something into a contest.","description":"Detailed multi-paragraph sign profile with personality analysis."}},"required":["short","long"],"description":"Sign description in short and long form."},"famous":{"type":"array","items":{"type":"string"},"example":["Leonardo da Vinci","Lady Gaga"],"description":"Notable people born under this zodiac sign."},"strengths":{"type":"array","items":{"type":"string"},"example":["You are the most courageous and ambitious sign, the leader of every pack.","Your determination is unmatched when it comes to getting what you want.","You work hard but also play hard, and you are the life of every party."],"description":"Key strengths and lovable qualities of this sign."},"motto":{"type":"string","example":"I am.","description":"Signature motto or tagline for this sign."},"gifts":{"type":"string","example":"Whether it is backpacking around the world, launching a business, or training for a marathon, once an Aries sets a goal they will achieve it. Rams never need a plus one: they love their own company.","description":"Greatest gifts and natural talents of this sign."},"challenges":{"type":"string","example":"The world according to an Aries makes so much sense that they have a hard time accepting alternative viewpoints. Slowing down is also tough, and to maintain relationships an Aries must learn to adapt to other ways of doing and seeing.","description":"Greatest challenges and growth areas for this sign."},"weapon":{"type":"string","example":"Strong, adamant, and forged in fire, it is fitting that the Aries secret weapon is iron, one of the strongest elements. Weld it, cast it, or temper it, and iron takes on a seemingly limitless range of shapes.","description":"Secret weapon or superpower of this sign."},"compatibleSigns":{"type":"array","items":{"type":"string"},"example":["Leo","Sagittarius","Gemini"],"description":"Most compatible zodiac signs for this sign. Trine partners (same element, 120 degrees apart) listed first, followed by a sextile partner (complementary element, 60 degrees apart). Use for compatibility widgets, dating app onboarding, sign profile cards, and zodiac matchmaking."}},"required":["id","name","symbolName","element","modality","rulingPlanet","dates","keywords","description","compatibleSigns"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Zodiac sign not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/planet-meanings":{"get":{"operationId":"listPlanetMeanings","tags":["Western Astrology"],"summary":"Get all planet meanings - Complete astrology planet interpretations list","description":"Returns all 14 astrological bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) 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/{id} for complete profiles with detailed interpretations, keywords, temperature, and dignities (rulership/detriment/exaltation/fall).","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved all 14 body meanings","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"sun","description":"Lowercase planet identifier (e.g., sun, moon, mercury)."},"name":{"type":"string","example":"Sun","description":"Display name of the planet."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol for this planet."},"tagline":{"type":"string","example":"Self-awareness and ego","description":"Short tagline summarizing this planet in astrology."},"category":{"type":"string","example":"personal","description":"Planet classification: personal (Sun-Mars), social (Jupiter-Saturn), or generational (Uranus-Pluto)."},"rulership":{"type":"string","example":"Leo","description":"Zodiac sign this planet rules. The sign where the planet operates most naturally. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"description":{"type":"string","example":"The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose. Your Sun sign is the foundation of your natal chart.","description":"Brief overview of the planet and its astrological significance."}},"required":["id","name","symbol","tagline","description"]},"description":"All 14 astrological bodies with names, symbols, taglines, categories, and brief descriptions."}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/planet-meanings/{id}":{"get":{"operationId":"getPlanetMeaning","tags":["Western Astrology"],"summary":"Get planet meaning details - Complete astrology planet interpretation","description":"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/exaltation/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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","example":"sun","description":"Planet ID (lowercase, e.g., sun, moon, mercury) or display name (case-insensitive, e.g., Sun, MOON)."},"required":true,"description":"Planet ID (lowercase, e.g., sun, moon, mercury) or display name (case-insensitive, e.g., Sun, MOON).","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Successfully retrieved planet meaning","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"sun","description":"Lowercase planet identifier."},"name":{"type":"string","example":"Sun","description":"Display name of the planet."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol."},"tagline":{"type":"string","example":"Self-awareness and ego","description":"Short tagline summarizing this planet."},"category":{"type":"string","example":"personal","description":"Planet classification: personal (Sun-Mars), social (Jupiter-Saturn), or generational (Uranus-Pluto)."},"temperature":{"type":"string","example":"Hot","description":"Traditional planet temperature (Hot, Cold, or Neutral)."},"orbit":{"type":"string","example":"365.25 days","description":"Orbital period around the Sun or zodiac cycle length."},"retrograde":{"type":"boolean","example":false,"description":"Whether this planet can appear retrograde. Always false for Sun and Moon."},"rulership":{"type":"string","example":"Leo","description":"Zodiac sign this planet rules (domicile). Where the planet operates most naturally. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"detriment":{"type":"string","example":"Aquarius","description":"Sign of detriment. Opposite the rulership sign, where the planet struggles. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"exaltation":{"type":"string","example":"Aries","description":"Sign of exaltation. Where the planet is honored and amplified. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"exultation":{"type":"string","example":"Aries","description":"Deprecated: use exaltation. Retained for backward compatibility, scheduled for removal in v3. Sign of exaltation, carrying the same value as the exaltation field."},"fall":{"type":"string","example":"Libra","description":"Sign of fall. Opposite the exaltation sign, where the planet is weakened. Absent for the lunar nodes, Chiron, and Black Moon Lilith."},"keywords":{"type":"object","properties":{"positive":{"type":"array","items":{"type":"string"},"example":["Vitality","Confidence","Leadership"],"description":"Positive traits and keywords when this planet is well-aspected."},"negative":{"type":"array","items":{"type":"string"},"example":["Ego","Arrogance","Domineering"],"description":"Shadow traits when this planet is challenged or afflicted."}},"required":["positive","negative"],"description":"Positive and negative keyword associations for this planet."},"description":{"type":"object","properties":{"short":{"type":"string","example":"The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose. Your Sun sign is the foundation of your natal chart, shaping how you assert yourself and pursue your goals.","description":"Brief 1-2 sentence overview of the planet."},"long":{"type":"string","example":"The Sun traveling through the zodiac creates what we think of as our astrological year. In the natal chart, the Sun represents who we are and who we strive to be. Unlike the Moon, which represents our emotional responses, the Sun stands for our most rational selves and the way we interact with the world on a daily basis. Approximately every 30 days the Sun transits to a new sign and brings a fresh sense of perspective.","description":"Detailed multi-paragraph description of the planet, its symbolism, and astrological meaning."}},"required":["short","long"],"description":"Planet description in short and long form."}},"required":["id","name","symbol","tagline","temperature","orbit","keywords","description"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"Planet not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. May change wording — do not parse programmatically."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/natal-chart":{"post":{"operationId":"generateNatalChart","tags":["Western Astrology"],"summary":"Generate natal chart - Birth chart calculator API with houses and aspects","description":"Calculate complete Western astrology natal chart (birth chart) with tropical zodiac. Returns all 14 celestial bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith), 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. Verified against NASA JPL Horizons.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NatalChartRequest"}}}},"responses":{"200":{"description":"Successful natal chart calculation with complete astrological data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NatalChartResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/planets":{"post":{"operationId":"getPlanetaryPositions","tags":["Western Astrology"],"summary":"Get planetary positions - Ephemeris calculator for all planets","description":"Calculate accurate tropical zodiac positions for all 14 celestial bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) 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. Verified against NASA JPL Horizons.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2025-12-18","description":"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."},"time":{"type":"string","format":"time","example":"12:00:00","description":"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."},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"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":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"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."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC (e.g. -5 for EST, 5.5 for IST, 9 for JST, 5.75 for NPT) OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the chart date.","example":-5}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Planetary positions calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet name (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith). The lunar nodes are the mean node; software using the true node may show node positions up to 1.75 degrees different."},"longitude":{"type":"number","example":267.45,"description":"Tropical ecliptic longitude in degrees (0-360)."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees."},"sign":{"type":"string","example":"Sagittarius","description":"Tropical zodiac sign this planet occupies."},"degree":{"type":"number","example":27.45,"description":"Degree within the zodiac sign (0-29.999)."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet is in apparent retrograde motion."},"symbol":{"type":"string","example":"☉","description":"Unicode astronomical symbol for this planet."},"tagline":{"type":"string","example":"Self-awareness & ego","description":"Short tagline summarizing what this planet governs."},"description":{"type":"string","example":"The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose.","description":"Brief description of this planet in astrological context."},"keywords":{"type":"array","items":{"type":"string"},"example":["Identity","Vitality","Purpose"],"description":"Key themes and traits associated with this planet."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun in Sagittarius (Archer) brings adventurous, optimistic, independent energy to the themes of self-awareness and ego. This placement gives your Sun expression a distinctly Sagittarius character, shaping how you navigate these areas of life.","description":"Interpretation of this planet in its current zodiac sign."},"planetMeaning":{"type":"string","example":"The Sun represents your core identity, ego, and conscious will. It governs vitality, self-expression, and life purpose.","description":"General meaning of this planet in astrology."},"signExpression":{"type":"string","example":"Independent and strong-willed, Sagittarius personalities are all about going off the beaten path. Sagittarius is not afraid to step away from the pack, and is a natural born leader who goes after what they want, regardless of what other people think.","description":"How this planet expresses through the current sign."},"keywords":{"type":"array","items":{"type":"string"},"example":["active","awareness","bright","confidence","consciousness","adventurous","optimistic","independent"],"description":"Keywords for this specific planet-in-sign combination."}},"required":["summary","planetMeaning","signExpression","keywords"],"description":"Planet-in-sign interpretation. How this planet expresses through the zodiac sign it currently occupies."}},"required":["name","longitude","latitude","sign","degree","speed","isRetrograde"]},"description":"All 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith) with zodiac signs, speeds, retrograde status, meanings, and interpretations."}},"required":["planets"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/planets/monthly":{"post":{"operationId":"getMonthlyTropicalEphemeris","tags":["Western Astrology"],"summary":"Monthly Ephemeris - Daily tropical planetary positions for a month","description":"Get daily tropical ecliptic positions for all 14 Western bodies (the 10 classical planets Sun through Pluto, the lunar nodes, Chiron, and Black Moon Lilith) for an entire month. Returns longitude, zodiac sign, degree within sign, and retrograde status for each body on each day, calculated at noon UTC. Omit year and month to get the month in progress, so a published ephemeris page stays current without a redeploy. Essential for ephemeris tables, transit tracking, retrograde calendars, and planetary movement charts. Monthly ephemeris API, tropical position table, daily planet transit positions, ecliptic longitude calculator. Verified against NASA JPL Horizons.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"example":2026,"description":"Year for the monthly ephemeris (1900-2100). Defaults to the current year (UTC)."},"month":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"Month number (1-12) for the ephemeris. Defaults to the current month (UTC)."}}}}}},"responses":{"200":{"description":"Monthly ephemeris data","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2026,"description":"Year of the ephemeris. Echoes the year that was requested, or the current UTC year when it was omitted."},"month":{"type":"number","example":8,"description":"Month of the ephemeris. Echoes the month that was requested, or the current UTC month when it was omitted."},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-08-01","description":"Date in YYYY-MM-DD format."},"positions":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string","example":"Mars","description":"Body name, one of the 14 bodies Western astrology reads: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, Chiron, Black Moon Lilith. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use planetLocalized for anything a reader sees."},"planetLocalized":{"type":"string","example":"Marte","description":"Body name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat planet exactly."},"longitude":{"type":"number","example":83.4062,"description":"Tropical ecliptic longitude in degrees (0-360), measured from the vernal equinox. This is the Western zodiac, not the sidereal one, so the two differ by the ayanamsa of roughly 24 degrees."},"sign":{"type":"string","example":"Gemini","description":"Tropical zodiac sign the body occupies on this date. Always English, whatever the lang parameter says, so it stays safe to compare against in code. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Geminis","description":"Zodiac sign name in the requested language, for display. Present only when lang is set to a language other than English, since in English it would repeat sign exactly."},"degreeInSign":{"type":"number","example":23.4062,"description":"Degrees traversed within the current sign (0-30). Useful for precise transit tracking and for printing a position as sign plus degree."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the body is in apparent retrograde motion on this date. The lunar nodes are always retrograde and Black Moon Lilith is always direct."}},"required":["planet","longitude","sign","degreeInSign","isRetrograde"]},"description":"Tropical positions of all 14 Western bodies on this date at noon UTC."}},"required":["date","positions"]},"description":"Daily planetary position entries for the entire month."}},"required":["year","month","days"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/moon-phase/current":{"get":{"operationId":"getCurrentMoonPhase","tags":["Western Astrology"],"summary":"Get current moon phase - Lunar phase calculator with zodiac sign","description":"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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2025-12-18","description":"Date in YYYY-MM-DD format. Defaults to today if omitted."},"required":false,"description":"Date in YYYY-MM-DD format. Defaults to today if omitted.","name":"date","in":"query"},{"schema":{"type":"string","format":"time","example":"12:00:00","description":"Time in 24-hour HH:MM:SS format. Defaults to 12:00:00 (noon). Moon moves ~13 degrees per day so time affects phase precision."},"required":false,"description":"Time in 24-hour HH:MM:SS format. Defaults to 12:00:00 (noon). Moon moves ~13 degrees per day so time affects phase precision.","name":"time","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"IANA name (e.g. \"America/New_York\", \"Europe/London\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\"). IANA resolved to the DST-correct offset for the given date. Defaults to 0 (UTC)."},"required":false,"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\"). IANA resolved to the DST-correct offset for the given date. Defaults to 0 (UTC).","name":"timezone","in":"query"}],"responses":{"200":{"description":"Moon phase calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-18","description":"Date of this moon phase calculation (YYYY-MM-DD)."},"phase":{"type":"string","example":"Waxing Gibbous Moon","description":"Current lunar phase name. One of: New Moon, Waxing Crescent Moon, First Quarter Moon, Waxing Gibbous Moon, Full Moon, Waning Gibbous Moon, Last Quarter Moon, Waning Crescent Moon."},"illumination":{"type":"number","example":78.5,"description":"Moon illumination percentage (0-100). 0 = New Moon, 100 = Full Moon."},"age":{"type":"number","example":10.25,"description":"Lunar age in days since the last New Moon. Full lunation cycle is ~29.53 days."},"sign":{"type":"string","example":"Pisces","description":"Tropical zodiac sign the Moon currently occupies."},"degree":{"type":"number","example":15.42,"description":"Degree of the Moon within its current zodiac sign (0-29.999)."},"distance":{"type":"number","example":384400,"description":"Distance from Earth to the Moon in kilometers."},"meaning":{"type":"object","properties":{"name":{"type":"string","example":"Waxing Gibbous Moon","description":"Moon phase display name."},"symbol":{"type":"string","example":"🌔","description":"Moon phase emoji symbol."},"description":{"type":"string","description":"Astrological interpretation of this lunar phase and its influence on activities, emotions, and intentions.","example":"The waxing gibbous moon is there when we are close to our goals..."},"keywords":{"type":"array","items":{"type":"string"},"example":["assess","refine","perfect"],"description":"Key themes and activities aligned with this moon phase."},"energy":{"type":"string","enum":["waxing","waning","new","full"],"example":"waxing","description":"Lunar energy direction: waxing (building), waning (releasing), new (beginning), or full (culmination)."},"illumination":{"type":"string","example":"50-100% (Nearly Full)","description":"Illumination range description for this phase."}},"required":["name","symbol","description","keywords","energy","illumination"],"description":"Moon phase meaning and astrological interpretation. Includes energy direction, keywords, and guidance for this lunar phase."}},"required":["date","phase","illumination","age","sign","degree","distance"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/moon-phase/upcoming":{"get":{"operationId":"getUpcomingMoonPhases","tags":["Western Astrology"],"summary":"Get upcoming moon phases - Next new moon, full moon, quarters","description":"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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2025-12-18","description":"Start date in YYYY-MM-DD format. Defaults to today if omitted."},"required":false,"description":"Start date in YYYY-MM-DD format. Defaults to today if omitted.","name":"startDate","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":20,"default":8,"example":8,"description":"Number of upcoming moon phase transitions to return (1-20). Defaults to 8."},"required":false,"description":"Number of upcoming moon phase transitions to return (1-20). Defaults to 8.","name":"count","in":"query"}],"responses":{"200":{"description":"Upcoming moon phases retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"phases":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-26","description":"Date of this moon phase transition (YYYY-MM-DD)."},"phase":{"type":"string","example":"New Moon","description":"Lunar phase name (New Moon, First Quarter, Full Moon, Last Quarter)."}},"required":["date","phase"]},"description":"Upcoming moon phase transition dates in chronological order."}},"required":["phases"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/moon-phase/calendar/{year}/{month}":{"get":{"operationId":"getMoonCalendar","tags":["Western Astrology"],"summary":"Get lunar calendar - Moon phases for entire month","description":"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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"number","minimum":1900,"maximum":2100,"example":2026,"description":"Calendar year (1900-2100)."},"required":true,"description":"Calendar year (1900-2100).","name":"year","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":12,"example":3,"description":"Calendar month (1-12). 1 = January, 12 = December."},"required":true,"description":"Calendar month (1-12). 1 = January, 12 = December.","name":"month","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"responses":{"200":{"description":"Lunar calendar generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"number","example":2025,"description":"Calendar year for this lunar calendar."},"month":{"type":"number","example":12,"description":"Calendar month for this lunar calendar."},"monthName":{"type":"string","example":"December","description":"Month name, localized to the requested language. Saves the caller a lookup table when labelling a calendar heading, since the numeric month alone cannot be rendered without one."},"calendar":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2025-12-01","description":"Calendar date (YYYY-MM-DD)."},"phase":{"type":"string","example":"Waxing Crescent Moon","description":"Lunar phase name for this date."},"illumination":{"type":"number","example":5.2,"description":"Moon illumination percentage (0-100) at noon on this date."}},"required":["date","phase","illumination"]},"description":"Daily moon phase and illumination for every day of the month."}},"required":["year","month","monthName","calendar"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/synastry":{"post":{"operationId":"calculateSynastry","tags":["Western Astrology"],"summary":"Calculate synastry - Relationship compatibility analysis API","description":"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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"name":{"type":"string","example":"Alex","description":"Optional display name for this person. Included in the response for easy identification."}},"required":["date","time","latitude","longitude","timezone"]},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."},"name":{"type":"string","example":"Alex","description":"Optional display name for this person. Included in the response for easy identification."}},"required":["date","time","latitude","longitude","timezone"]},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for both natal charts. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["person1","person2"]}}}},"responses":{"200":{"description":"Synastry calculated successfully with compatibility analysis","content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"name":{"type":"string","example":"Alex","description":"Display name if provided in the request."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Taurus","description":"Ascendant (rising sign) of this person. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Tauro","description":"Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":15.32,"description":"Degree within the Ascendant sign (0-29.999)."}},"required":["sign","degree"],"description":"Ascendant position for person 1. Determines first house cusp and outward personality."},"sunSign":{"type":"string","example":"Cancer","description":"Sun sign (zodiac sign) of this person. Core identity and ego expression. Always English, whatever the lang parameter says. Use sunSignLocalized for anything a reader sees."},"sunSignLocalized":{"type":"string","example":"Cáncer","description":"Sun sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"moonSign":{"type":"string","example":"Pisces","description":"Moon sign of this person. Emotional nature and inner needs. Always English, whatever the lang parameter says. Use moonSignLocalized for anything a reader sees."},"moonSignLocalized":{"type":"string","example":"Piscis","description":"Moon sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet or point name. Matches the names used in interAspects. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sol","description":"Planet or point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","example":114.52,"description":"Ecliptic longitude in degrees (0-360) measured from 0 Aries. This is the value a wheel plots."},"sign":{"type":"string","example":"Cancer","description":"Zodiac sign containing the planet. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":24.52,"description":"Degree within the sign (0-29.999)."},"house":{"type":"number","example":3,"description":"House this planet occupies in the person 1 chart (1-12)."},"isRetrograde":{"type":"boolean","example":false,"description":"True when the planet is retrograde at this moment."}},"required":["name","longitude","sign","degree","house","isRetrograde"]},"description":"Planet positions for person 1, enough to render this side of a dual wheel without a second request. Per-planet interpretations are not repeated here; call the natal chart endpoint for an individual reading."}},"required":["ascendant","sunSign","moonSign","planets"],"description":"Person 1 chart highlights: Ascendant, Sun sign, Moon sign, and plotting positions."},"person2":{"type":"object","properties":{"name":{"type":"string","example":"Jordan","description":"Display name if provided in the request."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Ascendant (rising sign) of this person. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Virgo","description":"Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":22.18,"description":"Degree within the Ascendant sign (0-29.999)."}},"required":["sign","degree"],"description":"Ascendant position for person 2. Determines first house cusp and outward personality."},"sunSign":{"type":"string","example":"Pisces","description":"Sun sign (zodiac sign) of this person. Core identity and ego expression. Always English, whatever the lang parameter says. Use sunSignLocalized for anything a reader sees."},"sunSignLocalized":{"type":"string","example":"Piscis","description":"Sun sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"moonSign":{"type":"string","example":"Scorpio","description":"Moon sign of this person. Emotional nature and inner needs. Always English, whatever the lang parameter says. Use moonSignLocalized for anything a reader sees."},"moonSignLocalized":{"type":"string","example":"Escorpio","description":"Moon sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Sun","description":"Planet or point name. Matches the names used in interAspects. Always English, whatever the lang parameter says. Use nameLocalized for anything a reader sees."},"nameLocalized":{"type":"string","example":"Sol","description":"Planet or point name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"longitude":{"type":"number","example":114.52,"description":"Ecliptic longitude in degrees (0-360) measured from 0 Aries. This is the value a wheel plots."},"sign":{"type":"string","example":"Cancer","description":"Zodiac sign containing the planet. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","example":24.52,"description":"Degree within the sign (0-29.999)."},"house":{"type":"number","example":3,"description":"House this planet occupies in the person 2 chart (1-12)."},"isRetrograde":{"type":"boolean","example":false,"description":"True when the planet is retrograde at this moment."}},"required":["name","longitude","sign","degree","house","isRetrograde"]},"description":"Planet positions for person 2, enough to render this side of a dual wheel without a second request. Per-planet interpretations are not repeated here; call the natal chart endpoint for an individual reading."}},"required":["ascendant","sunSign","moonSign","planets"],"description":"Person 2 chart highlights: Ascendant, Sun sign, Moon sign, and plotting positions."},"compatibilityScore":{"type":"number","example":78,"description":"Overall compatibility score (0-100). Calculated from the balance of harmonious vs challenging inter-chart aspects weighted by planet importance."},"interAspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Venus","description":"Planet from person 1 chart. Always English, whatever the lang parameter says. Use planet1Localized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Venus","description":"Person 1 planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2":{"type":"string","example":"Mars","description":"Planet from person 2 chart. Always English, whatever the lang parameter says. Use planet2Localized for anything a reader sees."},"planet2Localized":{"type":"string","example":"Marte","description":"Person 2 planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"type":{"type":"string","example":"TRINE","description":"Aspect type (CONJUNCTION, OPPOSITION, TRINE, SQUARE, SEXTILE, etc.). Always English, whatever the lang parameter says. Use typeLocalized for anything a reader sees."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"angle":{"type":"number","example":120,"description":"Exact angle of this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Distance from exact aspect in degrees. Tighter orb means stronger influence."},"strength":{"type":"number","example":75,"description":"Aspect strength percentage (0-100) based on orb tightness."},"interpretation":{"type":"string","example":"harmonious","description":"Aspect nature: harmonious, challenging, or neutral."},"meaning":{"type":"object","properties":{"name":{"type":"string","example":"Trine","description":"Aspect display name."},"description":{"type":"object","properties":{"short":{"type":"string","example":"Planets in trine support each other. Trines, by nature, are accepting. They allow us to accept others, ourselves, and situations. The talents that trines offer a native are so natural that they are almost unconscious.","description":"Brief aspect description."},"long":{"type":"string","example":"These talents are second nature and completely natural. So, for example, if a chart has Venus trine Neptune, the native may be poetic, romantic, or artistic, and may easily accept a romantic partner for who they are.","description":"Detailed aspect description."}},"required":["short","long"],"description":"Aspect meaning in short and long form."},"keywords":{"type":"array","items":{"type":"string"},"example":["accept","accepting","difficult","natural","support","talent"],"description":"Keywords associated with this aspect type."},"nature":{"type":"string","example":"harmonious","description":"How this aspect type is characterised in its reference card, in the requested language, exactly like the name, description and keywords beside it. Branch on the aspect-level interpretation field instead, which is always English."},"relationshipContext":{"type":"string","example":"Strong physical and romantic attraction. Natural chemistry and mutual desire create magnetic pull between partners.","description":"How this specific planetary pair aspect manifests in relationships."}},"required":["name","description","keywords","nature","relationshipContext"],"description":"Aspect meaning with relationship-specific context for this planet pair."}},"required":["planet1","planet2","type","angle","orb","strength","interpretation"]},"description":"All inter-chart (synastry) aspects between person 1 and person 2 planets. Each aspect reveals a specific dynamic in the relationship."},"summary":{"type":"object","properties":{"total":{"type":"number","example":24,"description":"Total number of inter-chart aspects found."},"harmonious":{"type":"number","example":12,"description":"Count of harmonious aspects (trine, sextile). Natural ease and flow."},"challenging":{"type":"number","example":8,"description":"Count of challenging aspects (square, opposition). Dynamic tension and growth."},"neutral":{"type":"number","example":4,"description":"Count of neutral aspects (conjunction). Outcome depends on planets involved."},"byType":{"type":"object","additionalProperties":{"type":"number","example":5,"description":"Number of cross chart aspects of this type between the two charts. An aspect type with no hits is absent from the map rather than reported as zero."},"example":{"TRINE":5,"SEXTILE":7,"SQUARE":6,"OPPOSITION":2},"description":"Aspect count grouped by type. Shows which aspect patterns dominate the relationship."}},"required":["total","harmonious","challenging","neutral","byType"],"description":"Synastry aspect summary showing the balance of harmonious vs challenging inter-chart connections."},"analysis":{"type":"object","properties":{"overall":{"type":"string","example":"This relationship shows strong compatibility with genuine potential for lasting partnership. Most interactions feel natural and supportive, with a healthy mix of comfort and growth. Where challenges arise, both partners have the tools to work through them constructively.","description":"Overall relationship analysis narrative based on aspect patterns."},"strengths":{"type":"array","items":{"type":"string"},"example":["More harmonious aspects than challenging ones create a supportive foundation.","Harmonious Moon aspects indicate emotional understanding and nurturing.","Favorable Venus aspects bring affection, appreciation, and romantic chemistry."],"description":"Areas where the relationship naturally thrives based on harmonious aspects."},"challenges":{"type":"array","items":{"type":"string"},"example":["Challenging Sun aspects may create ego conflicts or competing life directions.","Challenging Mars aspects may bring tension, arguments, or competing desires."],"description":"Potential friction points and growth opportunities from challenging aspects."}},"required":["overall","strengths","challenges"],"description":"Relationship analysis with strengths, challenges, and overall assessment."}},"required":["person1","person2","compatibilityScore","interAspects","summary","analysis"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/houses":{"post":{"operationId":"calculateHouses","tags":["Western Astrology"],"summary":"Calculate house cusps - House system calculator with comparison","description":"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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Date is critical for house cusp calculations as it determines planetary positions used in some house systems."},"time":{"type":"string","format":"time","example":"14:30:00","description":"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."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). 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":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Affects local time and horizon calculations for house cusps."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC (e.g. -5 for EST, 5.5 for IST, 9 for JST) OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the chart date.","example":-5},"houseSystem":{"anyOf":[{"type":"string","enum":["placidus","whole-sign","equal","koch"]},{"type":"string","enum":["all"]}],"default":"placidus","example":"placidus","description":"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."}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"House cusps calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HousesResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/aspects":{"post":{"operationId":"calculateAspects","tags":["Western Astrology"],"summary":"Calculate planetary aspects - Aspect finder for any date and time","description":"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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectsRequest"}}}},"responses":{"200":{"description":"Aspects calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/aspect-patterns":{"post":{"operationId":"detectAspectPatterns","tags":["Western Astrology"],"summary":"Detect aspect patterns - Grand Trine, Kite, T-Square, Grand Cross, Yod, Mystic Rectangle, Stellium","description":"Identify classical Western astrology multi-planet configurations in a birth chart. Returns Grand Trines (with element), Kites (with apex), T-Squares (with apex and modality), Grand Crosses (with modality), Yods (Finger of Fate, with apex), Mystic Rectangles, and Stelliums. Each pattern carries a tightness score (0-100), dissociate flag for out-of-sign configurations, and a one-line interpretation suitable for chart reports. Disambiguation is built in: a Grand Cross suppresses its contained T-Squares, a Kite suppresses its underlying Grand Trine. Useful for personalized natal report engines, astrology chatbots, AI agents that interpret chart geometry, and editorial chart-pattern callouts.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","example":"false","description":"Use tighter orbs (Pontopia \"optimal\" recommendations). Truthy values (true, 1, yes, on; case-insensitive) narrow trine to 5, square to 5, sextile to 4, quincunx to 2. Defaults to false (industry-standard orbs)."},"required":false,"description":"Use tighter orbs (Pontopia \"optimal\" recommendations). Truthy values (true, 1, yes, on; case-insensitive) narrow trine to 5, square to 5, sextile to 4, quincunx to 2. Defaults to false (industry-standard orbs).","name":"strictOrbs","in":"query"},{"schema":{"type":"string","example":"","description":"Comma-separated list of optional bodies to include beyond the classical 10 planets. Valid tokens (case-insensitive): chiron, northNode (also accepts north_node, north-node, northnode). Empty by default."},"required":false,"description":"Comma-separated list of optional bodies to include beyond the classical 10 planets. Valid tokens (case-insensitive): chiron, northNode (also accepts north_node, north-node, northnode). Empty by default.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectPatternsRequest"}}}},"responses":{"200":{"description":"Aspect patterns detected successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AspectPatternsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/transits":{"post":{"operationId":"calculateTransits","tags":["Western Astrology"],"summary":"Calculate planetary transits - Current transits with natal chart comparison","description":"Calculate current or future planetary transits (positions of all bodies now). Optionally compare transits to natal chart to find transit-to-natal aspects. Returns all 14 celestial bodies (the 10 classical planets, the lunar nodes, Chiron, and Black Moon Lilith) 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.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitsRequest"}}}},"responses":{"200":{"description":"Transits calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/transit-aspects":{"post":{"operationId":"calculateTransitAspects","tags":["Western Astrology"],"summary":"Transit Aspects - Detailed transit-to-natal aspect analysis with interpretations","description":"Calculate all transit-to-natal aspects with detailed interpretations, strength ratings, and timing guidance. Compares current (or future) planetary positions against your natal chart to identify active transits. Returns aspect type, orb, applying/separating status, narrative interpretation, impact rating, and practical guidance for each transit. Supports planet and aspect-type filtering. More detailed than the /transits endpoint — includes AI-friendly interpretation fields. Transit aspects API, transit-to-natal analysis, predictive astrology, personalized transit forecast.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"natalChart":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"Natal chart birth details (date, time, location, timezone). Used to calculate natal planetary positions that transits are compared against."},"transitDate":{"type":"string","format":"date","example":"2026-02-03","description":"Transit date in YYYY-MM-DD format. Defaults to current date if omitted. Use future dates for predictive transit analysis."},"transitTime":{"type":"string","format":"time","example":"12:00:00","description":"Transit time in HH:MM:SS format. Defaults to 12:00:00 (noon) if omitted."},"planets":{"type":"array","items":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"]},"example":["Jupiter","Saturn","Pluto"],"description":"Filter to specific transiting planets. Omit to include all planets. Useful for focusing on slow-moving outer planet transits (Saturn, Jupiter, Pluto)."},"aspectTypes":{"type":"array","items":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"]},"example":["CONJUNCTION","OPPOSITION","TRINE","SQUARE"],"description":"Filter to specific aspect types (conjunction, opposition, trine, square, sextile, etc.). Omit to include all aspect types."},"minStrength":{"type":"number","minimum":0,"maximum":100,"example":50,"description":"Minimum aspect strength threshold (0-100). Higher values return only tighter, more potent aspects. Useful for filtering out wide-orb aspects."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system used to divide the natal chart into 12 houses. Every house number in the response is read against these natal cusps, for the natal bodies and the transiting bodies alike. Placidus (default) is time sensitive and the most widely used in Western astrology. Whole Sign assigns one sign per house. Equal divides into 30 degree segments from the Ascendant. Koch emphasizes higher latitudes. Quadrant systems fall back to Whole Sign above the polar circle."}},"required":["natalChart"]}}}},"responses":{"200":{"description":"Transit aspects calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transitDate":{"type":"string","example":"2026-02-03 12:00:00","description":"Date and time of the transit calculation."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system actually used for the natal cusps behind every house number in this response. Differs from the requested system only above the polar circle, where quadrant systems fall back to Whole Sign."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."},"signLocalized":{"type":"string","example":"Tauro","description":"Zodiac sign name on this cusp in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["number","longitude","sign","degree"]},"description":"The twelve NATAL house cusps that every house number in this response is read against, in the house system named by houseSystem. Same shape as the natal-chart houses array, so a bi-wheel can be drawn with real house sectors from this one response instead of pairing it with a second call."},"ascendant":{"type":"object","properties":{"sign":{"type":"string","example":"Taurus","description":"Tropical zodiac sign on the natal Ascendant. Always English, whatever the lang parameter says. Use signLocalized for anything a reader sees."},"signLocalized":{"type":"string","example":"Tauro","description":"Ascendant sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the Ascendant sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Absolute ecliptic longitude of the natal Ascendant in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"The natal Ascendant (rising sign): the eastern horizon at birth, and the left-hand horizon a chart wheel is oriented to. Reported alongside the cusps because the two are not the same longitude in every house system: Whole Sign puts the first cusp at 0 degrees of the rising sign, which can sit most of a sign away from the Ascendant itself."},"transitPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":10,"description":"Natal house (1-12) this transiting body is currently passing through, read against the natal house cusps. This is the life area the transit activates, so it is driven by the natal birth time and location rather than by the transit moment."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."},"nameLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"Current transiting positions in the tropical zodiac, each placed in the natal house it is passing through. All 14 celestial bodies: the 10 classical planets (Sun through Pluto), the lunar nodes, Chiron, and Black Moon Lilith."},"natalPlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."},"nameLocalized":{"type":"string","example":"Sol","description":"Body name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"signLocalized":{"type":"string","example":"Cáncer","description":"Zodiac sign name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"Natal (birth chart) planetary positions used as the baseline for transit aspect comparison, each placed in its natal house."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Sol","description":"First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2Localized":{"type":"string","example":"Luna","description":"Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"transitInterpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun supports your natal Moon harmoniously","description":"Narrative interpretation of this transit aspect and its life impact."},"timing":{"type":"string","example":"Active for a few days","description":"When this transit is most active and how long its influence lasts, localized. The bucket follows the speed of the transiting body: a few hours for the Moon, a few days for the Sun, Mercury, Venus and Mars, one to two weeks for Jupiter, several weeks for Saturn, and an extended period for Uranus, Neptune and Pluto."},"impact":{"type":"string","example":"Self-awareness and ego flows easily with Inner emotional life. Opportunities arise naturally in this area.","description":"Strength and nature of this transit effect — constructive, challenging, or neutral."},"guidance":{"type":"string","example":"Take advantage of this supportive energy. Things flow easily, so act on opportunities.","description":"Practical advice for working with this transit energy."},"keywords":{"type":"array","items":{"type":"string"},"example":["accept","accepting","difficult","natural","support","talent"],"description":"Key themes activated by this transit aspect."}},"required":["summary","timing","impact","guidance","keywords"],"description":"Rich interpretation of the transit aspect: narrative summary, timing, impact assessment, practical guidance, and keywords."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation","transitInterpretation"]},"description":"Transit-to-natal aspects with interpretations, strength ratings, and guidance. Each aspect represents a transiting planet forming a geometric angle to a natal planet."},"summary":{"type":"object","properties":{"total":{"type":"number","example":12,"description":"Total number of transit-to-natal aspects found."},"harmonious":{"type":"number","example":5,"description":"Count of harmonious aspects (trine, sextile). These transits bring ease, flow, and opportunity."},"challenging":{"type":"number","example":4,"description":"Count of challenging aspects (square, opposition, semi-square, sesquiquadrate). These transits bring tension, growth pressure, and action."},"neutral":{"type":"number","example":3,"description":"Count of neutral aspects (conjunction, minor aspects). Conjunctions blend energies — the outcome depends on the planets involved."},"strongest":{"type":["object","null"],"properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."},"planet1Localized":{"type":"string","example":"Sol","description":"First planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"planet2Localized":{"type":"string","example":"Luna","description":"Second planet name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"typeLocalized":{"type":"string","example":"Trígono","description":"Aspect type name in the requested language, for display only. Present only when lang is set to a language other than English, since in English it would repeat its canonical partner field exactly. Never compare against this value, compare against the canonical field beside it."},"transitInterpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun supports your natal Moon harmoniously","description":"Narrative interpretation of this transit aspect and its life impact."},"timing":{"type":"string","example":"Active for a few days","description":"When this transit is most active and how long its influence lasts, localized. The bucket follows the speed of the transiting body: a few hours for the Moon, a few days for the Sun, Mercury, Venus and Mars, one to two weeks for Jupiter, several weeks for Saturn, and an extended period for Uranus, Neptune and Pluto."},"impact":{"type":"string","example":"Self-awareness and ego flows easily with Inner emotional life. Opportunities arise naturally in this area.","description":"Strength and nature of this transit effect — constructive, challenging, or neutral."},"guidance":{"type":"string","example":"Take advantage of this supportive energy. Things flow easily, so act on opportunities.","description":"Practical advice for working with this transit energy."},"keywords":{"type":"array","items":{"type":"string"},"example":["accept","accepting","difficult","natural","support","talent"],"description":"Key themes activated by this transit aspect."}},"required":["summary","timing","impact","guidance","keywords"],"description":"Rich interpretation of the transit aspect: narrative summary, timing, impact assessment, practical guidance, and keywords."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation","transitInterpretation"],"description":"The tightest aspect by orb. This is the most potent transit currently active — the one most likely to be felt."},"byType":{"type":"object","additionalProperties":{"type":"number","example":3,"description":"Number of transit to natal aspects of this type in the window. An aspect type with no hits is absent from the map rather than reported as zero."},"example":{"CONJUNCTION":2,"TRINE":3,"SQUARE":2,"SEXTILE":1},"description":"Transit aspect counts grouped by aspect type (conjunction, trine, square, opposition, sextile, etc.). Useful for quickly assessing the transit weather."}},"required":["total","harmonious","challenging","neutral","strongest","byType"],"description":"Statistical summary of all transit aspects. The harmonious-to-challenging ratio reveals the overall transit weather — whether the current period favors ease or demands effort."}},"required":["transitDate","houseSystem","houses","ascendant","transitPlanets","natalPlanets","aspects","summary"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/solar-return":{"post":{"operationId":"generateSolarReturn","tags":["Western Astrology"],"summary":"Solar Return Chart - Annual birthday forecast with relocated chart","description":"Generate a solar return chart for any year, the foundational technique for annual astrological forecasting. The chart is cast for the exact moment the transiting Sun returns to its natal ecliptic longitude (your astrological birthday). Returns full tropical zodiac chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Location-sensitive: relocating your solar return chart to a different city changes the houses and Ascendant. Solar return chart API, annual horoscope forecast, birthday chart calculator, yearly astrology prediction, relocated solar return.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Original birth date in YYYY-MM-DD format. Used to determine natal Sun longitude for the solar return calculation."},"birthTime":{"type":"string","format":"time","example":"14:30:00","description":"Original birth time in 24-hour HH:MM:SS format. Determines exact natal Sun position for annual return timing."},"returnYear":{"type":"integer","example":2026,"description":"Year for which to cast the solar return chart. The chart is erected for the exact moment the transiting Sun conjuncts the natal Sun longitude in this year."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Latitude of the solar return location in decimal degrees (-90 to 90). Use current residence or travel location at time of birthday. Solar return charts are location-sensitive."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Longitude of the solar return location in decimal degrees (-180 to 180). Affects house cusps and Ascendant of the return chart."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the birthDate. Output datetime is adjusted to this timezone.","example":-5},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the solar return chart. Placidus (default) is most common in Western astrology. Whole Sign, Equal, and Koch also supported."}},"required":["birthDate","birthTime","returnYear","latitude","longitude","timezone"]},"example":{"birthDate":"1990-07-15","birthTime":"14:30:00","returnYear":2024,"latitude":40.7128,"longitude":-74.006,"timezone":-5,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Solar return chart calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Original birth date used for natal Sun longitude calculation."},"solarReturnDate":{"type":"string","example":"2026-07-15T08:42:00","description":"Exact solar return moment, when the transiting Sun conjuncts the natal Sun longitude. Adjusted to requested timezone. This is your astrological birthday for the year."},"solarReturnYear":{"type":"number","example":2026,"description":"Year of this solar return chart. Covers the period from this birthday to the next."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":40.7128,"description":"Observer latitude used for Placidus house cusp and Ascendant calculation in the solar return chart."},"longitude":{"type":"number","example":-74.006,"description":"Observer longitude used for local sidereal time and Midheaven calculation in the solar return chart."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to output datetime formatting."}},"required":["latitude","longitude","timezone"],"description":"Location used for the solar return chart. The Ascendant and house cusps change based on where you are at your birthday, a key technique in relocated solar returns."},"chart":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details used to generate this chart."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps calculated using the selected house system."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."}},"required":["birthDetails","planets","houses","houseSystem","aspects","partOfFortune","vertex"],"description":"Full natal-style chart erected for the solar return moment. Contains all 14 celestial bodies (10 classical planets, lunar nodes, Chiron, Black Moon Lilith), 12 house cusps, aspects, Ascendant, and Midheaven in the tropical zodiac."},"natalSunPosition":{"type":"object","properties":{"longitude":{"type":"number","example":112.45,"description":"Natal Sun ecliptic longitude in degrees (0-360). The transiting Sun returns to this exact degree each year."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign of the natal Sun (your Sun sign)."},"degree":{"type":"number","example":22.45,"description":"Degree within the zodiac sign (0-29.999). The precise position the Sun returns to."}},"required":["longitude","sign","degree"],"description":"Original natal Sun position that the transiting Sun returns to. This conjunction defines the solar return moment."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Solar Return chart for your 2026 birthday year. This chart is cast for the exact moment the Sun returns to its natal position, symbolizing a new solar year.","description":"Narrative overview of the solar return year themes and energy."},"purpose":{"type":"string","example":"Solar return charts are used for annual forecasting. The chart reveals themes, opportunities, and challenges for the year ahead from birthday to birthday. Focus on the Ascendant sign, angular planets, and aspects to natal positions.","description":"Explanation of how to use solar return charts for annual forecasting, identifying yearly themes, and timing predictions."},"keyThemes":{"type":"array","items":{"type":"string"},"example":["Annual themes and life direction","Career and public life developments","Relationships and partnerships","Personal growth and self-expression","Home and family matters"],"description":"Key life areas and themes highlighted by this solar return chart. Focus on these for the birthday year."}},"required":["summary","purpose","keyThemes"],"description":"Solar return interpretation with annual forecast themes. Solar returns are the primary technique in Western astrology for year-ahead predictions."}},"required":["birthDate","solarReturnDate","solarReturnYear","location","chart","natalSunPosition","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/lunar-return":{"post":{"operationId":"generateLunarReturn","tags":["Western Astrology"],"summary":"Lunar Return Chart - Monthly emotional forecast with Moon cycle chart","description":"Generate a lunar return chart for any month, cast for the exact moment the transiting Moon returns to its natal ecliptic longitude. The Moon completes one sidereal orbit every ~27.3 days, making this the primary technique for monthly astrological forecasting. Returns full tropical zodiac chart with planetary positions, house cusps, aspects, Ascendant, and Midheaven. Reveals emotional patterns, domestic focus, and intuitive themes for the coming month. Lunar return chart API, monthly horoscope forecast, Moon cycle chart, emotional astrology prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Original birth date in YYYY-MM-DD format. Used to determine natal Moon longitude for the lunar return calculation."},"birthTime":{"type":"string","format":"time","example":"14:30:00","description":"Original birth time in 24-hour HH:MM:SS format. Determines exact natal Moon position for monthly return timing."},"returnDate":{"type":"string","format":"date","example":"2026-02-12","description":"Approximate date near the desired lunar return (YYYY-MM-DD). The Moon returns to its natal position every ~27.3 days, so provide a date within a few days of the expected return."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Latitude of the lunar return location in decimal degrees (-90 to 90). Affects the Ascendant and house cusps of the return chart."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Longitude of the lunar return location in decimal degrees (-180 to 180). Determines local sidereal time for house calculations."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the birthDate. Output datetime is adjusted to this timezone.","example":-5},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the lunar return chart. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["birthDate","birthTime","returnDate","latitude","longitude","timezone"]},"example":{"birthDate":"1990-07-15","birthTime":"14:30:00","returnDate":"2024-08-12","latitude":40.7128,"longitude":-74.006,"timezone":-5,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Lunar return chart calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Original birth date used for natal Moon longitude calculation."},"lunarReturnDate":{"type":"string","example":"2026-02-13T19:22:00","description":"Exact lunar return moment, when the transiting Moon conjuncts the natal Moon longitude. Adjusted to requested timezone. Occurs approximately every 27.3 days (one sidereal month)."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":40.7128,"description":"Observer latitude used for house cusp calculation in the lunar return chart."},"longitude":{"type":"number","example":-74.006,"description":"Observer longitude used for local sidereal time and Midheaven in the return chart."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to output datetime formatting."}},"required":["latitude","longitude","timezone"],"description":"Location used for the lunar return chart house and Ascendant calculations."},"chart":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details used to generate this chart."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps calculated using the selected house system."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."}},"required":["birthDetails","planets","houses","houseSystem","aspects","partOfFortune","vertex"],"description":"Full tropical zodiac chart erected for the lunar return moment. Contains planetary positions, house cusps, aspects, Ascendant, and Midheaven."},"natalMoonPosition":{"type":"object","properties":{"longitude":{"type":"number","example":228.72,"description":"Natal Moon ecliptic longitude in degrees (0-360). The transiting Moon returns to this position each month."},"sign":{"type":"string","example":"Scorpio","description":"Tropical zodiac sign of the natal Moon."},"degree":{"type":"number","example":18.72,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["longitude","sign","degree"],"description":"Original natal Moon position that the transiting Moon returns to. This conjunction defines the lunar return moment."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Lunar Return chart for this month. This chart is cast for the exact moment the Moon returns to its natal position, occurring approximately every 27-28 days.","description":"Narrative overview of the monthly emotional themes and lunar cycle focus areas."},"purpose":{"type":"string","example":"Lunar return charts are used for monthly forecasting. The chart reveals themes, emotional patterns, and focus areas for the coming month. Pay attention to the Moon house position and aspects to other planets for emotional tone and priorities.","description":"Explanation of how to use lunar return charts for monthly emotional forecasting and self-care planning."},"keyThemes":{"type":"array","items":{"type":"string"},"example":["Emotional patterns and inner needs","Domestic and family matters","Daily routines and habits","Intuition and subconscious patterns","Self-care and nurturing"],"description":"Key emotional patterns, domestic themes, and self-care priorities for this lunar month."}},"required":["summary","purpose","keyThemes"],"description":"Lunar return interpretation with monthly forecast. Lunar returns reveal emotional patterns, domestic focus, and intuitive themes for the upcoming ~27-day cycle."}},"required":["birthDate","lunarReturnDate","location","chart","natalMoonPosition","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/composite-chart":{"post":{"operationId":"generateCompositeChart","tags":["Western Astrology"],"summary":"Composite Chart - Midpoint relationship chart with interpretations","description":"Generate a composite chart by calculating midpoints between two natal charts. The composite chart represents the relationship as a single entity, showing its core identity, emotional bond, communication style, and growth direction. Uses the midpoint method: planets, angles and house cusps are each the midpoint of the two natal values, so the Ascendant always sits on the first cusp. Returns composite planetary positions, house cusps, Ascendant, Midheaven, aspects, and relationship interpretation. Composite chart API, midpoint chart calculator, relationship astrology, couple chart analysis.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"First person birth details (date, time, location, timezone)."},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"Second person birth details (date, time, location, timezone)."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the composite chart. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["person1","person2"]},"example":{"person1":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":-5},"person2":{"date":"1992-03-20","time":"09:15:00","latitude":34.0522,"longitude":-118.2437,"timezone":-8},"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Composite chart calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"First person birth details."},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Second person birth details."},"compositePlanets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."},"compositeInterpretation":{"type":"object","properties":{"summary":{"type":"string","example":"Sun in Cancer (Crab) brings intuitive, nurturing, protective energy to the themes of self-awareness and ego. This placement gives your Sun expression a distinctly Cancer character, shaping how you navigate these areas of life.","description":"Narrative interpretation of this composite planet placement."},"relationshipMeaning":{"type":"string","example":"The composite Sun in cancer represents the core identity and purpose of your relationship. This is what you create together and how others see you as a couple.","description":"What this planet represents in the context of the relationship."},"keywords":{"type":"array","items":{"type":"string"},"example":["active","awareness","bright","confidence","consciousness","intuitive","nurturing","protective"],"description":"Key themes associated with this composite placement."}},"required":["summary","relationshipMeaning","keywords"],"description":"Composite interpretation for this planet in the relationship chart."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"Composite planetary positions calculated as midpoints between both charts. Each planet represents a shared energy in the relationship."},"compositeHouses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":1,"description":"House number (1-12) in the composite chart."},"sign":{"type":"string","example":"Gemini","description":"Zodiac sign on the composite house cusp."},"degree":{"type":"number","example":15.32,"description":"Degree within the zodiac sign (0-29.999)."},"longitude":{"type":"number","example":75.32,"description":"Absolute ecliptic longitude in degrees (0-360)."}},"required":["number","sign","degree","longitude"]},"description":"Composite house cusps, each the midpoint of the two natal cusps. Each house represents shared life areas in the relationship."},"compositeAscendant":{"type":"object","properties":{"sign":{"type":"string","example":"Gemini","description":"Zodiac sign on the composite Ascendant."},"degree":{"type":"number","example":15.32,"description":"Degree within the sign (0-29.999)."},"longitude":{"type":"number","example":75.32,"description":"Absolute ecliptic longitude in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Composite Ascendant. Represents how the relationship presents itself to the outside world."},"compositeMidheaven":{"type":"object","properties":{"sign":{"type":"string","example":"Aquarius","description":"Zodiac sign on the composite Midheaven."},"degree":{"type":"number","example":8.76,"description":"Degree within the sign (0-29.999)."},"longitude":{"type":"number","example":308.76,"description":"Absolute ecliptic longitude in degrees (0-360)."}},"required":["sign","degree","longitude"],"description":"Composite Midheaven (MC). Represents shared goals, public image, and the direction the relationship grows toward."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"Aspects between composite planets. Reveals the internal dynamics and energy patterns within the relationship."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"This relationship has strong harmonious energy with natural flow and compatibility.","description":"Overall relationship interpretation based on composite chart analysis."},"strengths":{"type":"array","items":{"type":"string"},"example":["The composite Sun in cancer represents the core identity and purpose of your relationship. This is what you create together and how others see you as a couple.","The composite Moon in aquarius shows your emotional bond and how you nurture each other. This reveals your shared feelings and domestic life together.","The composite Venus in taurus reveals what you value together and how you express affection. This is the love language of your relationship."],"description":"Areas where the relationship naturally thrives."},"challenges":{"type":"array","items":{"type":"string"},"example":["More challenging aspects than harmonious - requires work and understanding."],"description":"Potential friction points and growth opportunities in the relationship."}},"required":["summary","strengths","challenges"],"description":"Composite chart interpretation with relationship strengths, challenges, and overall assessment."}},"required":["person1","person2","compositePlanets","compositeHouses","compositeAscendant","compositeMidheaven","aspects","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/compatibility-score":{"post":{"operationId":"calculateCompatibility","tags":["Western Astrology"],"summary":"Compatibility Score. Relationship compatibility analysis with category breakdown","description":"Calculate a detailed compatibility score between two birth charts using Western synastry (inter-chart aspects). Returns overall score (0-100) plus category breakdowns for romantic, emotional, intellectual, physical, and spiritual compatibility. Each category analyzes specific planetary pairs: Venus-Mars for romance, Moon-Moon for emotions, Mercury-Mercury for intellect. Includes Sun, Moon, Venus, and Mars sign compatibility narratives, element balance analysis, relationship archetype classification, and the most significant inter-chart aspects with relationship-specific interpretations.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"person1":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"First person birth details (date, time, location, timezone). Required for calculating natal planetary positions."},"person2":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"],"description":"Second person birth details. Compared against person1 to evaluate inter-chart aspects and compatibility."}},"required":["person1","person2"]},"example":{"person1":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":-5},"person2":{"date":"1992-03-20","time":"09:15:00","latitude":34.0522,"longitude":-118.2437,"timezone":-8}}}}},"responses":{"200":{"description":"Compatibility score calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"overallScore":{"type":"number","minimum":0,"maximum":100,"example":72,"description":"Overall compatibility score (0-100). Weighted average across romantic, emotional, intellectual, physical, and spiritual categories."},"categories":{"type":"object","properties":{"romantic":{"type":"number","minimum":0,"maximum":100,"example":78,"description":"Romantic compatibility score based on Sun-Moon, Venus-Mars, and Sun-Venus inter-aspects."},"emotional":{"type":"number","minimum":0,"maximum":100,"example":65,"description":"Emotional compatibility score based on Moon-Moon and Moon-Venus inter-aspects."},"intellectual":{"type":"number","minimum":0,"maximum":100,"example":70,"description":"Intellectual compatibility score based on Mercury-Mercury and Sun-Mercury inter-aspects."},"physical":{"type":"number","minimum":0,"maximum":100,"example":80,"description":"Physical compatibility score based on Mars-Mars and Mars-Sun inter-aspects."},"spiritual":{"type":"number","minimum":0,"maximum":100,"example":60,"description":"Spiritual compatibility score based on Jupiter-Sun and Jupiter-Jupiter inter-aspects."}},"required":["romantic","emotional","intellectual","physical","spiritual"],"description":"Compatibility breakdown by life area. Each category evaluates specific planetary pair interactions that govern that domain."},"persons":{"type":"object","properties":{"person1":{"type":"object","properties":{"sun":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Sun sign position. Core identity and ego."},"moon":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Moon sign position. Emotional nature and instincts."},"venus":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Venus sign position. Love language and relationship style."},"mars":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Mars sign position. Passion, desire, and conflict style."}},"required":["sun","moon","venus","mars"],"description":"Key planet positions for person 1. Sun, Moon, Venus, and Mars sign placements."},"person2":{"type":"object","properties":{"sun":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Sun sign position. Core identity and ego."},"moon":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Moon sign position. Emotional nature and instincts."},"venus":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Venus sign position. Love language and relationship style."},"mars":{"type":"object","properties":{"sign":{"type":"string","example":"gemini","description":"Zodiac sign this planet occupies in the tropical zodiac."},"degree":{"type":"number","example":24.5,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["sign","degree"],"description":"Mars sign position. Passion, desire, and conflict style."}},"required":["sun","moon","venus","mars"],"description":"Key planet positions for person 2. Sun, Moon, Venus, and Mars sign placements."}},"required":["person1","person2"],"description":"Summary of key planetary positions for both people. Includes the four planets most relevant to relationship compatibility."},"signCompatibility":{"type":"object","properties":{"sun":{"type":"object","properties":{"person1Sign":{"type":"string","example":"Taurus","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"Scorpio","description":"Person 2 sign for this planet."},"description":{"type":"string","example":"Taurus and Scorpio combine earth and water core energy. Naturally nurturing and fertile. Water nourishes steady growth while Earth provides a stable container. This combination creates deep security and emotional safety. Your modalities (fixed and fixed) add another layer: Deeply committed and determined. Shared resolve can move mountains, though finding room for compromise keeps the relationship from becoming a standoff.","description":"Narrative analysis of how these two signs interact through this planet."}},"required":["person1Sign","person2Sign","description"],"description":"Sun sign compatibility. Reveals core personality dynamic as a couple."},"moon":{"type":"object","properties":{"person1Sign":{"type":"string","example":"Aquarius","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"Pisces","description":"Person 2 sign for this planet."},"description":{"type":"string","example":"Aquarius Moon and Pisces Moon bring together air and water emotional natures. Thought meets feeling. Air brings objectivity and perspective while Water brings emotional depth and intuition. Honoring both rational and emotional ways of knowing strengthens this bond.","description":"Narrative analysis of how these two signs interact through this planet."}},"required":["person1Sign","person2Sign","description"],"description":"Moon sign compatibility. Reveals how you process emotions and nurture each other."},"venus":{"type":"object","properties":{"person1Sign":{"type":"string","example":"Aries","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"Scorpio","description":"Person 2 sign for this planet."},"description":{"type":"string","example":"Venus in Aries and Venus in Scorpio blend fire and water love styles. Passion meets emotional depth. This powerful chemistry creates transformation when balanced. Directness and sensitivity learn from each other, forging a connection that is both warm and soulful.","description":"Narrative analysis of how these two signs interact through this planet."}},"required":["person1Sign","person2Sign","description"],"description":"Venus sign compatibility. Reveals love languages and what you find beautiful together."},"mars":{"type":"object","properties":{"person1Sign":{"type":"string","example":"Gemini","description":"Person 1 sign for this planet."},"person2Sign":{"type":"string","example":"Sagittarius","description":"Person 2 sign for this planet."},"description":{"type":"string","example":"Mars in Gemini and Mars in Sagittarius combine air and fire approaches to desire and conflict. Highly energizing and dynamic. Air fuels Fire with ideas and enthusiasm, creating an intellectually stimulating and active connection full of momentum.","description":"Narrative analysis of how these two signs interact through this planet."}},"required":["person1Sign","person2Sign","description"],"description":"Mars sign compatibility. Reveals how you handle passion, conflict, and desire."}},"required":["sun","moon","venus","mars"],"description":"Sign-by-sign compatibility analysis for the four key relationship planets. Each entry describes how the two signs interact through that planetary lens."},"elementBalance":{"type":"object","properties":{"person1":{"type":"object","properties":{"fire":{"type":"number","example":3,"description":"Count of planets in fire signs (Aries, Leo, Sagittarius)."},"earth":{"type":"number","example":2,"description":"Count of planets in earth signs (Taurus, Virgo, Capricorn)."},"air":{"type":"number","example":4,"description":"Count of planets in air signs (Gemini, Libra, Aquarius)."},"water":{"type":"number","example":3,"description":"Count of planets in water signs (Cancer, Scorpio, Pisces)."}},"required":["fire","earth","air","water"],"description":"Element distribution across person 1 natal planets."},"person2":{"type":"object","properties":{"fire":{"type":"number","example":3,"description":"Count of planets in fire signs (Aries, Leo, Sagittarius)."},"earth":{"type":"number","example":2,"description":"Count of planets in earth signs (Taurus, Virgo, Capricorn)."},"air":{"type":"number","example":4,"description":"Count of planets in air signs (Gemini, Libra, Aquarius)."},"water":{"type":"number","example":3,"description":"Count of planets in water signs (Cancer, Scorpio, Pisces)."}},"required":["fire","earth","air","water"],"description":"Element distribution across person 2 natal planets."},"sharedElement":{"type":["string","null"],"example":"water","description":"Dominant element shared by both charts, or null if dominant elements differ."},"description":{"type":"string","example":"Both charts share a dominant water element, creating natural resonance and instinctive understanding in how you approach life together.","description":"How the elemental balance between charts shapes the relationship dynamic."}},"required":["person1","person2","sharedElement","description"],"description":"Elemental balance comparison. Shows how fire, earth, air, and water energy is distributed across both charts."},"archetype":{"type":"object","properties":{"label":{"type":"string","example":"Kindred Spirits","description":"Relationship archetype label. A headline-friendly label for the dynamic."},"description":{"type":"string","example":"A natural understanding flows between you. Similar values and rhythms create a relationship that feels effortless and deeply familiar.","description":"Narrative description of the relationship archetype and what it means."}},"required":["label","description"],"description":"Relationship archetype based on score pattern, category strengths, and elemental balance. One of eight archetypes: Kindred Spirits, Opposites Attract, The Power Couple, The Nurturers, The Adventurers, Growth Partners, The Balancers, The Mystics."},"strengths":{"type":"array","items":{"type":"string"},"example":["Venus-Mars Trine: Strong physical and romantic attraction. Natural chemistry and mutual desire create magnetic pull between partners.","Sun-Pluto Trine: Sun and Pluto connect harmoniously, creating natural ease in how self-awareness and ego blends with sex, death, and transformation.","Chiron-Moon Trine: Chiron and Moon connect harmoniously, creating natural ease in how healing and inner wounds blends with inner emotional life."],"description":"Top relationship strengths based on harmonious inter-chart aspects. Each includes the planet pair, aspect type, and relationship-specific interpretation."},"challenges":{"type":"array","items":{"type":"string"},"example":["Pluto-Saturn Square: Pluto and Saturn create dynamic tension between sex, death, and transformation and responsibility, time, and routine. Conscious effort transforms this friction into growth.","Chiron-Neptune Opposition: Chiron and Neptune create dynamic tension between healing and inner wounds and dreams, healing, and intuition. Conscious effort transforms this friction into growth."],"description":"Potential friction points based on challenging inter-chart aspects. Each includes specific guidance for navigating the tension."},"summary":{"type":"string","example":"Compatibility score: 72/100 (very good). The 18 aspects between your charts reveal 8 harmonious connections and 6 challenging dynamics.","description":"Narrative overview of the relationship compatibility, highlighting the dominant themes."},"interpretation":{"type":"string","example":"This relationship shows strong compatibility with genuine potential for lasting partnership. Most interactions feel natural and supportive, with a healthy mix of comfort and growth. Where challenges arise, both partners have the tools to work through them constructively. The overall energy favors building something meaningful together.","description":"Detailed compatibility interpretation analyzing the synastry aspect patterns between both charts."},"aspectBreakdown":{"type":"object","properties":{"total":{"type":"number","example":18,"description":"Total number of inter-chart aspects found between the two natal charts."},"harmonious":{"type":"number","example":8,"description":"Count of harmonious aspects (trine, sextile). These indicate natural ease and flow."},"challenging":{"type":"number","example":6,"description":"Count of challenging aspects (square, opposition). These create dynamic tension and growth."},"neutral":{"type":"number","example":4,"description":"Count of neutral aspects (conjunction). Outcome depends on the planets involved."}},"required":["total","harmonious","challenging","neutral"],"description":"Synastry aspect breakdown showing the balance of harmonious, challenging, and neutral inter-chart aspects."},"keyAspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","example":"Venus","description":"First planet in the aspect."},"planet2":{"type":"string","example":"Mars","description":"Second planet in the aspect."},"type":{"type":"string","example":"TRINE","description":"Aspect type (conjunction, trine, square, etc.)."},"orb":{"type":"number","example":2.3,"description":"Deviation from exact aspect in degrees. Tighter orb = stronger influence."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious flows easily. Challenging creates growth-oriented tension."},"description":{"type":"string","example":"Strong physical and romantic attraction. Natural chemistry and mutual desire create magnetic pull between partners.","description":"Relationship-specific interpretation of this aspect between the two charts."}},"required":["planet1","planet2","type","orb","interpretation","description"]},"description":"The most significant inter-chart aspects involving personal planets (Sun through Saturn), sorted by strength. Each includes a relationship-specific interpretation."}},"required":["overallScore","categories","persons","signCompatibility","elementBalance","archetype","strengths","challenges","summary","interpretation","aspectBreakdown","keyAspects"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/horoscope/{sign}/daily":{"get":{"operationId":"getDailyHoroscope","tags":["Western Astrology"],"summary":"Daily horoscope by zodiac sign - Transit-based forecast with house activations","description":"Get the daily horoscope for any zodiac sign. Forecast is generated from real-time planetary transits using whole-sign house positions, so every sign receives unique content. Returns love, career, health, finance, overview with active transits, Moon sign, Moon phase, energy rating, lucky number, lucky color, and compatible signs. Content is fixed for a given date and rolls over at midnight, by default UTC. Pass date for editorial scheduling, or timezone to roll over on a local clock. Daily horoscope API, zodiac forecast, sun sign horoscope, astrology prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"],"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","example":"aries"},"required":true,"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","name":"sign","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-04-03","description":"Forecast date in YYYY-MM-DD format. Past and future dates are both supported, for editorial scheduling and backfill. Defaults to the current period in the timezone parameter."},"required":false,"description":"Forecast date in YYYY-MM-DD format. Past and future dates are both supported, for editorial scheduling and backfill. Defaults to the current period in the timezone parameter.","name":"date","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on each day. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\")."},"required":false,"description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on each day. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\").","name":"timezone","in":"query"}],"responses":{"200":{"description":"Daily horoscope retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign for this horoscope."},"date":{"type":"string","example":"2026-04-03","description":"Date of this daily horoscope (YYYY-MM-DD)."},"overview":{"type":"string","example":"Saturn teaches Aries through focused effort today. What feels heavy now becomes your greatest strength later. Trust the process of mastery and keep showing up.","description":"General daily overview based on Moon house activation and planetary transits. Unique per sign based on whole-sign house positions."},"love":{"type":"string","example":"Venus in your sixth house shows love through acts of service. Small gestures of care mean more than grand declarations. Health-focused activities with a partner strengthen your bond.","description":"Love and relationship forecast. Based on Venus house position relative to this sign, providing unique guidance per sign."},"career":{"type":"string","example":"Take responsibility seriously at work. Hard work brings lasting results, even when progress feels invisible. Your reliability earns respect.","description":"Career and professional outlook. Based on Mars house position relative to this sign, with Saturn and Jupiter influences."},"health":{"type":"string","example":"The Sun in your fifth house connects vitality with joy and self-expression. Physical play, creative movement, and laughter are the best medicine today.","description":"Health, energy, and wellness guidance for the day."},"finance":{"type":"string","example":"Jupiter in your fifth house brings financial luck through creative ventures and speculative risks. Hobbies could become income sources.","description":"Financial outlook and money-related guidance."},"advice":{"type":"string","example":"Mercury in your fourth house turns attention to family conversations and household planning. Important discussions about home life go well.","description":"Actionable daily advice based on the dominant transit energy."},"luckyNumber":{"type":"number","example":7,"description":"Lucky number for the day."},"luckyColor":{"type":"string","example":"Gold","description":"Lucky color for the day, derived from the sign element."},"compatibleSigns":{"type":"array","items":{"type":"string"},"example":["Leo","Sagittarius","Gemini"],"description":"Most compatible zodiac signs for this sign. Trine partners (same element) followed by a sextile partner (complementary element). Use for compatibility widgets, dating app onboarding, and horoscope cards."},"activeTransits":{"type":"array","items":{"type":"string"},"example":["Moon in Libra (7th house of partnerships and relationships)","Venus in Taurus (2nd house of finances and personal values)"],"description":"Active planetary transits affecting this sign today, with house activations. Each transit shows the planet, its current sign, and which house it activates for the queried sign."},"moonSign":{"type":"string","example":"Libra","description":"Current Moon sign. Changes every 2-3 days, sets the emotional tone for all signs."},"moonPhase":{"type":"string","example":"Waxing Gibbous Moon","description":"Current lunar phase (New Moon, Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Last Quarter, Waning Crescent)."},"energyRating":{"type":"number","minimum":1,"maximum":10,"example":7,"description":"Overall energy intensity for this sign today (1-10). Higher when more transits activate this sign directly. Useful for content widgets and visual indicators."}},"required":["sign","date","overview","love","career","health","finance","advice","luckyNumber","luckyColor","compatibleSigns","activeTransits","moonSign","moonPhase","energyRating"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/horoscope/{sign}/weekly":{"get":{"operationId":"getWeeklyHoroscope","tags":["Western Astrology"],"summary":"Weekly horoscope by zodiac sign - 7-day transit forecast","description":"Get weekly horoscope for any zodiac sign. Forecast covers a full Monday to Sunday period based on planetary transits with house-based content unique to each sign, with love, career, health, finance guidance plus lucky days, lucky numbers, and compatible signs. Pass any date inside a week to retrieve that week, or timezone to roll over on a local clock. Weekly horoscope API, zodiac weekly forecast, astrology weekly prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"],"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","example":"aries"},"required":true,"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","name":"sign","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-04-03","description":"Any date inside the target week, in YYYY-MM-DD format. The forecast covers the Monday to Sunday week containing it. Defaults to the current period in the timezone parameter."},"required":false,"description":"Any date inside the target week, in YYYY-MM-DD format. The forecast covers the Monday to Sunday week containing it. Defaults to the current period in the timezone parameter.","name":"date","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on each Monday. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\")."},"required":false,"description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on each Monday. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\").","name":"timezone","in":"query"}],"responses":{"200":{"description":"Weekly horoscope retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign for this horoscope."},"week":{"type":"string","example":"2026-03-30","description":"Start date of the forecast week (Monday)."},"overview":{"type":"string","example":"This week features Jupiter in Leo, influencing your broader life direction. Saturn presence in Aries demands maturity and hard work, but builds lasting foundations.","description":"Weekly overview highlighting the dominant planetary transits through the sign."},"love":{"type":"string","example":"Venus in your sixth house shows love through acts of service. Small gestures of care mean more than grand declarations. Health-focused activities with a partner strengthen your bond.","description":"Weekly love and relationship forecast."},"career":{"type":"string","example":"Focus on long-term goals and responsibilities. Hard work pays off, though progress feels slow.","description":"Weekly career and professional outlook."},"health":{"type":"string","example":"The Sun in your fifth house connects vitality with joy and self-expression. Physical play, creative movement, and laughter are the best medicine today.","description":"Weekly health, energy, and wellness guidance."},"finance":{"type":"string","example":"Jupiter in your fifth house brings financial luck through creative ventures and speculative risks. Hobbies could become income sources.","description":"Weekly financial outlook."},"advice":{"type":"string","example":"Mercury in your fourth house turns attention to family conversations and household planning. Important discussions about home life go well.","description":"Actionable weekly guidance based on transit patterns."},"luckyDays":{"type":"array","items":{"type":"string"},"example":["Wednesday","Friday","Sunday"],"description":"Favorable days this week, based on planetary rulership."},"luckyNumbers":{"type":"array","items":{"type":"number"},"example":[1,4,8],"description":"Lucky numbers for the week."},"compatibleSigns":{"type":"array","items":{"type":"string"},"example":["Leo","Sagittarius","Gemini"],"description":"Most compatible zodiac signs for this sign. Trine partners (same element) followed by a sextile partner (complementary element)."}},"required":["sign","week","overview","love","career","health","finance","advice","luckyDays","luckyNumbers","compatibleSigns"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/horoscope/{sign}/monthly":{"get":{"operationId":"getMonthlyHoroscope","tags":["Western Astrology"],"summary":"Monthly horoscope by zodiac sign - 30-day transit forecast with key dates","description":"Get monthly horoscope for any zodiac sign with sign-specific week-by-week breakdown and real lunar phase key dates. Based on planetary transits with house activations unique to each sign, covering love, career, health, and finance for the entire month. Key dates include actual New Moon, Full Moon, and retrograde dates from ephemeris calculations. Pass any date inside a month to retrieve that month, or timezone to roll over on a local clock. Monthly horoscope API, zodiac monthly forecast, astrology monthly prediction.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"],"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","example":"aries"},"required":true,"description":"Zodiac sign, case-insensitive (e.g., aries, Aries, ARIES all work).","name":"sign","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-04-03","description":"Any date inside the target month, in YYYY-MM-DD format. The forecast covers the whole calendar month containing it. Defaults to the current period in the timezone parameter."},"required":false,"description":"Any date inside the target month, in YYYY-MM-DD format. The forecast covers the whole calendar month containing it. Defaults to the current period in the timezone parameter.","name":"date","in":"query"},{"schema":{"type":"string","example":"America/New_York","description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on the 1st. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\")."},"required":false,"description":"Selects which period counts as current when date is omitted. Defaults to UTC, so the forecast rolls over at 00:00 UTC on the 1st. Pass the timezone of the end user to roll over on their local clock instead. Ignored when date is set. Accepts an IANA name (e.g. \"America/New_York\"), decimal hours (e.g. 5.5 for IST), or a fixed UTC offset (e.g. \"-05:00\").","name":"timezone","in":"query"}],"responses":{"200":{"description":"Monthly horoscope retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign for this horoscope."},"month":{"type":"string","example":"2026-04","description":"Month of this forecast (YYYY-MM)."},"overview":{"type":"string","example":"April brings Jupiter influence through Leo, encouraging growth and expansion. For you, this activates your 5th house of romance, creativity, and joy. Saturn in Aries reminds you to build solid foundations.","description":"Monthly overview covering the major planetary transits and their impact on the sign."},"love":{"type":"string","example":"Venus in your sixth house shows love through acts of service. Small gestures of care mean more than grand declarations. Health-focused activities with a partner strengthen your bond.","description":"Monthly love and relationship forecast."},"career":{"type":"string","example":"Focus on long-term career goals. Patience and persistence bring lasting success.","description":"Monthly career and professional outlook."},"health":{"type":"string","example":"The Sun in your fifth house connects vitality with joy and self-expression. Physical play, creative movement, and laughter are the best medicine today.","description":"Monthly health and wellness guidance."},"finance":{"type":"string","example":"Jupiter in your fifth house brings financial luck through creative ventures and speculative risks. Hobbies could become income sources.","description":"Monthly financial outlook and guidance."},"advice":{"type":"string","example":"Mercury in your fourth house turns attention to family conversations and household planning. Important discussions about home life go well.","description":"Actionable guidance for the month as a whole, derived from the Mercury house activation for this sign. Distinct from the per-week advice inside weekByWeek: this is the single takeaway for the month."},"weekByWeek":{"type":"array","items":{"type":"object","properties":{"week":{"type":"number","example":1,"description":"Week number within the month (1-4)."},"focus":{"type":"string","example":"Solitude and inner reflection","description":"Primary focus area for this week, derived from planetary house activations for this sign."},"advice":{"type":"string","example":"Focus on solitude and inner reflection this week for best results.","description":"Specific guidance for this week."}},"required":["week","focus","advice"]},"description":"Week-by-week breakdown with sign-specific focus areas based on transit house positions."},"keyDates":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-15","description":"Date of the astrological event (YYYY-MM-DD)."},"event":{"type":"string","example":"New Moon. Set intentions and plant seeds for new beginnings.","description":"Astrological event active on this date (lunar phases, retrogrades, sign ingresses)."}},"required":["date","event"]},"description":"Key astrological dates this month with actual New Moon, Full Moon, and retrograde dates calculated from ephemeris data."},"luckyNumbers":{"type":"array","items":{"type":"number"},"example":[1,4,8,12],"description":"Lucky numbers for the month."},"luckyColor":{"type":"string","example":"Gold","description":"Lucky color for the month."},"compatibleSigns":{"type":"array","items":{"type":"string"},"example":["Leo","Sagittarius","Gemini"],"description":"Most compatible zodiac signs for this sign. Trine partners (same element) followed by a sextile partner (complementary element)."}},"required":["sign","month","overview","love","career","health","finance","advice","weekByWeek","keyDates","luckyNumbers","luckyColor","compatibleSigns"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/planetary-returns":{"post":{"operationId":"generatePlanetaryReturn","tags":["Western Astrology"],"summary":"Planetary Return Chart - Saturn return, Jupiter return, and inner planet cycles","description":"Generate a planetary return chart for Mercury, Venus, Mars, Jupiter, or Saturn. A planetary return occurs when a transiting planet conjuncts its natal longitude, marking the beginning of a new cycle. Saturn return (~29 years) is the most significant life milestone in Western astrology. Jupiter return (~12 years) signals expansion and growth phases. Mars return (~2 years) resets energy and drive. Returns full tropical zodiac chart with all planetary positions, house cusps, and aspects. Planetary return chart API, Saturn return calculator, Jupiter return chart, Mars return forecast.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date","example":"1990-07-15","description":"Original birth date in YYYY-MM-DD format. Used to determine the natal longitude of the selected planet."},"birthTime":{"type":"string","format":"time","example":"14:30:00","description":"Original birth time in 24-hour HH:MM:SS format. Determines exact natal planet position for return timing."},"planet":{"type":"string","enum":["Mercury","Venus","Mars","Jupiter","Saturn"],"example":"Jupiter","description":"Planet for the return calculation. Supports Mercury (~88 days), Venus (~225 days), Mars (~687 days), Jupiter (~12 years), and Saturn (~29 years). Saturn return is a major life milestone in Western astrology."},"approximateDate":{"type":"string","format":"date","example":"2026-08-15","description":"Approximate date near the expected planetary return (YYYY-MM-DD). Provide a date within the expected return window. The algorithm searches from this starting point."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Latitude of the return location in decimal degrees (-90 to 90). Affects house cusps and Ascendant of the return chart."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Longitude of the return location in decimal degrees (-180 to 180)."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the birthDate. Output datetime is adjusted to this timezone.","example":-5},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"default":"placidus","example":"placidus","description":"House system for the return chart. Placidus (default), Whole Sign, Equal, or Koch."}},"required":["birthDate","birthTime","planet","approximateDate","latitude","longitude","timezone"]},"example":{"birthDate":"1990-07-15","birthTime":"14:30:00","planet":"Jupiter","approximateDate":"2024-08-15","latitude":40.7128,"longitude":-74.006,"timezone":-5,"houseSystem":"placidus"}}}},"responses":{"200":{"description":"Planetary return chart calculated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","example":"1990-07-15","description":"Original birth date used for natal planet longitude calculation."},"planet":{"type":"string","example":"Jupiter","description":"Planet whose return was calculated. Each planet has a different orbital period and return significance."},"returnDate":{"type":"string","example":"2026-08-22T14:15:00","description":"Exact planetary return moment, when the transiting planet conjuncts its natal longitude. Adjusted to requested timezone. Marks the beginning of a new cycle for that planet in your life."},"approximateCycle":{"type":"string","example":"~12 years","description":"Approximate orbital period for this planet. Mercury ~88 days, Venus ~225 days, Mars ~687 days (~1.9 years), Jupiter ~12 years, Saturn ~29 years."},"location":{"type":"object","properties":{"latitude":{"type":"number","example":40.7128,"description":"Observer latitude used for house cusp calculation in the return chart."},"longitude":{"type":"number","example":-74.006,"description":"Observer longitude used for Midheaven and local sidereal time."},"timezone":{"type":"number","example":-5,"description":"Timezone offset from UTC applied to output datetime formatting."}},"required":["latitude","longitude","timezone"],"description":"Location used for the planetary return chart house and Ascendant calculations."},"chart":{"type":"object","properties":{"birthDetails":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"type":"number","minimum":-12,"maximum":14,"example":-5,"description":"Timezone offset from UTC in decimal hours. Examples: New York = -5, London = 0, India = 5.5, Tokyo = 9."}},"required":["date","time","latitude","longitude","timezone"],"description":"Birth details used to generate this chart."},"planets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"Body name. One of the 10 classical planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto), the lunar nodes (North Node, South Node), Chiron, or Black Moon Lilith (the mean lunar apogee). The nodes follow the request `nodeType`, which defaults to the true (osculating) node; pass \"mean\" for the smoothed node. The two differ by up to about 1.8 degrees and no other body is affected."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":112.45,"description":"Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations."},"latitude":{"type":"number","example":0.01,"description":"Ecliptic latitude in degrees. Near zero for most planets, varies for the Moon and Pluto, and reaches up to about 5 degrees for Black Moon Lilith (projected from the inclined mean lunar orbit)."},"sign":{"type":"string","example":"Cancer","description":"Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude."},"degree":{"type":"number","minimum":0,"maximum":30,"example":22.45,"description":"Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign."},"house":{"type":"integer","minimum":1,"maximum":12,"example":7,"description":"House placement (1-12). Determined by the selected house system and birth location."},"speed":{"type":"number","example":0.9571,"description":"Daily motion in degrees per day. Negative values indicate retrograde motion."},"isRetrograde":{"type":"boolean","example":false,"description":"Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection."}},"required":["name","longitude","latitude","sign","degree","house","speed","isRetrograde"]},"description":"All 14 celestial bodies in the tropical zodiac with house placements: the 10 classical planets (Sun through Pluto), the lunar nodes (North Node, South Node, in the requested `nodeType` convention), Chiron, and Black Moon Lilith."},"houses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer","minimum":1,"maximum":12,"example":1,"description":"House number (1-12). Each house governs specific life themes in Western astrology."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":45.32,"description":"Ecliptic longitude of this house cusp in degrees (0-360)."},"sign":{"type":"string","example":"Taurus","description":"Zodiac sign on this house cusp. Colors the themes of this life area."},"degree":{"type":"number","minimum":0,"maximum":30,"example":15.32,"description":"Degree within the zodiac sign on this cusp (0-29.999)."}},"required":["number","longitude","sign","degree"]},"description":"All 12 house cusps calculated using the selected house system."},"houseSystem":{"type":"string","enum":["placidus","whole-sign","equal","koch"],"example":"placidus","description":"House system used for this chart (placidus, whole-sign, equal, or koch)."},"aspects":{"type":"array","items":{"type":"object","properties":{"planet1":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Sun","description":"First planet in the aspect pair."},"planet2":{"type":"string","enum":["Sun","Moon","Mercury","Venus","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto","North Node","South Node","Chiron","Black Moon Lilith"],"example":"Moon","description":"Second planet in the aspect pair."},"type":{"type":"string","enum":["CONJUNCTION","OPPOSITION","TRINE","SQUARE","SEXTILE","SEMI_SEXTILE","QUINCUNX","SEMI_SQUARE","SESQUIQUADRATE"],"example":"TRINE","description":"Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate."},"angle":{"type":"number","example":120,"description":"Exact angular separation that defines this aspect type in degrees."},"orb":{"type":"number","example":2.5,"description":"Deviation from exact aspect in degrees. Tighter orb means stronger influence."},"isApplying":{"type":"boolean","example":true,"description":"Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger."},"strength":{"type":"number","minimum":0,"maximum":100,"example":75,"description":"Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum."},"interpretation":{"type":"string","enum":["harmonious","challenging","neutral"],"example":"harmonious","description":"Aspect nature. Harmonious (trine, sextile) flows easily. Challenging (square, opposition) creates tension and growth. Neutral (conjunction) blends energies. Always English, whatever the lang parameter says: it is an identifier consumers switch and style on. Use interpretationLocalized for anything a reader sees."}},"required":["planet1","planet2","type","angle","orb","isApplying","strength","interpretation"]},"description":"All planetary aspects found in this chart with orbs, strength, and applying/separating status."},"partOfFortune":{"type":"object","properties":{"sign":{"type":"string","example":"Aries","description":"Zodiac sign holding the Part of Fortune."},"degree":{"type":"number","minimum":0,"maximum":30,"example":27.24,"description":"Degree within the Part of Fortune sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":27.24,"description":"Absolute ecliptic longitude of the Part of Fortune (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":8,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."},"sect":{"type":"string","enum":["day","night"],"example":"night","description":"Chart sect used for the calculation. Day (diurnal) when the Sun is above the horizon, night (nocturnal) when below. Day charts use Ascendant plus Moon minus Sun, night charts use Ascendant plus Sun minus Moon."}},"required":["sign","degree","longitude","house","sect"],"description":"Part of Fortune (Lot of Fortune). A point derived from the Ascendant and the two luminaries that marks an area of ease, vitality, and material wellbeing in the chart."},"vertex":{"type":"object","properties":{"sign":{"type":"string","example":"Virgo","description":"Zodiac sign holding the Vertex."},"degree":{"type":"number","minimum":0,"maximum":30,"example":12.9,"description":"Degree within the Vertex sign (0-29.999)."},"longitude":{"type":"number","minimum":0,"maximum":360,"example":162.9,"description":"Absolute ecliptic longitude of the Vertex (0-360)."},"house":{"type":"integer","minimum":1,"maximum":12,"example":6,"description":"House containing this point, resolved against the same cusps as `planets[].house` and using the requested house system. Read this field rather than inferring a house from the sign: the two disagree whenever a house spans more than one sign, which is most of the time outside Whole Sign."}},"required":["sign","degree","longitude","house"],"description":"Vertex. The western intersection of the prime vertical with the ecliptic, often read as a point of fated encounters and turning-point relationships. The opposite point is the Anti-Vertex."}},"required":["birthDetails","planets","houses","houseSystem","aspects","partOfFortune","vertex"],"description":"Full tropical zodiac chart erected for the planetary return moment. Contains planetary positions, house cusps, aspects, Ascendant, and Midheaven."},"natalPlanetPosition":{"type":"object","properties":{"longitude":{"type":"number","example":135.33,"description":"Natal planet ecliptic longitude in degrees (0-360). The transiting planet returns to this exact degree."},"sign":{"type":"string","example":"Leo","description":"Tropical zodiac sign of the natal planet position."},"degree":{"type":"number","example":15.33,"description":"Degree within the zodiac sign (0-29.999)."}},"required":["longitude","sign","degree"],"description":"Original natal planet position that defines the return. The transiting planet conjuncts this longitude to trigger the return."},"interpretation":{"type":"object","properties":{"summary":{"type":"string","example":"This Jupiter return marks a new cycle in the themes governed by Jupiter. The chart shows how this cycle will unfold in your life.","description":"Narrative overview of this planetary return cycle and its significance for personal development."},"keyThemes":{"type":"array","items":{"type":"string"},"example":["Growth and expansion opportunities","Wisdom and philosophical outlook","Luck and abundance","Travel and higher learning"],"description":"Key life themes activated during this return cycle. Focus areas vary by planet — Jupiter brings expansion, Saturn brings structure and responsibility."}},"required":["summary","keyThemes"],"description":"Planetary return interpretation. Saturn returns (~29 years) mark major life milestones. Jupiter returns (~12 years) signal growth cycles. Inner planet returns offer shorter-term insights."}},"required":["birthDate","planet","returnDate","approximateCycle","location","chart","natalPlanetPosition","interpretation"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/astrocartography":{"post":{"operationId":"generateAstrocartography","tags":["Western Astrology"],"summary":"Astrocartography map - planetary lines and relocation calculator","description":"Generate an astrocartography map of Midheaven, Imum Coeli, Ascendant, and Descendant planetary lines for any birth moment. Each line marks where a planet turns angular across the world, the core of relocation astrology and astro mapping. Returns right ascension, declination, the two meridian line longitudes, and sampled rising and setting curves ready to plot, with a short interpretation per line.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","example":"chiron","description":"Optional comma separated list of extra bodies to plot beyond the ten classical planets. Allowed values: north-node, chiron, lilith. north-node is the mean lunar node. Unknown values are ignored. Defaults to none."},"required":false,"description":"Optional comma separated list of extra bodies to plot beyond the ten classical planets. Allowed values: north-node, chiron, lilith. north-node is the mean lunar node. Unknown values are ignored. Defaults to none.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Astrocartography planetary lines calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AstrocartographyResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/relocation-chart":{"post":{"operationId":"generateRelocationChart","tags":["Western Astrology"],"summary":"Generate relocation chart - Relocated birth chart calculator with shifted houses and angles","description":"Calculate a relocation chart (relocated birth chart) for a new place on Earth. The birth moment stays the same, so every planet keeps its natal sign and degree, while the Ascendant, Midheaven, Vertex, and all twelve house cusps are recomputed for the new latitude and longitude. Returns the relocated houses and angles, the planets that change house, the angular planets activated at the new place, and the distance and compass direction from the birthplace. Built for relocation astrology readings, astrocartography style move planning, and travel charts. Verified against NASA JPL Horizons.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelocationChartRequest"}}}},"responses":{"200":{"description":"Relocation chart calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelocationChartResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/local-space":{"post":{"operationId":"generateLocalSpace","tags":["Western Astrology"],"summary":"Local space astrology map - Directional planetary compass lines","description":"Generate a local space astrology map that projects the natal planets onto the local horizon as compass directions and great-circle lines radiating from the birthplace. Returns each body azimuth (degrees clockwise from true north), altitude, 16-point compass direction, whether it sits above the horizon, and the latitude and longitude waypoints of its directional line. Ideal for relocation planning, directional astrology, and travel-direction maps.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":"string","example":"chiron,lilith","description":"Optional comma-separated extra bodies to add beyond the 10 classical planets. Allowed values: north-node, chiron, lilith. north-node is the mean lunar node. Omit to return the 10 classical planets only."},"required":false,"description":"Optional comma-separated extra bodies to add beyond the 10 classical planets. Allowed values: north-node, chiron, lilith. north-node is the mean lunar node. Omit to return the 10 classical planets only.","name":"include","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Combined with time and timezone it fixes the birth instant whose planetary positions are projected onto the local horizon."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Time is essential: the local horizon rotates a full circle each day, so the azimuth (compass direction) of every body depends on the exact birth time."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birthplace latitude in decimal degrees (-90 to 90). This is the origin point of every local space line and the observer latitude used to turn each body into an azimuth and altitude."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birthplace longitude in decimal degrees (-180 to 180). Sets the local horizon orientation and the starting point from which the directional lines radiate."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Decimal hours from UTC (e.g. -5 for EST, 5.5 for IST, 9 for JST) OR IANA name (e.g. \"America/New_York\"). IANA resolved to the DST-correct offset for the birth date.","example":-5}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Local space map generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalSpaceResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/fixed-stars":{"post":{"operationId":"generateFixedStars","tags":["Western Astrology"],"summary":"Fixed stars and star conjunctions calculator - Regulus, Spica, Algol natal report","description":"Calculate the tropical zodiac positions of the major named fixed stars for any birth moment, including the four Royal stars and the fifteen Behenian stars, then detect conjunctions to the natal planets, Ascendant, and Midheaven. Each star returns its precessed ecliptic longitude, zodiac sign, visual magnitude, and traditional planetary nature, with a plain language interpretation for every conjunction inside the chosen orb. A focused tool for natal reports that weigh Regulus, Spica, Aldebaran, Antares, and Algol against the chart.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"maximum":3,"default":1,"example":1,"description":"Conjunction orb in degrees, the maximum separation for a star to count as conjunct a chart point. Defaults to 1, maximum 3. Widen it to surface looser contacts or tighten it for only the closest hits."},"required":false,"description":"Conjunction orb in degrees, the maximum separation for a star to count as conjunct a chart point. Defaults to 1, maximum 3. Widen it to surface looser contacts or tighten it for only the closest hits.","name":"orb","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-07-15","description":"Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown."},"latitude":{"type":"number","minimum":-90,"maximum":90,"example":40.7128,"description":"Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South."},"longitude":{"type":"number","minimum":-180,"maximum":180,"example":-74.006,"description":"Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"Timezone: IANA name (e.g. \"America/New_York\", \"Europe/London\") OR decimal hours from UTC (e.g. -5 for EST, 1 for CET). IANA strings are resolved to the DST-correct offset for the given date, so you can pass `cities[0].timezone` from /location/search directly.","example":-5},"nodeType":{"type":"string","enum":["mean","true"],"default":"true","example":"true","description":"Lunar node convention. \"mean\" is the smoothed average node, which always moves retrograde; \"true\" is the osculating node, which tracks the real perturbed node, oscillates up to about 1.5 degrees either side of the mean on a 173-day cycle, and can briefly turn direct. Neither is more correct and they almost always fall in the same sign. Applies to the North and South Node. True is the osculating node and the default, because it is what most Western chart software reports; mean is the smoothed node preferred by several evolutionary schools, so pass \"mean\" to match one. Nothing else in the chart changes, and the two agree on the sign except when the node sits within about 1.8 degrees of a cusp. Defaults to \"true\"."}},"required":["date","time","latitude","longitude","timezone"]}}}},"responses":{"200":{"description":"Fixed star positions and conjunctions calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FixedStarsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/arabic-lots":{"post":{"operationId":"calculateArabicLots","tags":["Western Astrology"],"summary":"Arabic lots calculator - seven Hermetic parts including Part of Fortune and Spirit","description":"Calculate the seven Hermetic lots (Arabic parts) for any birth moment: Part of Fortune, Part of Spirit, Eros, Necessity, Courage, Victory, and Nemesis. Each lot is a sensitive point projected by arc from the Ascendant, with the day or night formula applied automatically from the chart sect. Returns the zodiac sign, degree, exact longitude, the arc used, and a plain language interpretation per lot, for Hellenistic and traditional astrology apps. Built on accurate tropical chart positions, no astronomy expertise needed.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArabicLotsRequest"}}}},"responses":{"200":{"description":"Arabic lots calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArabicLotsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/asteroids":{"post":{"operationId":"generateAsteroids","tags":["Western Astrology"],"summary":"Asteroid goddesses calculator - Ceres, Pallas, Juno, and Vesta natal positions","description":"Calculate the natal positions of the four classical asteroid goddesses, Ceres, Pallas, Juno, and Vesta, for any birth moment. Each asteroid returns its tropical zodiac sign, degree, house placement, daily speed, retrograde status, and a plain language interpretation of its meaning in the chart. Chiron is available through the natal chart endpoint, so this endpoint stays focused on the four asteroid goddesses for natal reports and relationship astrology.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsteroidsRequest"}}}},"responses":{"200":{"description":"Asteroid positions calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsteroidsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/lilith":{"post":{"operationId":"generateLilith","tags":["Western Astrology"],"summary":"Black Moon Lilith calculator - mean and true lunar apogee in the natal chart","description":"Calculate Black Moon Lilith for any birth chart, both the mean lunar apogee, the steady and most widely used point, and the true or osculating apogee, the exact position that can shift sign and turn retrograde. Returns the zodiac sign, degree, house, ecliptic longitude and latitude, daily speed, retrograde flag, and a plain language interpretation for each variant. Built for natal astrology apps and AI agents exploring the wild, suppressed, and reclaimed self that Lilith represents.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LilithRequest"}}}},"responses":{"200":{"description":"Black Moon Lilith calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LilithResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/progressions":{"post":{"operationId":"generateProgressions","tags":["Western Astrology"],"summary":"Secondary progressions calculator - progressed chart, progressed Sun and Moon","description":"Generate the secondary progressed chart for any date using the day-for-a-year key, where each day of ephemeris motion after birth stands in for one year of life. Returns every progressed body with its sign, degree, whole-sign house, motion, and retrograde state, plus the progressed Ascendant and Midheaven via the Naibod arc. The progressed Sun and progressed Moon are the headline timing markers for inner growth and emotional chapters. Secondary progressions API, progressed chart calculator, progressed Sun and Moon, progressed Ascendant and Midheaven.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgressionsRequest"}}}},"responses":{"200":{"description":"Progressed chart calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgressionsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/solar-arc":{"post":{"operationId":"generateSolarArc","tags":["Western Astrology"],"summary":"Solar arc directions calculator - directed chart at one degree per year","description":"Calculate a solar arc directed chart for any birth moment and target date. The solar arc is the secondary-progressed Sun longitude minus the natal Sun longitude, about one degree for each year of life, and every natal point including the Ascendant and Midheaven is advanced forward by that same arc. Returns the solar arc, each directed point with its natal and directed longitude, zodiac sign, degree, and a plain language interpretation, for predictive astrology apps timing major life events. Built on accurate tropical chart positions, no astronomy expertise needed.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolarArcRequest"}}}},"responses":{"200":{"description":"Solar arc directed chart calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolarArcResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/profections":{"post":{"operationId":"generateProfections","tags":["Western Astrology"],"summary":"Annual profections calculator - lord of the year and yearly time lord by age","description":"Calculate the annual profection and lord of the year for any birth chart and target date using the Hellenistic time lord technique. Each completed year of life advances the rising sign by one whole sign house, activating a new profected house, profected sign, and ruling planet that sets the tone of the year. Returns the age, profected house and sign, the lord of the year with its natal sign and house placement, and a plain language interpretation for traditional and Hellenistic astrology apps.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru"],"default":"en","example":"en","description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English."},"required":false,"description":"Response language (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return English.","name":"lang","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfectionsRequest"}}}},"responses":{"200":{"description":"Annual profection calculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfectionsResponse"}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}}},"webhooks":{}}