Composite Chart API
Midpoint relationship chart with interpretations
POST/astrology/composite-chart
Included with every plan (at no extra cost)
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.
Location first, chart second
The Composite Chart API needs latitude, longitude, and timezone. Never ask users to type coordinates. Resolve a city with the Location endpoint first, then feed the result into the request. Timezone accepts a decimal offset or an IANA name.
1 Resolve the location
GET
curl "https://roxyapi.com/api/v2/location/search?q=New York" \
-H "X-API-Key: YOUR_KEY"
# -> cities[0]: { latitude, longitude, timezone: "America/New_York" }2 Call the Composite Chart endpoint
POST /astrology/composite-chart
# feed latitude, longitude and timezone from step 1
POST https://roxyapi.com/api/v2/astrology/composite-chartRequest
POST /api/v2/astrology/composite-chart
Parameters
| Parameter | Type | Description |
|---|---|---|
| langquery | string enum | Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default en. |
Request body
| Field | Type | Description |
|---|---|---|
| person1* | object | First person birth details (date, time, location, timezone). |
| person1.date* | string (date) | Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day. |
| person1.time* | string (time) | Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown. |
| person1.latitude* | number | Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South. |
| person1.longitude* | number | Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West. |
| person1.timezone* | number or string | Timezone: an IANA name (e.g. "America/New_York", "Europe/London", or `cities[0].timezone` from /location/search) or decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). An IANA name is resolved to the offset in force at the given date and time. |
| person1.nodeType | string enum | 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". |
| person2* | object | Second person birth details (date, time, location, timezone). |
| person2.date* | string (date) | Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day. |
| person2.time* | string (time) | Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown. |
| person2.latitude* | number | Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South. |
| person2.longitude* | number | Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West. |
| person2.timezone* | number or string | Timezone: an IANA name (e.g. "America/New_York", "Europe/London", or `cities[0].timezone` from /location/search) or decimal hours from UTC (e.g. -5 for EST, 5.5 for IST). An IANA name is resolved to the offset in force at the given date and time. |
| person2.nodeType | string enum | 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". |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
| houseSystem | string enum | House system for the composite chart. Placidus (default), Whole Sign, Equal, or Koch. |
Example request
POST /api/v2/astrology/composite-chart
{
"person1": {
"date": "1990-07-15",
"time": "14:30:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": "America/New_York",
"nodeType": "true"
},
"person2": {
"date": "1990-07-15",
"time": "14:30:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": "America/New_York",
"nodeType": "true"
},
"houseSystem": "placidus"
}Response
Structured JSON with documented fields, covered by 13,405 automated tests per deploy, 3,620 of them gold-standard tests verified against NASA JPL Horizons. Not hallucinated text.
200 OK
{
"person1": {
"date": "1990-07-15",
"time": "14:30:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -4,
"nodeType": "true"
},
"person2": {
"date": "1990-07-15",
"time": "14:30:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -4,
"nodeType": "true"
},
"compositePlanets": [
{
"name": "Sun",
"longitude": 113.00452053215861,
"latitude": 0.0001759667946626438,
"sign": "Cancer",
"degree": 23.004520532158608,
"house": 9,
"speed": 0.9539943976308223,
"isRetrograde": false,
"compositeInterpretation": {
"summary": "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.",
"relationshipMeaning": "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.",
"keywords": [
"active",
"awareness",
"bright",
"confidence",
"consciousness",
"intuitive",
"nurturing",
"protective"
]
}
},
{
"name": "Moon",
"longitude": 27.068938674158613,
"latitude": 5.181805332627993,
"sign": "Aries",
"degree": 27.068938674158613,
"house": 6,
"speed": 14.10478254438371,
"isRetrograde": false,
"compositeInterpretation": {
"summary": "Moon in Aries (Ram) brings ambitious, independent, impatient energy to the themes of inner emotional life. This placement gives your Moon expression a distinctly Aries character, shaping how you navigate these areas of life.",
"relationshipMeaning": "The composite Moon in aries shows your emotional bond and how you nurture each other. This reveals your shared feelings and domestic life together.",
"keywords": [
"caretaker",
"comfort",
"emotion",
"feeling",
"femininity",
"ambitious",
"independent",
"impatient"
]
}
},
{
"name": "Mercury",
"longitude": 127.2804483512056,
"latitude": 1.771366339138991,
"sign": "Leo",
"degree": 7.280448351205607,
"house": 9,
"speed": 1.8691982629179336,
"isRetrograde": false,
"compositeInterpretation": {
"summary": "Mercury in Leo (Lion) brings proud, bold, ambitious energy to the themes of communication. This placement gives your Mercury expression a distinctly Leo character, shaping how you navigate these areas of life.",
"relationshipMeaning": "The composite Mercury in leo indicates how you communicate as a couple and your shared mental interests. This shows your intellectual connection.",
"keywords": [
"analysis",
"childhood",
"communication",
"curiosity",
"education",
"proud",
"bold",
"ambitious"
]
}
},
{
"name": "Venus",
"longitude": 84.73608276357183,
"latitude": -0.9479624880105159,
"sign": "Gemini",
"degree": 24.73608276357183,
"house": 8,
"speed": 1.1994159048476547,
"isRetrograde": false,
"compositeInterpretation": {
"summary": "Venus in Gemini (Twins) brings curious, affectionate, kind energy to the themes of love, beauty, and money. This placement gives your Venus expression a distinctly Gemini character, shaping how you navigate these areas of life.",
"relationshipMeaning": "The composite Venus in gemini reveals what you value together and how you express affection. This is the love language of your relationship.",
"keywords": [
"attractiveness",
"beauty",
"culture",
"eros",
"fantasy",
"curious",
"affectionate",
"kind"
]
}
},
{
"name": "Mars",
"longitude": 32.12342925796031,
"latitude": -2.0650864909835867,
"sign": "Taurus",
"degree": 2.1234292579603107,
"house": 6,
"speed": 0.6691958830514579,
"isRetrograde": false,
"compositeInterpretation": {
"summary": "Mars in Taurus (Bull) brings dependable, musical, practical energy to the themes of assertiveness and aggression. This placement gives your Mars expression a distinctly Taurus character, shaping how you navigate these areas of life.",
"relationshipMeaning": "The composite Mars in taurus shows how you assert yourselves as a couple and handle conflicts. This represents your shared drive and sexual energy.",
"keywords": [
"action",
"adventurous",
"athletic",
"brave",
"courage",
"dependable",
"musical",
"practical"
]
}
},
{
"name": "Jupiter",
"longitude": 112.60994571682349,
"latitude": 0.23002826787756697,
"sign": "Cancer",
"degree": 22.60994571682349,
"house": 9,
"speed": 0.22425373323959263,
"isRetrograde": false,
"compositeInterpretation": {
"summary": "Jupiter in Cancer (Crab) brings intuitive, nurturing, protective energy to the themes of luck and opportunity. This placement gives your Jupiter expression a distinctly Cancer character, shaping how you navigate these areas of life.",
"relationshipMeaning": "Jupiter in Cancer (Crab) brings intuitive, nurturing, protective energy to the themes of luck and opportunity. This placement gives your Jupiter expression a distinctly Cancer character, shaping how you navigate these areas of life.",
"keywords": [
"abundance",
"college",
"culture",
"curiosity",
"diversity",
"intuitive",
"nurturing",
"protective"
]
}
},
{
"name": "Saturn",
"longitude": 291.94353953255387,
"latitude": 0.07390792755091395,
"sign": "Capricorn",
"degree": 21.94353953255387,
"house": 3,
"speed": -0.07405290614678961,
"isRetrograde": true,
"compositeInterpretation": {
"summary": "Saturn in Capricorn (Goat) brings ambitious, disciplined, patient energy to the themes of responsibility, time, and routine. This placement gives your Saturn expression a distinctly Capricorn character, shaping how you navigate these areas of life.",
"relationshipMeaning": "Saturn in Capricorn (Goat) brings ambitious, disciplined, patient energy to the themes of responsibility, time, and routine. This placement gives your Saturn expression a distinctly Capricorn character, shaping how you navigate these areas of life.",
"keywords": [
"ambition",
"boundaries",
"determination",
"discipline",
"experience",
"ambitious",
"disciplined",
"patient"
]
}
},
{
"name": "Uranus",
"longitude": 276.956281802796,
"latitude": -0.32815436960618005,
"sign": "Capricorn",
"degree": 6.956281802796013,
"house": 2,
"speed": -0.0384483570994405,
"isRetrograde": true,
"compositeInterpretation": {
"summary": "Uranus in Capricorn (Goat) brings ambitious, disciplined, patient energy to the themes of individuality and revolution. This placement gives your Uranus expression a distinctly Capricorn character, shaping how you navigate these areas of life.",
"relationshipMeaning": "Uranus in Capricorn (Goat) brings ambitious, disciplined, patient energy to the themes of individuality and revolution. This placement gives your Uranus expression a distinctly Capricorn character, shaping how you navigate these areas of life.",
"keywords": [
"avant-garde",
"change",
"comic",
"determined",
"experimental",
"ambitious",
"disciplined",
"patient"
]
}
},
{
"name": "Neptune",
"longitude": 282.9139975022088,
"latitude": 0.8724956724681929,
"sign": "Capricorn",
"degree": 12.913997502208815,
"house": 3,
"speed": -0.026536991986546354,
"isRetrograde": true,
"compositeInterpretation": {
"summary": "Neptune in Capricorn (Goat) brings ambitious, disciplined, patient energy to the themes of dreams, healing, and intuition. This placement gives your Neptune expression a distinctly Capricorn character, shaping how you navigate these areas of life.",
"relationshipMeaning": "Neptune in Capricorn (Goat) brings ambitious, disciplined, patient energy to the themes of dreams, healing, and intuition. This placement gives your Neptune expression a distinctly Capricorn character, shaping how you navigate these areas of life.",
"keywords": [
"artistic",
"calm",
"compassionate",
"deep",
"dreams",
"ambitious",
"disciplined",
"patient"
]
}
},
{
"name": "Pluto",
"longitude": 224.99788103667183,
"latitude": 15.61090590671027,
"sign": "Scorpio",
"degree": 14.997881036671828,
"house": 1,
"speed": -0.005732571919807583,
"isRetrograde": true,
"compositeInterpretation": {
"summary": "Pluto in Scorpio (Scorpion) brings seductive, passionate, independent energy to the themes of sex, death, and transformation. This placement gives your Pluto expression a distinctly Scorpio character, shaping how you navigate these areas of life.",
"relationshipMeaning": "Pluto in Scorpio (Scorpion) brings seductive, passionate, independent energy to the themes of sex, death, and transformation. This placement gives your Pluto expression a distinctly Scorpio character, shaping how you navigate these areas of life.",
"keywords": [
"alchemy",
"bold",
"charismatic",
"complex",
"courageous",
"seductive",
"passionate",
"independent"
]
}
},
{
"name": "North Node",
"longitude": 307.35871686645265,
"latitude": 0,
"sign": "Aquarius",
"degree": 7.358716866452653,
"house": 3,
"speed": -0.0031712752905264097,
"isRetrograde": true,
"compositeInterpretation": {
"summary": "North Node in Aquarius (Water Bearer) brings imaginative, idealistic, intuitive energy to the themes of life purpose and destiny. This placement gives your North Node expression a distinctly Aquarius character, shaping how you navigate these areas of life.",
"relationshipMeaning": "North Node in Aquarius (Water Bearer) brings imaginative, idealistic, intuitive energy to the themes of life purpose and destiny. This placement gives your North Node expression a distinctly Aquarius character, shaping how you navigate these areas of life.",
"keywords": [
"destiny",
"life purpose",
"soul growth",
"future direction",
"karmic reward",
"imaginative",
"idealistic",
"intuitive"
]
}
},
{
"name": "South Node",
"longitude": 127.35871686645265,
"latitude": 0,
"sign": "Leo",
"degree": 7.358716866452653,
"house": 9,
"speed": -0.0031712752905264097,
"isRetrograde": true,
"compositeInterpretation": {
"summary": "South Node in Leo (Lion) brings proud, bold, ambitious energy to the themes of past life gifts and comfort zone. This placement gives your South Node expression a distinctly Leo character, shaping how you navigate these areas of life.",
"relationshipMeaning": "South Node in Leo (Lion) brings proud, bold, ambitious energy to the themes of past life gifts and comfort zone. This placement gives your South Node expression a distinctly Leo character, shaping how you navigate these areas of life.",
"keywords": [
"innate talents",
"past life wisdom",
"natural abilities",
"comfort zone",
"mastered skills",
"proud",
"bold",
"ambitious"
]
}
},
{
"name": "Chiron",
"longitude": 109.25705196871604,
"latitude": -6.240259250272088,
"sign": "Cancer",
"degree": 19.25705196871604,
"house": 9,
"speed": 0.10748734886365696,
"isRetrograde": false,
"compositeInterpretation": {
"summary": "Chiron in Cancer (Crab) brings intuitive, nurturing, protective energy to the themes of healing and inner wounds. This placement gives your Chiron expression a distinctly Cancer character, shaping how you navigate these areas of life.",
"relationshipMeaning": "Chiron in Cancer (Crab) brings intuitive, nurturing, protective energy to the themes of healing and inner wounds. This placement gives your Chiron expression a distinctly Cancer character, shaping how you navigate these areas of life.",
"keywords": [
"healing",
"wisdom",
"mentorship",
"teaching",
"empathy",
"intuitive",
"nurturing",
"protective"
]
}
},
{
"name": "Black Moon Lilith",
"longitude": 238.3402727210398,
"latitude": -4.828700516273704,
"sign": "Scorpio",
"degree": 28.34027272103981,
"house": 1,
"speed": 0.1119058931179211,
"isRetrograde": false,
"compositeInterpretation": {
"summary": "Black Moon Lilith in Scorpio (Scorpion) brings seductive, passionate, independent energy to the themes of primal instinct and the reclaimed self. This placement gives your Black Moon Lilith expression a distinctly Scorpio character, shaping how you navigate these areas of life.",
"relationshipMeaning": "Black Moon Lilith in Scorpio (Scorpion) brings seductive, passionate, independent energy to the themes of primal instinct and the reclaimed self. This placement gives your Black Moon Lilith expression a distinctly Scorpio character, shaping how you navigate these areas of life.",
"keywords": [
"authenticity",
"autonomy",
"instinct",
"raw power",
"self-possession",
"seductive",
"passionate",
"independent"
]
}
}
],
"compositeHouses": [
{
"number": 1,
"sign": "Scorpio",
"degree": 6.947368350486414,
"longitude": 216.9473683504864
},
{
"number": 2,
"sign": "Sagittarius",
"degree": 5.704907994392499,
"longitude": 245.7049079943925
},
{
"number": 3,
"sign": "Capricorn",
"degree": 8.864425319131954,
"longitude": 278.86442531913195
},
{
"number": 4,
"sign": "Aquarius",
"degree": 14.375460667638663,
"longitude": 314.37546066763866
},
{
"number": 5,
"sign": "Pisces",
"degree": 17.269211596167793,
"longitude": 347.2692115961678
},
{
"number": 6,
"sign": "Aries",
"degree": 14.67330657058801,
"longitude": 14.67330657058801
},
{
"number": 7,
"sign": "Taurus",
"degree": 6.947368350486386,
"longitude": 36.947368350486386
},
{
"number": 8,
"sign": "Gemini",
"degree": 5.704907994392499,
"longitude": 65.7049079943925
},
{
"number": 9,
"sign": "Cancer",
"degree": 8.864425319131954,
"longitude": 98.86442531913195
},
{
"number": 10,
"sign": "Leo",
"degree": 14.375460667638691,
"longitude": 134.3754606676387
},
{
"number": 11,
"sign": "Virgo",
"degree": 17.26921159616782,
"longitude": 167.26921159616782
},
{
"number": 12,
"sign": "Libra",
"degree": 14.67330657058804,
"longitude": 194.67330657058804
}
],
"compositeAscendant": {
"sign": "Scorpio",
"degree": 6.947368350486414,
"longitude": 216.9473683504864
},
"compositeMidheaven": {
"sign": "Leo",
"degree": 14.375460667638691,
"longitude": 134.3754606676387
},
"aspects": [
{
"planet1": "North Node",
"planet2": "South Node",
"type": "OPPOSITION",
"angle": 180,
"orb": 0,
"isApplying": false,
"strength": 100,
"interpretation": "challenging"
},
{
"planet1": "Mercury",
"planet2": "North Node",
"type": "OPPOSITION",
"angle": 180,
"orb": 0.07826851524703216,
"isApplying": true,
"strength": 99.0216435594121,
"interpretation": "challenging"
},
{
"planet1": "Mercury",
"planet2": "South Node",
"type": "CONJUNCTION",
"angle": 0,
"orb": 0.07826851524704637,
"isApplying": true,
"strength": 99.02164355941193,
"interpretation": "neutral"
},
{
"planet1": "Sun",
"planet2": "Jupiter",
"type": "CONJUNCTION",
"angle": 0,
"orb": 0.39457481533511896,
"isApplying": false,
"strength": 95.06781480831101,
"interpretation": "neutral"
},
{
"planet1": "Jupiter",
"planet2": "Saturn",
"type": "OPPOSITION",
"angle": 180,
"orb": 0.6664061842696185,
"isApplying": false,
"strength": 91.66992269662977,
"interpretation": "challenging"
},
{
"planet1": "Mercury",
"planet2": "Uranus",
"type": "QUINCUNX",
"angle": 150,
"orb": 0.32416654840960746,
"isApplying": false,
"strength": 89.19444838634641,
"interpretation": "challenging"
},
{
"planet1": "Sun",
"planet2": "Saturn",
"type": "OPPOSITION",
"angle": 180,
"orb": 1.0609809996047375,
"isApplying": false,
"strength": 86.73773750494078,
"interpretation": "challenging"
},
{
"planet1": "Uranus",
"planet2": "North Node",
"type": "SEMI_SEXTILE",
"angle": 30,
"orb": 0.4024350636566396,
"isApplying": false,
"strength": 86.58549787811202,
"interpretation": "neutral"
},
{
"planet1": "Uranus",
"planet2": "South Node",
"type": "QUINCUNX",
"angle": 150,
"orb": 0.4024350636566396,
"isApplying": false,
"strength": 86.58549787811202,
"interpretation": "challenging"
},
{
"planet1": "Neptune",
"planet2": "Black Moon Lilith",
"type": "SEMI_SQUARE",
"angle": 45,
"orb": 0.4262752188309946,
"isApplying": false,
"strength": 78.68623905845027,
"interpretation": "challenging"
},
{
"planet1": "Saturn",
"planet2": "Chiron",
"type": "OPPOSITION",
"angle": 180,
"orb": 2.6864875638378294,
"isApplying": true,
"strength": 66.41890545202713,
"interpretation": "challenging"
},
{
"planet1": "Neptune",
"planet2": "Pluto",
"type": "SEXTILE",
"angle": 60,
"orb": 2.0838835344630127,
"isApplying": false,
"strength": 65.26860775894978,
"interpretation": "harmonious"
},
{
"planet1": "Moon",
"planet2": "Venus",
"type": "SEXTILE",
"angle": 60,
"orb": 2.3328559105867868,
"isApplying": false,
"strength": 61.11906815688688,
"interpretation": "harmonious"
},
{
"planet1": "Jupiter",
"planet2": "Chiron",
"type": "CONJUNCTION",
"angle": 0,
"orb": 3.352893748107448,
"isApplying": false,
"strength": 58.0888281486569,
"interpretation": "neutral"
},
{
"planet1": "Moon",
"planet2": "Black Moon Lilith",
"type": "QUINCUNX",
"angle": 150,
"orb": 1.2713340468812078,
"isApplying": true,
"strength": 57.62219843729308,
"interpretation": "challenging"
},
{
"planet1": "Sun",
"planet2": "Chiron",
"type": "CONJUNCTION",
"angle": 0,
"orb": 3.747468563442567,
"isApplying": false,
"strength": 53.156642956967914,
"interpretation": "neutral"
},
{
"planet1": "Pluto",
"planet2": "Chiron",
"type": "TRINE",
"angle": 120,
"orb": 4.2591709320442135,
"isApplying": false,
"strength": 46.76036334944733,
"interpretation": "harmonious"
},
{
"planet1": "Sun",
"planet2": "Venus",
"type": "SEMI_SEXTILE",
"angle": 30,
"orb": 1.7315622314132213,
"isApplying": false,
"strength": 42.28125895289262,
"interpretation": "neutral"
},
{
"planet1": "Sun",
"planet2": "Moon",
"type": "SQUARE",
"angle": 90,
"orb": 4.064418142000008,
"isApplying": false,
"strength": 41.936883685714164,
"interpretation": "challenging"
},
{
"planet1": "Mars",
"planet2": "Uranus",
"type": "TRINE",
"angle": 120,
"orb": 4.832852544835703,
"isApplying": true,
"strength": 39.589343189553716,
"interpretation": "harmonious"
},
{
"planet1": "Moon",
"planet2": "Mars",
"type": "CONJUNCTION",
"angle": 0,
"orb": 5.054490583801698,
"isApplying": true,
"strength": 36.81886770247878,
"interpretation": "neutral"
},
{
"planet1": "Moon",
"planet2": "Jupiter",
"type": "SQUARE",
"angle": 90,
"orb": 4.458992957335127,
"isApplying": false,
"strength": 36.30010060949819,
"interpretation": "challenging"
},
{
"planet1": "Sun",
"planet2": "Black Moon Lilith",
"type": "TRINE",
"angle": 120,
"orb": 5.335752188881202,
"isApplying": true,
"strength": 33.30309763898498,
"interpretation": "harmonious"
},
{
"planet1": "Venus",
"planet2": "Jupiter",
"type": "SEMI_SEXTILE",
"angle": 30,
"orb": 2.1261370467483403,
"isApplying": false,
"strength": 29.128765108388656,
"interpretation": "neutral"
},
{
"planet1": "Jupiter",
"planet2": "Black Moon Lilith",
"type": "TRINE",
"angle": 120,
"orb": 5.730327004216321,
"isApplying": true,
"strength": 28.370912447295993,
"interpretation": "harmonious"
},
{
"planet1": "Moon",
"planet2": "Saturn",
"type": "SQUARE",
"angle": 90,
"orb": 5.12539914160476,
"isApplying": false,
"strength": 26.780012262789143,
"interpretation": "challenging"
},
{
"planet1": "Mercury",
"planet2": "Mars",
"type": "SQUARE",
"angle": 90,
"orb": 5.157019093245296,
"isApplying": false,
"strength": 26.328298667924344,
"interpretation": "challenging"
},
{
"planet1": "Uranus",
"planet2": "Neptune",
"type": "CONJUNCTION",
"angle": 0,
"orb": 5.957715699412802,
"isApplying": false,
"strength": 25.528553757339978,
"interpretation": "neutral"
},
{
"planet1": "Mars",
"planet2": "North Node",
"type": "SQUARE",
"angle": 90,
"orb": 5.235287608492342,
"isApplying": true,
"strength": 25.210177021537973,
"interpretation": "challenging"
},
{
"planet1": "Mars",
"planet2": "South Node",
"type": "SQUARE",
"angle": 90,
"orb": 5.235287608492342,
"isApplying": true,
"strength": 25.210177021537973,
"interpretation": "challenging"
},
{
"planet1": "Neptune",
"planet2": "Chiron",
"type": "OPPOSITION",
"angle": 180,
"orb": 6.343054466507226,
"isApplying": false,
"strength": 20.711819168659673,
"interpretation": "challenging"
},
{
"planet1": "Venus",
"planet2": "Saturn",
"type": "QUINCUNX",
"angle": 150,
"orb": 2.7925432310179588,
"isApplying": false,
"strength": 6.915225632734712,
"interpretation": "challenging"
},
{
"planet1": "Jupiter",
"planet2": "Pluto",
"type": "TRINE",
"angle": 120,
"orb": 7.612064680151661,
"isApplying": false,
"strength": 4.849191498104233,
"interpretation": "harmonious"
}
],
"interpretation": {
"summary": "This relationship has dynamic energy with areas requiring conscious effort and growth.",
"strengths": [
"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 aries shows your emotional bond and how you nurture each other. This reveals your shared feelings and domestic life together.",
"The composite Venus in gemini reveals what you value together and how you express affection. This is the love language of your relationship."
],
"challenges": [
"More challenging aspects than harmonious - requires work and understanding."
]
}
}Response fields
| Field | Type | Description |
|---|---|---|
| person1* | object | First person birth details. |
| person1.date* | string (date) | Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day. |
| person1.time* | string (time) | Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown. |
| person1.latitude* | number | Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South. |
| person1.longitude* | number | Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West. |
| person1.timezone* | number | Timezone offset from UTC in decimal hours, resolved for the birth date. Examples: New York = -5 in winter and -4 in summer, London = 0, India = 5.5, Tokyo = 9. |
| person2* | object | Second person birth details. |
| person2.date* | string (date) | Birth date in YYYY-MM-DD format. Determines planetary positions for the specific calendar day. |
| person2.time* | string (time) | Birth time in 24-hour HH:MM:SS format. Determines the Ascendant (rising sign) and house cusps. Use 12:00:00 if unknown. |
| person2.latitude* | number | Birth location latitude in decimal degrees (-90 to 90). Positive = North, negative = South. |
| person2.longitude* | number | Birth location longitude in decimal degrees (-180 to 180). Positive = East, negative = West. |
| person2.timezone* | number | Timezone offset from UTC in decimal hours, resolved for the birth date. Examples: New York = -5 in winter and -4 in summer, London = 0, India = 5.5, Tokyo = 9. |
| compositePlanets* | array of object | Composite planetary positions calculated as midpoints between both charts. Each planet represents a shared energy in the relationship. |
| compositePlanets[].name* | string enum | 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 lunar 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. |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
| compositePlanets[].longitude* | number | Apparent geocentric tropical longitude on the true ecliptic of date, in degrees (0-360): light time and aberration applied, nutation included, the convention desktop chart software and the NASA JPL Horizons observer tables print, so it compares directly with either. Primary coordinate for zodiac sign and aspect calculations. |
| compositePlanets[].latitude* | number | Apparent geocentric ecliptic latitude of date, 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). |
| compositePlanets[].sign* | string | Tropical zodiac sign this planet occupies. Determined by 30-degree divisions of ecliptic longitude. |
| compositePlanets[].degree* | number | Degree within the zodiac sign (0-29.999). Indicates how far the planet has progressed through the sign. |
| compositePlanets[].house* | integer | House placement (1-12). Determined by the selected house system and birth location. |
| compositePlanets[].speed* | number | Daily motion in degrees per day. Negative values indicate retrograde motion. |
| compositePlanets[].isRetrograde* | boolean | Whether the planet appears to move backward from Earth perspective. Retrograde periods signal review and introspection. |
| compositePlanets[].compositeInterpretation | object | Composite interpretation for this planet in the relationship chart. |
| compositePlanets[].compositeInterpretation.summary* | string | Narrative interpretation of this composite planet placement. |
| compositePlanets[].compositeInterpretation.relationshipMeaning* | string | What this planet represents in the context of the relationship. |
| compositePlanets[].compositeInterpretation.keywords* | array of string | Key themes associated with this composite placement. |
| compositeHouses* | array of object | Composite house cusps, each the midpoint of the two natal cusps. Each house represents shared life areas in the relationship. |
| compositeHouses[].number* | number | House number (1-12) in the composite chart. |
| compositeHouses[].sign* | string | Zodiac sign on the composite house cusp. |
| compositeHouses[].degree* | number | Degree within the zodiac sign (0-29.999). |
| compositeHouses[].longitude* | number | Absolute ecliptic longitude in degrees (0-360). |
| compositeAscendant* | object | Composite Ascendant. Represents how the relationship presents itself to the outside world. |
| compositeAscendant.sign* | string | Zodiac sign on the composite Ascendant. |
| compositeAscendant.degree* | number | Degree within the sign (0-29.999). |
| compositeAscendant.longitude* | number | Absolute ecliptic longitude in degrees (0-360). |
| compositeMidheaven* | object | Composite Midheaven (MC). Represents shared goals, public image, and the direction the relationship grows toward. |
| compositeMidheaven.sign* | string | Zodiac sign on the composite Midheaven. |
| compositeMidheaven.degree* | number | Degree within the sign (0-29.999). |
| compositeMidheaven.longitude* | number | Absolute ecliptic longitude in degrees (0-360). |
| aspects* | array of object | Aspects between composite planets. Reveals the internal dynamics and energy patterns within the relationship. |
| aspects[].planet1* | string enum | First planet in the aspect pair. |
| aspects[].planet2* | string enum | Second planet in the aspect pair. |
| aspects[].type* | string enum | Aspect type. Major: conjunction (0), opposition (180), trine (120), square (90), sextile (60). Minor: semi-sextile, quincunx, semi-square, sesquiquadrate. |
| aspects[].angle* | number | Exact angular separation that defines this aspect type in degrees. |
| aspects[].orb* | number | Deviation from exact aspect in degrees. Tighter orb means stronger influence. |
| aspects[].isApplying* | boolean | Whether the aspect is applying (planets moving toward exact) or separating (moving apart). Applying aspects grow stronger. |
| aspects[].strength* | number | Aspect strength percentage (0-100). Based on orb tightness relative to the allowed maximum. |
| aspects[].interpretation* | string enum | 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. |
| interpretation* | object | Composite chart interpretation with relationship strengths, challenges, and overall assessment. |
| interpretation.summary* | string | Overall relationship interpretation based on composite chart analysis. |
| interpretation.strengths* | array of string | Areas where the relationship naturally thrives. |
| interpretation.challenges* | array of string | Potential friction points and growth opportunities in the relationship. |
Supported options
lang
entrdeeshiptfrruzh-Hanszh-Hant
houseSystem
placiduswhole-signequalkoch
Call it in your language.
Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.astrology.generateCompositeChart({ body: { person1: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York', nodeType: 'true' }, person2: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: 'America/New_York', nodeType: 'true' } } })Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.astrology.generate_composite_chart(person1={'date': '1990-07-15', 'time': '14:30:00', 'latitude': 40.7128, 'longitude': -74.006, 'timezone': 'America/New_York', 'nodeType': 'true'}, person2={'date': '1990-07-15', 'time': '14:30:00', 'latitude': 40.7128, 'longitude': -74.006, 'timezone': 'America/New_York', 'nodeType': 'true'})Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->astrology->generateCompositeChart(person1: ['date' => '1990-07-15', 'time' => '14:30:00', 'latitude' => 40.7128, 'longitude' => -74.006, 'timezone' => 'America/New_York', 'nodeType' => 'true'], person2: ['date' => '1990-07-15', 'time' => '14:30:00', 'latitude' => 40.7128, 'longitude' => -74.006, 'timezone' => 'America/New_York', 'nodeType' => 'true']);Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Astrology.CompositeChart.PostAsync(new() { /* request fields above */ });Install: dotnet add package RoxyApi.Sdk
Go
import roxyapi "github.com/RoxyAPI/sdk-go"
roxy, _ := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
resp, _ := roxy.Astrology.GenerateCompositeChart(ctx, nil, roxyapi.GenerateCompositeChartJSONRequestBody{ /* request fields above */ })Install: go get github.com/RoxyAPI/sdk-go
cURL
curl -X POST "https://roxyapi.com/api/v2/astrology/composite-chart" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"person1":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York","nodeType":"true"},"person2":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York","nodeType":"true"}}'Prefer to try before you write code? Run this Western Astrology endpoint live in the API playground and inspect a real production response.
Remote MCP for AI agents
Every Western Astrology endpoint is a callable tool on the Remote MCP server over Streamable HTTP. No local setup, no Docker. Claude, ChatGPT, Cursor, and any MCP client auto-discover the tools and ground their answers in verified data.
Claude Code / Cursor
claude mcp add --transport http \
roxy-astrology https://roxyapi.com/mcp/astrology \
--header "X-API-Key: YOUR_KEY"Tool name for POST /astrology/composite-chart: post_astrology_composite_chart. Full MCP setup guide
What you can build
Launch natal chart apps with professional-grade accuracy: birth charts, planet positions, house placements, aspects, and element analysis ready for your UI
Add zodiac compatibility scoring to dating apps: synastry analysis, composite charts, and compatibility scores with detailed relationship dynamics
Ship personalized horoscope platforms: editorial daily, weekly, monthly, and yearly columns with unique content per sign, the dated events each one rests on returned beside the prose for fact-checking, active transit metadata, Moon phase data, and any past or future period on request for editorial pre-publishing
Build AI astrology chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers and calls every astrology endpoint with zero integration code
Power wellness and lifestyle apps with real-time transits, moon phase calendars, solar returns, and planetary movement alerts for self-discovery features
Create astrology content engines: automated zodiac content with house-based uniqueness per sign, horoscope newsletters with real lunar event dates, transit alerts, and year-ahead pages built from every eclipse and every retrograde and direct station of the year with the house each one falls in for that sign
Related capabilities
Composite Chart API FAQ
What does the Composite Chart API return?
Generate a composite chart by calculating midpoints between two natal charts. Every response is structured JSON with documented fields, not free text, so you map it straight into your product.
How do I authenticate with the Composite Chart API?
Pass your key in the X-API-Key header on every request. Keys are delivered instantly at checkout with no approval queue. Use a secret sk key server side, or mint a publishable pk key locked to your origins for browser and no-code use.
Does the Composite Chart API support multiple languages?
Yes. Append the lang query parameter to any endpoint for responses in English, German, Spanish, French, Hindi, Portuguese, Russian and Turkish. The translated payload includes the full interpretation text, not just field labels.
Do I need coordinates to call the Composite Chart API?
No. Call GET /location/search with a city name first, then pass latitude, longitude, and timezone from the first result into the request. Never ask users to type coordinates. Timezone accepts a decimal offset or an IANA name.
Is the Composite Chart API available over Remote MCP for AI agents?
Yes. Every endpoint is exposed as a callable tool on the Remote MCP server at https://roxyapi.com/mcp/astrology over Streamable HTTP, so Claude, ChatGPT, Cursor, and any MCP client auto-discover it with no local setup or Docker.
How is the Composite Chart API billed?
Flat pricing: 1 request equals 1 quota unit, REST and MCP identical, with no credit weighting or per-token markup. Every plan includes all 18 domains, so the Composite Chart API is included at no extra cost.
What houseSystem values does the Composite Chart API accept?
The houseSystem parameter accepts placidus, whole-sign, equal, koch. Case-insensitive where it is a path value.
Start using Composite Chart API today.
Birth charts checked cusp by cusp, and horoscopes that name the dated sky events behind each reading.
All 18 domains included with every plan. Every endpoint, MCP server, SDK, and templates.
Plans from $39/mo, starting at $1.80 per domain on annual billing. No credit card required for testing.
View Pricing & Get API Key