WESTERN ASTROLOGY · JSON REST API

Synastry API

Build a two-person chart comparison around explicit calculations. Each person retains an individual chart, while cross-aspects describe angular relationships between their planets.

AvailablePOST /v1/astrology/synastry

50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗

BUILD AROUND THE DATA

What this API provides.

Compare two birth charts with structured planetary cross-aspects, individual houses and source-linked interpretations. Preview real synastry JSON.

01

Two separately calculated birth charts

02

Major planetary cross-aspects between people

03

The same requested house system applied to both charts

04

Localized paragraphs with person and between-people context

Send

  • person1.birth and person2.birth with separate time zones and coordinates
  • Optional whole_sign, equal or placidus house_system
  • A supported interpretation locale

Receive

  • person1 and person2 chart objects
  • cross_aspects with body names, aspect type and orb
  • Explicit warnings when either time is unknown
FROM THE NUMERICAL RESULT

See the calculated chart.

The original renderer uses the exact positions in this example. These are computed charts, not stock diagrams. JSON remains the authoritative source.

Person 1 natal chart from the Synastry API computed fixture
Person 1 natal chart. Download SVG ↗
Person 2 natal chart from the Synastry API computed fixture
Person 2 natal chart. Download SVG ↗
INSPECT BEFORE SUBSCRIBING

Real input. Real output.

Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.

Request JSON POST /v1/astrology/synastry
{
  "locale": "en",
  "person1": {
    "birth": {
      "date": "1990-05-21",
      "time": "14:30:00",
      "timezone": "Europe/Madrid",
      "latitude": 40.4168,
      "longitude": -3.7038
    }
  },
  "person2": {
    "birth": {
      "date": "1992-02-10",
      "time": "08:15:00",
      "timezone": "Europe/Madrid",
      "latitude": 40.4168,
      "longitude": -3.7038
    }
  }
}
Response JSON · selected fields
{
  "request_id": "f9ec8686058a6db68b69936b09fe3862",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "person1": {
      "birth_time_known": true,
      "at": "1990-05-21T12:30:00Z",
      "planets": {
        "sun": {
          "longitude": 60.19554186,
          "latitude": 0.00015523,
          "distance_au": 1.0121680489,
          "sign": "gemini"
        },
        "moon": {
          "longitude": 18.08236232,
          "latitude": 4.67747445,
          "distance_au": 0.0024294565,
          "sign": "aries"
        },
        "mercury": {
          "longitude": 38.664821,
          "latitude": -3.37497387,
          "distance_au": 0.6700853983,
          "sign": "taurus"
        },
        "venus": {
          "longitude": 19.7137408,
          "latitude": -1.9474912,
          "distance_au": 1.0821255365,
          "sign": "aries"
        }
      },
      "houses": {
        "system": "whole_sign",
        "ascendant": 158.31543091,
        "midheaven": 64.64823285,
        "cusps": [
          150
        ]
      },
      "aspects": [
        {
          "body1": "mercury",
          "body2": "uranus",
          "aspect": "trine",
          "angle": 120
        },
        {
          "body1": "moon",
          "body2": "venus",
          "aspect": "conjunction",
          "angle": 0
        }
      ],
      "warnings": []
    },
    "person2": {
      "birth_time_known": true,
      "at": "1992-02-10T07:15:00Z",
      "planets": {
        "sun": {
          "longitude": 320.80383971,
          "latitude": 0.00006066,
          "distance_au": 0.9867349844,
          "sign": "aquarius"
        },
        "moon": {
          "longitude": 34.11188267,
          "latitude": 4.68041467,
          "distance_au": 0.0025896511,
          "sign": "taurus"
        },
        "mercury": {
          "longitude": 319.23893991,
          "latitude": -2.07468149,
          "distance_au": 1.3991140764,
          "sign": "aquarius"
        },
        "venus": {
          "longitude": 289.66020584,
          "latitude": 0.36680657,
          "distance_au": 1.3597527886,
          "sign": "capricorn"
        }
      },
      "houses": {
        "system": "whole_sign",
        "ascendant": 318.91852555,
        "midheaven": 246.53508331,
        "cusps": [
          300
        ]
      },
      "aspects": [
        {
          "body1": "mars",
          "body2": "pluto",
          "aspect": "sextile",
          "angle": 60
        },
        {
          "body1": "sun",
          "body2": "mercury",
          "aspect": "conjunction",
          "angle": 0
        }
      ],
      "warnings": []
    },
    "cross_aspects": [
      {
        "body1": "pluto",
        "body2": "uranus",
        "aspect": "sextile",
        "angle": 60
      },
      {
        "body1": "venus",
        "body2": "venus",
        "aspect": "square",
        "angle": 90
      }
    ],
    "warnings": []
  },
  "interpretation": {
    "locale": "en",
    "kind": "astrology/synastry",
    "disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
    "coverage": {
      "total_facts": 92,
      "selected_facts": 92,
      "omitted_count": 0,
      "selection_method": "all-source-facts-v1",
      "full_numeric_data_unchanged": true
    },
    "method": {
      "engine": "celestack-original-rules-v1",
      "corpus": "celestack-original-compositional-v1",
      "corpus_version": "2026-11-17.2",
      "fallback_locale": null,
      "editorial_status": "agent-authored; independent linguistic review pending",
      "predictive_validity": "symbolic interpretations are not scientifically validated predictions",
      "chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
    },
    "items": [
      {
        "fact_id": "astrology/synastry.cross_aspects.1",
        "title": "Between the two people · Pluto — Uranus",
        "text": "Context: Between the two people. Pluto — Uranus: sextile · orb 0.01338°. Look for a modest opportunity to connect these themes through practice. Areas to reflect on: change and the use of influence; experimentation and independence.",
        "source": {
          "body1": "pluto",
          "body2": "uranus",
          "aspect": "sextile",
          "angle": 60,
          "orb": 0.013377,
          "id": "astrology/synastry.cross_aspects.1",
          "type": "astro_aspect",
          "at": null,
          "context": [
            "between_people"
          ]
        }
      }
    ]
  },
  "warnings": [],
  "credits_used": 5
}

The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.

cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/astrology/synastry' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: synastry-api-example-001' \
+  --data '{
  "locale": "en",
  "person1": {
    "birth": {
      "date": "1990-05-21",
      "time": "14:30:00",
      "timezone": "Europe/Madrid",
      "latitude": 40.4168,
      "longitude": -3.7038
    }
  },
  "person2": {
    "birth": {
      "date": "1992-02-10",
      "time": "08:15:00",
      "timezone": "Europe/Madrid",
      "latitude": 40.4168,
      "longitude": -3.7038
    }
  }
}'

Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗

YOUR PRODUCT, YOUR EXPERIENCE

Ways to use it.

  • A relationship-chart comparison tool
  • Shared chart views in an astrology application
  • Traceable context for your own compatibility narrative

12 response locales

English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.

Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.

KNOW THE CONVENTIONS

Limits and interpretation.

  • No scientifically validated relationship probability or guaranteed outcome is calculated.
  • Unknown birth times limit the available timed chart data and cross-aspects.
  • This is a comparison of two charts; the midpoint composite is a separate endpoint.

Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗

PREDICTABLE ACCESS

Choose your billing.

Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.

5,000credits per UTC day
60requests per minute
5,000new operation attempts per UTC day
32 MiBmaximum stored JSON result

Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.

DEVELOPER QUESTIONS

Frequently asked questions.

Does synastry return a compatibility percentage?

No. It returns chart data and cross-aspects. The symbolic reading does not convert those into a measured probability that a relationship will succeed.

Can the two people have different birth locations?

Yes. Each birth object has its own latitude, longitude and IANA time zone.

Is a composite chart included?

No. Use the composite endpoint for a shorter-arc midpoint chart. Synastry preserves the two original charts and their cross-aspects.

What does access cost?

Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 5 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API