Western Synastry API

POST/api/v1/western/synastry

Full URL

https://api.freeastroapi.com/api/v1/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.

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.

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

Mode	Path	Best For	Returned Data
Detailed	/synastry	Raw data tabs, custom tables, full debug views.	Full aspects, overlays, natal snapshots, scores, archetype.
Lite	/synastry/simplified	Quick compatibility summaries.	Top aspects, highlights, scores, archetype.
Summary	/synastry/summary	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	Type	Required	Description
person_a	Person	Yes	First person's birth data. Location accepts city or lat/lng coordinates.
person_b	Person	Yes	Second person's birth data. Accurate birth time is required for houses and angles.
settings	SynastrySettings	No	Calculation settings, body selection, orb policy, and response inclusion flags.
response_format	"full" \| "flat"	No	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	Type	Required	Description
zodiac	string	No	tropical (default) or sidereal.
sidereal_ayanamsa	string	No	When zodiac is sidereal: lahiri, raman, kp, fagan_bradley, or yukteshwar.
house_system	string	No	placidus (default), whole_sign, equal, koch, porphyry, regiomontanus, campanus, or topocentric.
node_type	string	No	true (default) or mean. Used when `bodies` includes `node`.
bodies	string[]	No	Point list for aspect and overlay calculations. Defaults to planets, ASC, MC, and node.
aspect_set	string	No	major (default), major_plus (+quincunx), or extended (+minor aspects).
orb_policy	object	No	Custom default, aspect-specific, or body-specific orb controls.
include	object	No	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/v1/western/synastry?aspects=false&overlays=false

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

Quick Integration

curl -X POST "https://api.freeastroapi.com/api/v1/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" },
    "response_format": "full",
    "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

{
  "meta": {
    "engine": {
      "name": "FreeAstroApi Synastry",
      "version": "1.0.0"
    },
    "ephemeris": {
      "version": "2.10.03"
    },
    "settings_resolved": {
      "zodiac": "tropical",
      "sidereal_ayanamsa": null,
      "house_system": "placidus",
      "coordinate_system": "geocentric_ecliptic",
      "node_type": "true",
      "bodies": [
        "sun",
        "moon",
        "mercury",
        "venus",
        "mars",
        "jupiter",
        "saturn",
        "uranus",
        "neptune",
        "pluto",
        "asc",
        "mc",
...

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"
  }
}