Back to Docs

Western Synastry API

Western Synastry API

POST/api/v2/western/synastry

V2 is the recommended raw synastry endpoint. It keeps the detailed calculation response while using the calibrated orb_weighted_v6_astro_factors score model for normalized overall and tension scores.

Full URL

https://api.freeastroapi.com/api/v2/western/synastry
Safe retries with Idempotency-Key

Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.

A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.

Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.

Need Interpreted Cards?

Use the cards endpoint when your UI needs ready-to-render relationship cards instead of the raw calculation matrix.

View Cards Endpoint

Raw Synastry Calculation Data

This endpoint returns deterministic Western synastry data for two natal charts. It is designed for products that need to render their own aspect tables, raw data tabs, house overlay views, scoring breakdowns, or custom interpretation layers.

The detailed response includes the full inter-aspect list, directional house overlays, natal snapshots for both people, score contributors, and relationship archetype metadata. It supports tropical and sidereal calculations through settings.zodiac and settings.sidereal_ayanamsa.

Raw data note:Aspect rows include ids and exact geometry. Sign names and exact zodiac positions live in the returned natal snapshots, so clients can join a_point and b_point to the matching chart positions.
V2 default:Use V2 for new integrations. Tension is a separate friction-intensity axis and is not subtracted from overall; overall is derived from adjusted positive domains.

Architecture & Logic

The calculation engine evaluates both charts with precise planetary positions, then builds a structured relationship model:

  • Inter-Aspects: Person A points are compared to Person B points using the configured aspect set and orb policy.
  • House Overlays: Each chart's planets and requested points are placed into the other person's house system when birth times are known.
  • Scores & Archetypes: Aspect strengths are aggregated into relationship domains and deterministic archetype buckets.
  • V2 Score Model: Normalized domain evidence is refined with capped house overlay, luminary/angle, Saturn, Node, and reciprocity modifiers.

Raw Data Model

Use these response branches to build raw data tables, debug views, or your own interpretation layer.

synastry.aspects[]
Inter-Aspects

Every returned Person A to Person B aspect includes point ids, aspect type, exact aspect angle, separation, orb, applying state, strength, polarity, categories, and contributor weights.

synastry.house_overlays
House Overlays

Two directional arrays show Person A planets in Person B houses and Person B planets in Person A houses, with target house and distance to cusp.

natal.person_a / natal.person_b
Natal Snapshots

Chart snapshots include positions, signs, absolute degrees, houses, speed, cusps, and angles. Join these to aspect rows by point id when rendering sign-degree labels.

synastry.scores
Scores & Contributors

The relationship buckets include overall, romance, communication, stability, intimacy, growth, tension, and ranked aspect contributors.

Points & Aspect Sets

Configure settings.bodies and settings.aspect_set to control the raw matrix.

Default Points

sunmoonmercuryvenusmarsjupitersaturnuranusneptuneplutoascmcnode

Optional Secondary Points

chironlilithvertex

Derived Angles

dscic
majorMajorconjunction, opposition, trine, square, sextile
major_plusMajor Plusmajor aspects plus quincunx
extendedExtendedmajor_plus plus semisextile, semisquare, and sesquisquare

Response Branches

The detailed endpoint returns a complete response by default. Query parameters can remove large branches when you do not need them.

metaEngine version, ephemeris version, resolved settings, warnings, aliases, and calculation hash.
natalOptional chart snapshots for both people. Enabled by default on the detailed endpoint.
synastry.aspectsOptional full aspect matrix. Returned by default unless disabled with query params or include flags.
synastry.house_overlaysOptional directional house overlay lists. Returned by default when both relevant birth times are known.
synastry.highlightsRanked references to notable aspects and overlays.
synastry.scoresScore buckets plus contributor references.
synastry.archetypeRelationship archetype classification and driver references.
synastry.textOptional keyed text entries when `include.text` or `?text=true` is enabled.

Endpoint Modes

VersionModePathBest ForReturned Data
V2Detailed/api/v2/western/synastryNew raw synastry integrations with calibrated scoring.Full raw response plus V2 normalized scores.
V1Detailed/api/v1/western/synastryLegacy raw data tabs, flat response mode, and full debug views.Full aspects, overlays, natal snapshots, legacy scores, archetype.
V1Lite/api/v1/western/synastry/simplifiedLegacy quick compatibility summaries.Top aspects, highlights, scores, archetype.
V1Summary/api/v1/western/synastry/summaryLegacy small narrative previews.Scores, archetype, strengths, challenges, narrative.

Relationship Archetypes

The synthesis engine identifies the core behavioral pattern of the connection:

Soulmates
Romance > 70 & Stability > 60

Rare blend of passion and deep durability.

Kindred Spirits
Intimacy > 65 & Tension < 40

Deep emotional understanding with little friction.

Opposites Attract
Romance > 60 & Tension > 60

High passion fueled by intense differences.

Karmic Lesson
Growth > 60 & Tension > 60

Challenging dynamic meant for evolution.

Steady Rock
Stability > 70

Unshakable foundation and reliability.

Intellectual Powerhouse
Communication > 70

Exceptional mental connection and flow.

Magnetic Attraction
Dominant Romance

Strong romantic and physical chemistry.

Long-Term Anchor
Dominant Stability

A solid foundation for building a future.

Mental Synergy
Dominant Communication

Great intellectual rapport.

Volatile Spark
Dominant Tension

High energy, challenging but transformative.

Catalyst for Change
Dominant Growth

Encourages mutual expansion.

Deep Bond
Dominant Intimacy

Profound emotional safety.

Balanced Connection
Default

A stable mix of various energies.

Discordant Layout
Overall < 40

Significant friction requiring conscious effort.

Request Parameters

Parameter
person_a
Type
Person
Required
Yes
Description
First person's birth data. Location accepts city or lat/lng coordinates.
Parameter
person_b
Type
Person
Required
Yes
Description
Second person's birth data. Accurate birth time is required for houses and angles.
Parameter
settings
Type
SynastrySettings
Required
No
Description
Calculation settings, body selection, orb policy, and response inclusion flags.
Parameter
response_format
Type
"full" | "flat"
Required
No
Description
Default: full. On /synastry, use flat for no-code platforms: returns shallow root fields plus a single text field containing scores, aspects, house overlays, highlights, and enabled text entries.

Synastry Settings

Parameter
zodiac
Type
string
Required
No
Description
tropical (default) or sidereal.
Parameter
sidereal_ayanamsa
Type
string
Required
No
Description
When zodiac is sidereal: lahiri, raman, kp, fagan_bradley, or yukteshwar.
Parameter
house_system
Type
string
Required
No
Description
placidus (default), whole_sign, equal, koch, porphyry, regiomontanus, campanus, or topocentric.
Parameter
node_type
Type
string
Required
No
Description
true (default) or mean. Used when `bodies` includes `node`.
Parameter
bodies
Type
string[]
Required
No
Description
Point list for aspect and overlay calculations. Defaults to planets, ASC, MC, and node.
Parameter
aspect_set
Type
string
Required
No
Description
major (default), major_plus (+quincunx), or extended (+minor aspects).
Parameter
orb_policy
Type
object
Required
No
Description
Custom default, aspect-specific, or body-specific orb controls.
Parameter
include
Type
object
Required
No
Description
Flags for natal snapshots, aspects, overlays, scores, archetype, text, labels, ranges, and scoring definitions.

Timezone Precision

View Technical Specs

Accurate synastry requires precise birth times. The tz_str parameter controls how input times are interpreted.

"AUTO"
(Recommended) The engine resolves the timezone based on the coordinate and date. It automatically switches to LMT (Local Mean Time) for historical dates before standardization.
Explicit
Use a timezone id such as "Europe/Paris" when the client already knows the correct timezone rule.

Optimization & Filtering

The detailed response can be large. Use compression and branch filters when you only need part of the calculation.

Gzip Compression

Send Accept-Encoding: gzip to reduce transfer size for full raw responses.

Query Parameter Filtering

For score-only or archetype-only views, disable the large aspect and overlay branches.

POST /api/v2/western/synastry?aspects=false&overlays=false
Parameter
aspects
Type
boolean
Required
No
Description
Include the full inter-aspect grid. Default: true.
Parameter
overlays
Type
boolean
Required
No
Description
Include Person A planets in Person B houses and Person B planets in Person A houses. Default: true.
Parameter
scores
Type
boolean
Required
No
Description
Include relationship score buckets and contributors. Default: true.
Parameter
archetypes
Type
boolean
Required
No
Description
Include the deterministic relationship archetype. Default: true.
Parameter
text
Type
boolean
Required
No
Description
Include generated text entries for aspect and overlay keys. Default: false.
Parameter
display_point_labels
Type
boolean
Required
No
Description
Include display labels for returned points in meta.display.
Parameter
display_aspect_labels
Type
boolean
Required
No
Description
Include display labels for available aspects in meta.display.
Parameter
strength_labels
Type
boolean
Required
No
Description
Include strength label ranges in resolved settings.
Parameter
ranges
Type
boolean
Required
No
Description
Include resolved orb policy/range metadata.
Parameter
scoring_bucket_definitions
Type
boolean
Required
No
Description
Include definitions for scoring buckets.

Quick Integration

V2 DETAILED
curl -X POST "https://api.freeastroapi.com/api/v2/western/synastry" \
 -H "Content-Type: application/json" \
 -H "Accept-Encoding: gzip" \
 -H "x-api-key: YOUR_KEY" \
 -d '{
    "person_a": { "datetime": "1990-05-15T14:30:00", "location": { "city": "New York, USA" }, "tz_str": "AUTO" },
    "person_b": { "datetime": "1992-08-20T09:15:00", "location": { "city": "Los Angeles, USA" }, "tz_str": "AUTO" },
    "settings": {
        "zodiac": "sidereal",
        "sidereal_ayanamsa": "lahiri",
        "aspect_set": "extended",
        "bodies": ["sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", "pluto", "node", "chiron", "lilith", "asc", "mc", "vertex"],
        "include": {
            "natal_snapshots": true,
            "aspects": true,
            "house_overlays": true,
            "scores": true,
            "archetype": true,
            "text": false
        }
    }
}'

Sample Response

V2

This V2 sample is abbreviated around the scoring contract. Full responses include the same raw aspect, overlay, natal, highlight, and archetype branches as the detailed endpoint.

{
  "meta": {
    "engine": {
      "name": "FreeAstroApi Synastry",
      "version": "2.0.0"
    },
    "settings_resolved": {
      "zodiac": "sidereal",
      "sidereal_ayanamsa": "lahiri",
      "aspect_set": "extended",
      "strength_model": "orb_weighted_v6_astro_factors"
    }
  },
  "synastry": {
    "scores": {
      "overall": 45,
      "romance": 51,
      "communication": 37,
      "stability": 60,
      "intimacy": 51,
      "growth": 41,
      "tension": 68,
      "model": "orb_weighted_v6_astro_factors",
      "scoring_meta": {
        "model": "orb_weighted_v6_astro_factors",
        "calibration_version": "synastry_v2_composite_2026_07",
        "method": "normalized_weighted_domain_evidence_with_astro_factor_modifiers",
        "domain_method": "weighted_average_polarity_logistic_scaled",
        "overall_method": "hybrid_arithmetic_geometric_with_weak_domain_penalty",
        "tension_method": "corpus_calibrated_mean_friction_logistic",
        "astro_factor_method": "capped_additive_feature_modifiers",
        "tension_higher_is_more": true,
        "aspect_count": 153,
        "friction_count": 39,
        "tension_base_score": 64,
        "tension_modifier": 4.4439,
        "domain_scores_base": {
          "romance": 48,
          "communication": 36,
          "stability": 53,
          "intimacy": 49,
          "growth": 37
        },
        "domain_modifiers": {
          "romance": 2.7293,
          "communication": 0.6322,
          "stability": 7.1864,
          "intimacy": 2.0054,
          "growth": 3.8365
        },
        "domain_scores_adjusted": {
          "romance": 51,
          "communication": 37,
          "stability": 60,
          "intimacy": 51,
          "growth": 41
        },
        "fatedness_score": 0,
        "fatedness_band": "low",
        "active_feature_layer_count": 3,
        "confidence_band": "high",
        "score_band": "balanced",
        "tension_band": "moderate"
      }
    },
    "aspects": [
      "Full aspect rows are returned here when aspects=true."
    ],
    "house_overlays": "Directional house overlay arrays are returned here when overlays=true.",
    "archetype": "Relationship archetype metadata is returned here when archetypes=true."
  }
}

FAQ

Can each person be sent as separate fields (year/month/day/hour/minute)?

Yes. The API keeps backwards-compatible support for split birth fields per person. For each person object you can send either:

  • One ISO datetime string in person_*.datetime
  • Or component fields year, month, day, hour, minute

This is the no-code friendly split format and matches Natal-style payloads, including Telegram/Chatplace flows where datetime is collected separately.

{
  "person_a": {
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "city": "New York, USA",
    "tz_str": "AUTO"
  },
  "person_b": {
    "year": 1992,
    "month": 8,
    "day": 20,
    "hour": 9,
    "minute": 15,
    "city": "Los Angeles, USA",
    "tz_str": "AUTO"
  }
}

Is a single ISO datetime string supported?

Yes. This is preferred when you can send a single string:

{
  "person_a": {
    "datetime": "1990-05-15T14:30:00+00:00",
    "location": { "city": "New York, USA" },
    "tz_str": "UTC"
  },
  "person_b": {
    "datetime": "1992-08-20T09:15:00+00:00",
    "location": { "city": "Los Angeles, USA" },
    "tz_str": "UTC"
  }
}

Endpoint behavior was verified live on 2026-06-08 and returned HTTP 200 for this payload shape.

What happens with full ISO + tz_str: "AUTO"?

If you send a full ISO string (with an offset) and tz_str: "AUTO", the engine resolves timezone from each person's location and date, not from the offset in the ISO string.

If you need the ISO-provided offset to be the source of truth, set an explicit timezone in tz_str (for example "UTC" or "Europe/Paris") instead.

{
  "person_a": {
    "datetime": "1990-05-15T14:30:00+01:00",
    "location": { "city": "Paris, France" },
    "tz_str": "AUTO"
  },
  "person_b": {
    "datetime": "1992-08-20T09:15:00-07:00",
    "location": { "city": "Los Angeles, USA" },
    "tz_str": "AUTO"
  }
}