Composite Chart API
Midpoint relationship chart with interpretations
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. 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
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
# 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 (ISO 639-1). Supported: en, tr, de, es, hi, pt, fr, ru. Defaults to en. Languages without translations yet return 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: 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. |
| 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: 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. |
| houseSystem | string enum | House system for the composite chart. Placidus (default), Whole Sign, Equal, or Koch. |
Example request
{
"person1": {
"date": "1990-07-15",
"time": "14:30:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -5
},
"person2": {
"date": "1990-07-15",
"time": "14:30:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -5
}
}Response
Structured JSON with documented fields, verified against NASA JPL Horizons across 828 gold-standard tests. Not hallucinated text.
{
"person1": {
"date": "1990-07-15",
"time": "14:30:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -5
},
"person2": {
"date": "1990-07-15",
"time": "14:30:00",
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -5
},
"compositePlanets": [
{
"name": "Sun",
"longitude": 112.45,
"latitude": 0.01,
"sign": "Cancer",
"degree": 22.45,
"house": 7,
"speed": 0.9571,
"isRetrograde": false
}
],
"compositeHouses": [
{
"number": 1,
"sign": "Gemini",
"degree": 15.32,
"longitude": 75.32
}
],
"compositeAscendant": {
"sign": "Gemini",
"degree": 15.32,
"longitude": 75.32
},
"compositeMidheaven": {
"sign": "Aquarius",
"degree": 8.76,
"longitude": 308.76
},
"aspects": [
{
"planet1": "Sun",
"planet2": "Moon",
"type": "TRINE",
"angle": 120,
"orb": 2.5,
"isApplying": true,
"strength": 75,
"interpretation": "harmonious"
}
],
"interpretation": {
"summary": "string",
"strengths": [
"string"
],
"challenges": [
"string"
]
}
}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. Examples: New York = -5, 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. Examples: New York = -5, 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). |
Show all fieldsShow fewer fields
| Field | Type | Description |
|---|---|---|
| compositePlanets[].longitude* | number | Tropical ecliptic longitude in degrees (0-360). Primary coordinate for zodiac sign and aspect calculations. |
| compositePlanets[].latitude* | number | 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). |
| 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 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. |
| 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
houseSystem
Call it in your language in seconds.
Every snippet is generated from the live OpenAPI spec, so method names, parameters, and fields always match production.
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: -5 }, person2: { date: '1990-07-15', time: '14:30:00', latitude: 40.7128, longitude: -74.006, timezone: -5 } } })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': -5}, person2={'date': '1990-07-15', 'time': '14:30:00', 'latitude': 40.7128, 'longitude': -74.006, 'timezone': -5})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' => -5], person2: ['date' => '1990-07-15', 'time' => '14:30:00', 'latitude' => 40.7128, 'longitude' => -74.006, 'timezone' => -5]);using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.Astrology.CompositeChart.PostAsync(new() { /* request fields above */ });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 */ })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":-5},"person2":{"date":"1990-07-15","time":"14:30:00","latitude":40.7128,"longitude":-74.006,"timezone":-5}}'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 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 in days
Add zodiac compatibility scoring to dating apps: synastry analysis, composite charts, and compatibility scores with detailed relationship dynamics
Ship personalized horoscope platforms: publisher-grade daily, weekly, and monthly forecasts with unique content per sign, active transit metadata, Moon phase data, and date scheduling for editorial pre-publishing
Build AI astrology chatbots with MCP: your OpenAI, Claude, or Gemini agent auto-discovers and calls 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 seasonal forecasts at scale
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 12 domains, so the Composite Chart API is included at no extra cost.
What lang values does the Composite Chart API accept?
The lang parameter accepts en, tr, de, es, hi, pt, fr, ru. Case-insensitive where it is a path value.
Start using Composite Chart API today.
Ship your astrology app this weekend. Not this quarter.
All 12 domains included with every plan. Every endpoint, MCP server, SDK, and starters.
Plans from $39/mo, starting at $2.70 per domain on annual billing. No credit card required for testing.
View Pricing & Get API Key