Compatibility (Synastry)

Compare two birth charts to get an overall compatibility score with a category breakdown and cross-aspects. Costs 5 credits.

POST /v1/compatibility

Parameters

Name	Type	Required	Description
`person1`	object	Yes	Birth data for person 1.
`person2`	object	Yes	Birth data for person 2.
Each person object has the same fields as the natal-chart body:
`date`	string	Yes	ISO date `YYYY-MM-DD`.
`time`	string	No	Birth time `HH:MM`.
`latitude`	number	Yes	Decimal degrees, north positive.
`longitude`	number	Yes	Decimal degrees, east positive.
`timezone`	string	No	IANA timezone.

Example request

curl -X POST https://api.gitstrology.dev/v1/compatibility \
  -H "X-API-Key: $GITSTROLOGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person1": {
      "date": "1990-03-15",
      "time": "14:30",
      "latitude": 44.8,
      "longitude": 20.4
    },
    "person2": {
      "date": "1988-07-22",
      "time": "09:00",
      "latitude": 40.7,
      "longitude": -74.0
    }
  }'

Example response

{
  "data": {
    "person1": { "sun": "pisces", "moon": "leo", "rising": "gemini" },
    "person2": { "sun": "cancer", "moon": "pisces", "rising": "leo" },
    "overallScore": 78,
    "breakdown": {
      "emotional": 82,
      "physical": 75,
      "mental": 68,
      "values": 80,
      "commitment": 85
    },
    "aspects": [
      {
        "from": { "person": 1, "planet": "sun" },
        "to": { "person": 2, "planet": "moon" },
        "type": "trine",
        "orb": 1.2
      }
    ],
    "summary": "A strong water-sign bond with deep emotional rapport."
  },
  "credits": { "used": 5, "remaining": 95 }
}

Response fields

Field	Type	Description
`data.person1`	object	Sun, moon, and rising of person 1.
`data.person2`	object	Sun, moon, and rising of person 2.
`data.overallScore`	number	Compatibility score, 0–100.
`data.breakdown`	object	Category sub-scores (0–100 each).
`data.breakdown.emotional`	number	Moon–moon harmony.
`data.breakdown.physical`	number	Sun–moon chemistry.
`data.breakdown.mental`	number	Mercury–mercury rapport.
`data.breakdown.values`	number	Venus–mars alignment.
`data.breakdown.commitment`	number	Saturn–sun stability.
`data.aspects`	array	Cross-chart aspects. See below.
`data.summary`	string	Plain-language summary.

Cross-aspect object

Field	Type	Description
`from`	object	`{ person: 1\|2, planet }` source.
`to`	object	`{ person: 1\|2, planet }` target.
`type`	string	Aspect type (trine, square, …).
`orb`	number	Orb in degrees.