Compatibility

Calculate astrological compatibility between two birth charts based on sun sign elements and the aspect between their natal Sun positions.

Required Module

Requires the compatibility:calc module.

Calculate Compatibility

curl -X POST "https://api.astroapi.cloud/api/calc/compatibility" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime1": "1990-06-15T14:30",
    "location1": {
      "longitude": -0.1278,
      "latitude": 51.5074,
      "timezone": "Europe/London"
    },
    "dateTime2": "1988-03-22T09:15",
    "location2": {
      "longitude": 2.3522,
      "latitude": 48.8566,
      "timezone": "Europe/Paris"
    },
    "language": "en",
    "includeText": true,
    "includeReadableEntities": true
  }'

Parameters

Parameter	Type	Required	Description
dateTime1	string	Yes	First person's birth date and time in YYYY-MM-DDTHH:mm format
location1	object	Yes	First person's birth location (longitude, latitude, timezone)
dateTime2	string	Yes	Second person's birth date and time in YYYY-MM-DDTHH:mm format
location2	object	Yes	Second person's birth location (longitude, latitude, timezone)
language	string	No	Language code for text content (default: "en")
includeText	boolean	No	Include interpretation text (default: false)
includeReadableEntities	boolean	No	Include human-readable sign titles (default: false)

Location Object

{
    "longitude": -0.1278,
    "latitude": 51.5074,
    "timezone": "Europe/London"
}

Response

{
    "data": {
        "sign1": "gemini",
        "sign2": "aries",
        "scoreBasedOnElement": 80,
        "scoreBasedOnSunAspect": 85,
        "sign1Title": "Gemini",
        "sign2Title": "Aries",
        "text": "Gemini and Aries form a lively and stimulating combination. Both signs are drawn to new ideas and fast-paced experiences. Aries brings passion and directness while Gemini adds wit and versatility..."
    }
}

Response Fields

Field	Type	Description
sign1	string	Zodiac sign of the first person
sign2	string	Zodiac sign of the second person
scoreBasedOnElement	number	Compatibility score (0–100) based on elemental affinity
scoreBasedOnSunAspect	number	Compatibility score (0–100) based on the exact Sun-to-Sun aspect
sign1Title	string | null	Human-readable sign name (only if includeReadableEntities: true)
sign2Title	string | null	Human-readable sign name (only if includeReadableEntities: true)
text	string | null	Interpretation text (only if includeText: true)

---

Scoring Methods

Element-Based Score

Compatibility is assessed based on the elemental relationship between the two Sun signs:

Relationship	Score	Sign Pairs
Same element	90	Fire+Fire, Earth+Earth, Air+Air, Water+Water
Compatible elements	80	Fire+Air, Earth+Water
Neutral elements	65	Fire+Earth, Air+Water
Challenging elements	50	Fire+Water, Earth+Air

Sun Aspect Score

Compatibility is also assessed based on the exact aspect between the two natal Sun positions:

Aspect	Score	Notes
Conjunction (0°)	95	Same degree, very strong bond
Trine (120°)	92	Natural harmony and ease
Sextile (60°)	85	Friendly and supportive
Opposition (180°)	70	Magnetic attraction with tension
Square (90°)	55	Dynamic but challenging
Quincunx (150°)	45	Adjustment and growth required

Two Scores

The element score gives a quick overview based on traditional sign affinities. The Sun aspect score is more precise because it is calculated from the exact degree of both natal Suns, making it unique to the specific individuals rather than their signs alone.

---

Elemental Groups

Element	Signs
Fire	Aries, Leo, Sagittarius
Earth	Taurus, Virgo, Capricorn
Air	Gemini, Libra, Aquarius
Water	Cancer, Scorpio, Pisces

Going Deeper

For a more comprehensive compatibility analysis, consider using the Synastry endpoint, which calculates inter-chart aspects between all planets in both charts and provides house overlays.