Synastry Calculation for Developers: Comparing Two Charts

About the author: Yasmin Khalidi is a Tarot Practitioner and Numerology Author with 17 years of experience across Jordan, Lebanon, and the UAE. She holds an M.A. in Comparative Religion from the American University of Beirut and has published extensively in Arabic-language spiritual magazines. Her work explores how tarot archetypes, numerological cycles, and astrological compatibility translate meaningfully across cultural and linguistic contexts.

If you are building a dating app, a matchmaking feature, or a relationship insights product, synastry calculation is the astrological engine behind it. Synastry overlays two natal charts and identifies every angular relationship between them. It answers the question: how do the planetary energies of one person interact with those of another? The challenge for developers is that the math spans circular geometry, weighted scoring, and multiple orb systems, all wrapped in domain conventions that are easy to get wrong. This guide walks through the full calculation pipeline, from generating two charts to scoring and storing the results, with working API examples you can ship today.

What is synastry and why developers need it

Synastry is the branch of Western astrology that compares two natal (birth) charts to evaluate relationship dynamics. Each natal chart maps the positions of ten celestial bodies (Sun through Pluto) at the exact moment and location of birth. In synastry, you overlay Chart A onto Chart B and calculate the angular distance between every planet in one chart and every planet in the other. These angular relationships are called inter-chart aspects. A Venus-Mars trine between two charts suggests natural romantic chemistry. A Moon-Saturn square suggests emotional friction. The complete set of inter-chart aspects forms the synastry profile. Dating apps, matrimonial platforms, relationship coaching tools, and AI-powered compatibility features all rely on this calculation. For developers, the value is a structured, scorable dataset that maps human relationship dynamics to numbers.

How synastry calculation works step by step

The synastry calculation pipeline has three stages. First, generate natal charts for both people. Each chart requires a birth date, birth time, and birth location. The output is a set of ecliptic longitudes (0 to 360 degrees) for each planet. Second, compare every planet in Chart A against every planet in Chart B. For ten planets per chart, that is 100 planet pairs. For each pair, compute the shortest angular distance on the ecliptic circle. Third, check whether that angular distance falls within the orb tolerance for any of the five major aspects: conjunction (0 degrees), sextile (60), square (90), trine (120), or opposition (180). If the distance is within orb, you have found an inter-chart aspect. Record the aspect type, the exact orb deviation, and which two planets are involved. This produces a complete synastry profile.

Ready to build this? RoxyAPI Astrology API gives you synastry, composite charts, and compatibility scoring in a single subscription. See pricing.

Solving the 360 degree wrap-around problem

The ecliptic is a circle. When Planet A sits at 355 degrees and Planet B sits at 5 degrees, the naive difference is 350 degrees, but the actual shortest distance is 10 degrees. Every synastry calculation must handle this boundary correctly. The formula is straightforward: compute the absolute difference, then check if it exceeds 180 degrees. If it does, subtract it from 360 to get the shorter arc. In pseudocode: diff = abs(lon1 - lon2); if (diff > 180) diff = 360 - diff;. Once you have the shortest angular distance, compare it against each target angle (0, 60, 90, 120, 180) and check whether the deviation falls within the allowed orb. This single check is the foundation of all aspect detection. Getting it wrong produces phantom aspects near the Aries point (0 degrees longitude) where the circle wraps. Test your implementation with planets at 1 degree and 359 degrees, the correct distance is 2 degrees.

Orb systems: fixed vs proportional tolerance ranges

An orb is the tolerance range around an exact aspect angle. If the allowed orb for a trine is 8 degrees, then any angular distance between 112 and 128 degrees counts as a trine. Two orb systems exist. Fixed orbs assign the same tolerance to every planet: typically 8 degrees for major aspects and 4 degrees for minor ones. This is simple to implement but treats a Sun trine differently from a Pluto trine despite the Sun being far more influential. Proportional orbs assign wider tolerances to luminaries (Sun, Moon) and personal planets (Mercury, Venus, Mars), and narrower tolerances to outer planets (Uranus, Neptune, Pluto). A common scheme grants the Sun and Moon a 10 degree orb for conjunctions while limiting Pluto to 3 degrees. Professional astrologers overwhelmingly use proportional orbs. The strength of an aspect is inversely proportional to the orb: a Venus-Mars trine with a 0.5 degree orb is far more potent than one at 7.8 degrees.

Scoring and weighting inter-chart aspects

Raw aspect lists are not enough for a product. Users want a score. The synastry calculation must weight aspects by three factors: planet importance (Sun and Moon matter more than Neptune), aspect type (conjunctions and oppositions are strongest, sextiles are mildest), and orb tightness (closer to exact means stronger). A common approach assigns each aspect a base score. Harmonious aspects (trine, sextile) add positive points. Challenging aspects (square, opposition) add tension points. Conjunctions are context-dependent: Venus conjunct Mars is romantic, Saturn conjunct Moon is restrictive. The overall compatibility score is the ratio of harmonious to total weighted points. Category scores break this further: romantic compatibility weights Venus-Mars and Sun-Moon aspects, emotional compatibility weights Moon-Moon and Moon-Venus, intellectual compatibility weights Mercury-Mercury. The RoxyAPI compatibility score endpoint returns all of this pre-calculated.

Beyond aspects: house overlays and composite charts

Synastry calculation does not stop at aspects. House overlays show where the planets of one person land in the house system of the other. If your Venus falls in my 7th house (partnerships), that carries specific romantic significance regardless of whether an aspect exists. This requires calculating both full house systems, not just planet positions. Composite charts take synastry further by creating a single chart for the relationship itself. The midpoint method averages each matching planet pair: if Person A has a Sun at 90 degrees and Person B has a Sun at 180 degrees, the composite Sun is at 135 degrees. The same midpoint calculation applies to the Ascendant, Midheaven, and all house cusps. The resulting chart represents the relationship as its own entity, with its own aspects, houses, and interpretive meaning. The RoxyAPI composite chart endpoint handles all midpoint calculations and returns full interpretations.

Working API example: synastry in one request

The RoxyAPI synastry endpoint accepts two sets of birth details and returns the complete inter-chart aspect profile with scoring and analysis. Here is a working example:

curl -X POST https://roxyapi.com/api/v2/astrology/synastry \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person1": {
      "name": "Alex",
      "date": "1990-07-15",
      "time": "14:30:00",
      "latitude": 40.7128,
      "longitude": -74.006,
      "timezone": -5
    },
    "person2": {
      "name": "Jordan",
      "date": "1992-03-20",
      "time": "09:15:00",
      "latitude": 34.0522,
      "longitude": -118.2437,
      "timezone": -8
    },
    "houseSystem": "placidus"
  }'

The response includes person1 and person2 chart summaries (Ascendant, Sun sign, Moon sign), a compatibilityScore (0 to 100), a full interAspects array where each entry contains planet1, planet2, type, orb, strength, interpretation, and relationship-specific meaning, a summary object breaking down harmonious, challenging, and neutral counts, and an analysis with strengths and challenges. Each inter-aspect entry includes the angular distance and a strength percentage based on orb tightness, so you can sort by influence and display the most significant connections first.

For a composite midpoint chart, use a separate endpoint:

curl -X POST https://roxyapi.com/api/v2/astrology/composite-chart \
  -H "X-API-Key: YOUR_API_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": "1992-03-20",
      "time": "09:15:00",
      "latitude": 34.0522,
      "longitude": -118.2437,
      "timezone": -8
    },
    "houseSystem": "placidus"
  }'

This returns compositePlanets with midpoint positions and relationship interpretations, compositeHouses, compositeAscendant, compositeMidheaven, internal aspects, and a full interpretation block with strengths and challenges for the relationship entity.

Data model considerations for synastry results

Storing synastry results requires planning for the combinatorial nature of the data. A single synastry report produces 15 to 30 inter-chart aspects. If your app supports re-calculation (different house systems, updated birth times), you need versioning. A practical schema stores the two person IDs, the calculation parameters (house system, orb system), the overall score, and the raw inter-aspects as a JSON column. Index on the person pair so lookups are fast. For the compatibility score endpoint, store the category breakdown (romantic, emotional, intellectual, physical, spiritual) as separate columns if you plan to filter or sort by category. Cache aggressively: synastry results for the same two birth details and house system are deterministic. The API returns an X-Cache-TTL header, so responses are cached for 24 hours on the server side.

Frequently Asked Questions

Q: What is the difference between synastry and a composite chart? A: Synastry compares two separate charts by finding inter-chart aspects between them. A composite chart creates a single new chart by averaging (midpointing) matching planets from both charts. Synastry shows how two people interact. The composite chart shows the relationship as its own entity with its own personality and themes.

Q: How many inter-chart aspects does a typical synastry calculation produce? A: With ten planets per chart and five major aspect types, a typical synastry profile finds 15 to 30 aspects depending on orb settings. Tighter orbs produce fewer but stronger aspects. The RoxyAPI synastry endpoint returns all detected aspects sorted by strength.

Q: What orb system does the RoxyAPI synastry endpoint use? A: The endpoint uses proportional orbs where luminaries (Sun, Moon) receive wider tolerances and outer planets receive narrower ones. This matches professional astrological practice and produces more meaningful results than fixed-orb systems.

Q: Can I get synastry results broken down by category like romantic or emotional? A: Yes. The compatibility score endpoint at /api/v2/astrology/compatibility-score returns separate scores for romantic, emotional, intellectual, physical, and spiritual compatibility, each based on specific planetary pair interactions. It also includes a relationship archetype classification and element balance analysis.

Q: Do I need to calculate natal charts separately before calling the synastry endpoint? A: No. The synastry endpoint accepts raw birth details for both people and generates both natal charts internally. You send two sets of date, time, latitude, longitude, and timezone, and receive the complete synastry analysis in a single response.

Build synastry into your product today

Synastry calculation turns birth data into structured relationship insights. The math is deterministic: two sets of birth details always produce the same aspect profile. Whether you are building a dating app, a compatibility widget, or an AI relationship advisor, the RoxyAPI Astrology API handles the astronomical calculations, aspect detection, orb weighting, scoring, and interpretation. Planetary positions are verified against NASA JPL Horizons. Start with the synastry endpoint for inter-chart aspects, add the composite chart for relationship entity analysis, and use the compatibility score for category breakdowns your users can act on. See pricing and get your API key in minutes.