Your Stars API (1.0.0)

Download OpenAPI specification:Download

API documentation for Your Stars

Ascendant and Midheaven

Calculate the Ascendant (ASC) or Midheaven (MC) based on birth data.

This endpoint computes the zodiac sign, degree, and decan for the Ascendant (ASC) or Midheaven (MC) using the Swiss Ephemeris. It requires full birth details (date, time, location) and returns astrological data for the selected points. The request must specify whether to calculate ASC, MC, or both.

header Parameters

YS-API-Key

required

string

Example: your-api-key-here

API key required for authentication.

Request Body schema: application/json

year required	integer
month required	integer
day required	integer
hour required	integer
minute required	integer
second	integer
latitude required	number
longitude required	number
timezone required	number
points required	Array of strings Items Enum: "asc" "mc" Points to calculate ("asc" for Ascendant, "mc" for Midheaven).
full_name	string Optional name for personalization.
place	string Optional place name for personalization.
showInterpretation	boolean Default: true Flag to include detailed interpretations in the response. Defaults to true.

Responses

Request samples

Payload

Content type

application/json

{"year": 1988,
"month": 11,
"day": 18,
"hour": 3,
"minute": 47,
"second": 30,
"latitude": 36.1627,
"longitude": -86.7816,
"timezone": -6,
"points": ["asc",
"mc"
],
"full_name": "Logan",
"place": "Nashville, Tennessee",
"showInterpretation": true
}

Response samples

Content type

application/json

{"success": true,
"data": [{"point": "MC",
"sign": "Aries",
"degree": "29°34′",
"decimalDegree": 29.58,
"decan": {"name": "Aries III – The Explorer",
"ruler": "Jupiter"
},
"interpretation": "With your Midheaven in Aries, you’re destined to be a trailblazer, driven by a bold, pioneering spirit and a deep-seated need for recognition and achievement. Jupiter’s influence adds a generous and expansive quality to your ambition, suggesting you’ll attract opportunities and abundance as you pursue your passions. You'll likely excel in leadership roles and public-facing positions, radiating confidence and a contagious enthusiasm. Embrace your natural assertiveness, and remember to channel your energy into projects that ignite your soul and leave a lasting impact on the world."
},
{"point": "ASC",
"sign": "Leo",
"degree": "8°51′",
"decimalDegree": 128.85,
"decan": {"name": "Leo I – The Performer",
"ruler": "Sun"
},
"interpretation": "With an Ascendant in Leo, you radiate warmth and charisma, instinctively drawing people to you with your natural confidence and generous spirit. This placement gifts you with a powerful need for recognition and admiration, fueling a desire to be a center of attention and a leader in your chosen endeavors. Embrace your theatricality and use your creativity to express your unique voice – don’t be afraid to shine brightly and command attention. Channel this energy into projects and relationships where you can inspire and uplift others, honoring your innate desire for celebration and joyful connection."
}
]
}

Houses

Calculate detailed astrological house placements and interpretations

This endpoint calculates comprehensive astrological data including house placements, degrees, decans, and personalized interpretations for specified celestial bodies based on birth data. The calculation includes planets, lunar nodes (northnode, southnode), Chiron, and the Midheaven (MC). The system uses Swiss Ephemeris for precise astronomical calculations and provides rich astrological insights.

Request Body schema: application/json

planets required	Array of strings Items Enum: "sun" "moon" "mercury" "venus" "mars" "jupiter" "saturn" "uranus" "neptune" "pluto" "northnode" "southnode" "chiron" Array of celestial bodies to calculate (planets, nodes, and angles)
year required	integer [ 1800 .. 2100 ]
month required	integer [ 1 .. 12 ]
day required	integer [ 1 .. 31 ]
hour required	integer [ 0 .. 23 ]
minute required	integer [ 0 .. 59 ]
second	integer [ 0 .. 59 ] Default: 0
latitude required	number [ -90 .. 90 ]
longitude required	number [ -180 .. 180 ]
timezone required	number [ -12 .. 14 ]
full_name	string Optional name for personalization
place	string Optional birth location name
showInterpretation	boolean Default: true Flag to include detailed interpretations in the response. Defaults to true.

Responses

Request samples

Payload

Content type

application/json

{"planets": ["sun",
"moon",
"mercury",
"venus"
],
"year": 1982,
"month": 3,
"day": 25,
"hour": 14,
"minute": 12,
"second": 30,
"latitude": 34.0522,
"longitude": -118.2437,
"timezone": -7,
"full_name": "Sophia",
"place": "Los Angeles, California",
"showInterpretation": true
}

Response samples

Content type

application/json

{"success": true,
"data": [{"planet": "sun",
"degree": "4°53′",
"decimalDegree": 4.89,
"house": 9,
"decan": {"name": "House IX – I",
"title": "The First Pilgrimage",
"ruler": "Jupiter"
},
"interpretation": "With your Sun in the 9th House, you’re driven by a profound yearning for justice, ethics, and philosophical understanding – a deep-seated desire to reshape your worldview. Jupiter’s influence amplifies this, suggesting a natural optimism and expansive thinking as you navigate legal, political, or spiritual systems.  This placement indicates a transformative journey focused on challenging established norms and potentially disrupting outdated beliefs.  As a soul-level archetype, you are a pioneer, seeking higher knowledge and advocating for universal principles, often through travel, learning, or engaging with diverse cultures."
},
{"planet": "moon",
"degree": "10°48′",
"decimalDegree": 10.8,
"house": 9,
"decan": {"name": "House IX – II",
"title": "The Inner Compass",
"ruler": "Jupiter"
},
"interpretation": "With Moon in the 9th house, ruled by Sagittarius, you possess a deep-seated yearning for expansive philosophical understanding and global connection. This placement reveals a core need for intellectual and spiritual transformation, often seeking answers through travel, higher education, or engaging with diverse cultures. Your soul is driven by a desire for justice, ethics, and a profound understanding of humanity’s place in the world. Embrace the discomfort of challenging your beliefs and trust your instinctual wisdom to navigate uncharted territories of the mind and heart."
},
{"planet": "mercury",
"degree": "19°16′",
"decimalDegree": 349.27,
"house": 8,
"decan": {"name": "House VIII – II",
"title": "The Crucible",
"ruler": "Mars"
},
"interpretation": "With Mercury in the 8th house, ruled by Mars, you possess a deeply analytical mind intensely focused on transformative processes – particularly those involving partnerships, shared resources, and profound shifts. This placement suggests a powerful, almost combative intellect applied to uncovering hidden truths within relationships and legacies. Driven by a fiery need for psychological honesty and radical change, you likely approach intimacy and finance with a strategic, sometimes intense, perspective.  At your soul level, you’re an investigator, a reformer, yearning to dismantle outdated systems and reclaim power through intellectual and emotional breakthroughs."
},
{"planet": "venus",
"degree": "18°38′",
"decimalDegree": 318.65,
"house": 7,
"decan": {"name": "House VII – II",
"title": "The Pact",
"ruler": "Juno"
},
"interpretation": "With Venus in the 7th, you’re deeply driven by the desire for harmonious, soul-level partnerships—these relationships aren’t just about attraction, but about profound integration and mutual growth. Juno’s influence suggests a need for deeply ethical and supportive connections, prioritizing fairness and justice in your collaborations. This placement indicates a transformation through shared values and a willingness to negotiate your own needs for the benefit of the relationship. You likely seek a partner who mirrors your commitment to justice and fosters a sense of deep, soulful belonging."
}
]
}

Moon Phase

Calculate the moon phase based on birth data.

This endpoint calculates the moon phase, including the phase name, angle between the moon and sun, illumination percentage, waxing/waning status, and a symbolic interpretation. It uses the Swiss Ephemeris for astronomical accuracy and returns the moon’s current relationship to the sun.

Request Body schema: application/json

full_name	string
year required	integer
month required	integer
day required	integer
hour required	integer
minute required	integer
second	integer
timezone required	number
latitude required	number
longitude required	number
place	string
showInterpretation	boolean Default: true Flag to include detailed interpretations in the response

Responses

Request samples

Payload

Content type

application/json

{"full_name": "Carlyn",
"year": 1985,
"month": 9,
"day": 14,
"hour": 22,
"minute": 18,
"second": 0,
"timezone": -7,
"latitude": 47.6062,
"longitude": -122.3321,
"place": "Seattle, Washington",
"showInterpretation": true
}

Response samples

Content type

application/json

{"success": true,
"data": {"phase": "New Moon",
"angle": 5.69,
"illumination": 0.25,
"waxing": true,
"moonLongitude": 178.0007256110145,
"sunLongitude": 172.31410352672754,
"interpretation": "This is your moment to pause, reflect, and begin again. The New Moon invites you to get clear on your desires and set grounded, intentional goals. It's not about rushing forward — it's about aligning with what truly matters. Give yourself permission to dream quietly and plant seeds in stillness. What you begin now has the power to grow with time and care."
}
}

Natal Chart

Generate a natal chart SVG based on birth data.

Generates a natal chart in SVG format based on the user's birth data and optional drawing preferences. Calculates planetary positions, house cusps, and aspects to create the SVG representation.

header Parameters

YS-API-Key

required

string

Example: your-api-key-here

API key for authentication.

Request Body schema: application/json

full_name	string Optional name for personalization.
year required	integer
month required	integer
day required	integer
hour required	integer
minute required	integer
second	integer
timezone	number
latitude required	number
longitude required	number
place	string Optional place name for personalization.
size	integer Size of the SVG image in pixels.

Responses

Request samples

Payload

Content type

application/json

{"full_name": "Mason",
"year": 1995,
"month": 2,
"day": 9,
"hour": 16,
"minute": 28,
"second": 45,
"timezone": -5,
"latitude": 40.7128,
"longitude": -74.006,
"place": "New York, New York",
"size": 800
}

Response samples

Content type

application/json

{"success": false,
"error": "Invalid JSON in request body"
}

Planets

Calculate planetary positions based on birth data.

This endpoint calculates the zodiac sign, degree, and symbolic decan for one or more planets or sensitive points based on the provided birth data (date, time, and location). The response includes sign placement, precise degree, symbolic decan (name and planetary ruler), and an optional interpretation if showInterpretation is true.

header Parameters

YS-API-Key

required

string

Example: your-api-key-here

API key required for authentication.

Request Body schema: application/json

required	string or Array of strings
year required	integer
month required	integer
day required	integer
hour required	integer
minute required	integer
second	integer
latitude required	number
longitude required	number
timezone required	number
full_name	string
place	string
showInterpretation	boolean Default: true Flag to include detailed interpretations in the response. Defaults to true.

Responses

Request samples

Payload

Content type

application/json

{"planets": ["venus",
"sun",
"moon",
"mercury"
],
"year": 1984,
"month": 10,
"day": 2,
"hour": 21,
"minute": 11,
"second": 15,
"latitude": 34.0522,
"longitude": -118.2437,
"timezone": -7,
"full_name": "Ethan",
"place": "Los Angeles, California",
"showInterpretation": true
}

Response samples

Content type

application/json

{"success": true,
"data": [{"planet": "venus",
"sign": "Scorpio",
"degree": "9°10′",
"decimalDegree": 219.18,
"decan": {"name": "Scorpio I – The Alchemist",
"ruler": "Pluto"
},
"interpretation": "Venus in Scorpio reveals a soul deeply invested in profound love and transformation, often seeking intensity and emotional depth beyond the surface. The influence of Pluto amplifies this, suggesting a need to excavate and transmute past wounds and shadow aspects within relationships and self-love. You’re an alchemist of the heart, capable of turning pain into exquisite beauty and understanding through intense, sometimes challenging, experiences. Embrace the discomfort – it’s where true growth and a uniquely magnetic allure reside. Ultimately, your romantic passions and desires will reshape you and those you connect with, leaving a lasting, transformative impact."
},
{"planet": "sun",
"sign": "Libra",
"degree": "10°07′",
"decimalDegree": 190.13,
"decan": {"name": "Libra II – The Innovator",
"ruler": "Uranus"
},
"interpretation": "As a Sun in Libra, you possess a natural talent for innovation born from a deep-seated desire for harmony and balance, constantly seeking elegant solutions to complex problems. Uranus rules your expression, injecting bursts of unexpected creativity and a rebellious streak that challenges the status quo – you’re not content with simply improving things, you crave radical shifts. This translates into a career path where you can design, mediate, or introduce fresh perspectives, and you likely excel in fields requiring diplomacy and aesthetic sensibilities. Embrace your urge to disrupt, but temper it with your innate need for fairness and collaboration to achieve truly transformative results."
},
{"planet": "moon",
"sign": "Capricorn",
"degree": "24°53′",
"decimalDegree": 294.89,
"decan": {"name": "Capricorn III – The Craftsperson",
"ruler": "Mercury"
},
"interpretation": "With Moon in Capricorn, you possess a deeply grounded and responsible emotional core, shaped by a need for structure and achievement. Mercury’s influence adds a sharp, analytical mind to your feelings, allowing you to dissect situations and communicate your needs with precision. You likely approach emotional vulnerability with careful consideration, prioritizing logic and strategic planning in your relationships. This combination suggests a talent for craftsmanship – not just in a physical sense, but in building stable, respected, and enduring connections. Focus on translating your intuition into tangible results, and you’ll find profound fulfillment in your projects and partnerships."
},
{"planet": "mercury",
"sign": "Libra",
"degree": "4°15′",
"decimalDegree": 184.25,
"decan": {"name": "Libra I – The Diplomat",
"ruler": "Venus"
},
"interpretation": "With Mercury in Libra, you’re likely experiencing a heightened need for harmony and fairness in your communication – strive to articulate your needs with grace and consideration for others’ perspectives. The influence of Venus encourages you to seek balanced, beautiful solutions and to avoid sharp, argumentative language. You may find yourself drawn to intellectual pursuits that involve collaboration, diplomacy, and aesthetic beauty. To thrive, prioritize finding common ground and expressing yourself in a way that fosters connection and understanding, recognizing that compromise is often key to successful outcomes."
}
]
}

Synastry

Calculate synastry aspects between two people's natal charts.

This endpoint calculates astrological aspects (e.g., conjunction, square, trine, opposition) between the natal planets of two individuals. It compares the planetary positions of both people to determine potential relationship dynamics and compatibility based on selected aspects and orbs.

Request Body schema: application/json

required	object
required	object
planets required	Array of strings Items Enum: "sun" "moon" "mercury" "venus" "mars" "jupiter" "saturn" "uranus" "neptune" "pluto" "chiron" "northnode" "southnode" "mc"
aspects	Array of strings Items Enum: "conjunction" "opposition" "trine" "square" "sextile"
orb	number
showInterpretation	boolean Default: true Flag to include detailed interpretations in the response

Responses

Request samples

Payload

Content type

application/json

{"personA": {"full_name": "Alice",
"year": 1990,
"month": 5,
"day": 17,
"hour": 14,
"minute": 30,
"second": 0,
"timezone": -4,
"latitude": 40.7128,
"longitude": -74.006
},
"personB": {"full_name": "Bob",
"year": 1988,
"month": 10,
"day": 3,
"hour": 9,
"minute": 15,
"second": 0,
"timezone": -7,
"latitude": 34.0522,
"longitude": -118.2437
},
"planets": ["sun",
"moon",
"venus"
],
"aspects": ["conjunction",
"square",
"trine",
"opposition"
],
"orb": 5,
"showInterpretation": true
}

Response samples

Content type

application/json

{"success": true,
"data": [{"personAPlanet": "moon",
"personBPlanet": "venus",
"aspect": "opposition",
"angle": 176.96,
"personALongitude": 325.95,
"personBLongitude": 148.99,
"interpretation": "The Moon Opposition Venus in your synastry suggests a beautiful, yet potentially complex, dance of emotions and attraction. One partner likely feels deeply sensitive and needs a significant amount of reassurance and nurturing, while the other radiates warmth, charm, and a desire to please. This pairing thrives on shared appreciation for beauty, pleasure, and connection, but it can also create tension as one partner’s need for emotional safety clashes with the other’s tendency to prioritize outward displays of affection. To truly flourish, both individuals must learn to consciously validate each other’s feelings and express their desires openly, fostering a harmonious balance between vulnerability and outward expression."
},
{"personAPlanet": "venus",
"personBPlanet": "sun",
"aspect": "opposition",
"angle": 184.75,
"personALongitude": 15.41,
"personBLongitude": 190.66,
"interpretation": "The Venus-Sun opposition in your synastry suggests a beautiful, yet potentially turbulent, dynamic rooted in core values and attraction. You likely experience profound, almost magnetic, pulls towards each other, fueled by a deep need for validation and mirroring of your fundamental identities. However, this opposition can create a push-and-pull in communication, as one partner may feel the other is subtly challenging their beliefs or presenting a contrasting vision of happiness. To thrive, you’ll need to consciously acknowledge and appreciate the unique perspectives you bring, fostering a space where both your needs for recognition and authenticity are honored, ultimately leading to a truly expansive and transformative connection."
}
]
}

Transits

Calculate transiting aspects to a natal chart.

Calculates daily transiting aspects (e.g., conjunctions, squares, trines) between specified transiting planets and the natal positions derived from a user's birth data over a given date range. The maximum supported range is 90 days.

Request Body schema: application/json

full_name	string
year required	integer
month required	integer
day required	integer
hour required	integer
minute required	integer
second	integer
timezone required	number
latitude required	number
longitude required	number
place	string
startDate required	string <date>
endDate required	string <date>
planets required	Array of strings Items Enum: "sun" "moon" "mercury" "venus" "mars" "jupiter" "saturn" "uranus" "neptune" "pluto" "chiron" "northnode" "southnode" "mc"
aspects	Array of strings Items Enum: "conjunction" "opposition" "trine" "square" "sextile"
exactThreshold	number
showInterpretation	boolean Default: true Flag to include detailed interpretations in the response

Responses

Request samples

Payload

Content type

application/json

{"full_name": "Alisha",
"year": 1982,
"month": 11,
"day": 3,
"hour": 14,
"minute": 26,
"second": 0,
"timezone": -8,
"latitude": 34.0522,
"longitude": -118.2437,
"place": "Los Angeles, California",
"startDate": "2025-03-29",
"endDate": "2025-03-30",
"planets": ["sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter"
],
"aspects": ["conjunction",
"square",
"trine"
],
"exactThreshold": 1,
"showInterpretation": true
}

Response samples

Content type

application/json

{"success": true,
"data": [{"transitPlanet": "moon",
"natalPlanet": "mars",
"aspect": "square",
"exactDateTime": "2025-03-29T00:00:00.000Z",
"startDate": "2025-03-28",
"endDate": "2025-03-30",
"interpretation": "This Moon square Mars transit may bring emotional volatility and impulsive action..."
}
]
}