Full inter-aspect analysis between two natal charts plus a weighted compatibility score. One key covers 18+ spiritual domains. MCP-first, verified against NASA JPL Horizons.

Synastry is the branch of astrology that examines the inter-chart aspects between two people. This repo ships working TypeScript, JavaScript, and Python samples against the RoxyAPI synastry endpoint. One subscription unlocks 18+ spiritual domains: Western astrology, Vedic astrology, Forecast, Human Design, Chinese astrology, Feng Shui, Mesoamerican astrology, Vastu, numerology, Kabbalah, tarot, biorhythm, Ayurveda, I Ching, crystals, dreams, angel numbers, and location. Every planetary position is computed by Roxy Ephemeris, verified against NASA JPL Horizons. The synastry response returns a compatibility score (0-100), every inter-aspect with orb and strength, and a narrative analysis split into relationship strengths and challenges.

1. Get a key at roxyapi.com/pricing
2. Pick a language below
3. Copy the snippet, run, ship

curl -X POST https://roxyapi.com/api/v2/astrology/synastry \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person1": {
      "name": "Alex",
      "date": "1990-03-21",
      "time": "08:15:00",
      "latitude": 40.7128,
      "longitude": -74.006,
      "timezone": "America/New_York"
    },
    "person2": {
      "name": "Jordan",
      "date": "1992-08-14",
      "time": "14:30:00",
      "latitude": 51.5074,
      "longitude": -0.1278,
      "timezone": "Europe/London"
    }
  }'

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ["ROXY_API_KEY"])

# Synastry: always geocode both birth cities first
loc1 = roxy.location.search_cities(q="New York")
city1 = loc1["cities"][0]

loc2 = roxy.location.search_cities(q="London")
city2 = loc2["cities"][0]

# Synastry analysis between two people
result = roxy.astrology.calculate_synastry(
    person1={
        "name": "Alex",
        "date": "1990-03-21",
        "time": "08:15:00",
        "latitude": city1["latitude"],
        "longitude": city1["longitude"],
        "timezone": city1["timezone"],
    },
    person2={
        "name": "Jordan",
        "date": "1992-08-14",
        "time": "14:30:00",
        "latitude": city2["latitude"],
        "longitude": city2["longitude"],
        "timezone": city2["timezone"],
    },
)

print(result["compatibilityScore"])
for aspect in result["interAspects"][:3]:
    print(aspect["planet1"], "->", aspect["planet2"], aspect["type"], "orb:", aspect["orb"])

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY);

// Synastry: geocode both birth cities first, then compute inter-chart aspects
const { data: loc1 } = await roxy.location.searchCities({ query: { q: 'New York' } });
const { data: loc2 } = await roxy.location.searchCities({ query: { q: 'London' } });

const { data, error } = await roxy.astrology.calculateSynastry({
  body: {
    person1: {
      name: 'Alex',
      date: '1990-03-21',
      time: '08:15:00',
      latitude: loc1.cities[0].latitude,
      longitude: loc1.cities[0].longitude,
      timezone: loc1.cities[0].timezone,
    },
    person2: {
      name: 'Jordan',
      date: '1992-08-14',
      time: '14:30:00',
      latitude: loc2.cities[0].latitude,
      longitude: loc2.cities[0].longitude,
      timezone: loc2.cities[0].timezone,
    },
  },
});

if (error) throw new Error(error.error);

console.log('Compatibility score:', data.compatibilityScore);
data.interAspects.slice(0, 3).forEach(a =>
  console.log(`${a.planet1} -> ${a.planet2} ${a.type} orb: ${a.orb}`)
);

import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

// Synastry: geocode both birth cities, then run full inter-aspect analysis
const { data: loc1 } = await roxy.location.searchCities({ query: { q: 'New York' } });
const { data: loc2 } = await roxy.location.searchCities({ query: { q: 'London' } });

const { data, error } = await roxy.astrology.calculateSynastry({
  body: {
    person1: {
      name: 'Alex',
      date: '1990-03-21',
      time: '08:15:00',
      latitude: loc1.cities[0].latitude,
      longitude: loc1.cities[0].longitude,
      timezone: loc1.cities[0].timezone,
    },
    person2: {
      name: 'Jordan',
      date: '1992-08-14',
      time: '14:30:00',
      latitude: loc2.cities[0].latitude,
      longitude: loc2.cities[0].longitude,
      timezone: loc2.cities[0].timezone,
    },
  },
});

if (error) throw new Error(error.error);

console.log('Compatibility score:', data.compatibilityScore);
console.log('Total inter-aspects:', data.summary.total);
data.interAspects.slice(0, 3).forEach(a =>
  console.log(`${a.planet1} -> ${a.planet2} ${a.type} orb: ${a.orb} strength: ${a.strength}`)
);
console.log('Strengths:', data.analysis.strengths);
console.log('Challenges:', data.analysis.challenges);

{
  "person1": {
    "name": "Alex",
    "ascendant": { "sign": "Taurus", "degree": 15.32 },
    "sunSign": "Aries",
    "moonSign": "Gemini"
  },
  "person2": {
    "name": "Jordan",
    "ascendant": { "sign": "Virgo", "degree": 22.18 },
    "sunSign": "Leo",
    "moonSign": "Scorpio"
  },
  "compatibilityScore": 78,
  "interAspects": [
    {
      "planet1": "Venus",
      "planet2": "Mars",
      "type": "TRINE",
      "angle": 120,
      "orb": 2.5,
      "strength": 75,
      "interpretation": "harmonious",
      "meaning": {
        "name": "Trine",
        "description": { "short": "Natural flow", "long": "..." },
        "keywords": ["harmony", "ease", "attraction"],
        "nature": "harmonious",
        "relationshipContext": "..."
      }
    }
  ],
  "summary": {
    "total": 24,
    "harmonious": 12,
    "challenging": 8,
    "neutral": 4,
    "byType": { "TRINE": 5, "SEXTILE": 7, "SQUARE": 6, "OPPOSITION": 2 }
  },
  "analysis": {
    "overall": "...",
    "strengths": ["Strong Venus-Mars attraction", "..."],
    "challenges": ["Saturn square Moon tension", "..."]
  }
}

• POST /astrology/compatibility-score (calculateCompatibility) - lighter compatibility percent with sign-level blocks, no full inter-aspect table
• POST /astrology/natal-chart (generateNatalChart) - full natal chart per person with planet sign, house, and interpretation
• POST /astrology/transits (calculateTransits) - current sky transits to a natal chart for live timing overlays

Connect Claude, GPT, Gemini, or Cursor to RoxyAPI through the remote MCP server. No Docker. No self hosting. The full MCP tool catalog for this domain is at https://roxyapi.com/mcp/astrology.

{
  "mcpServers": {
    "astrology": {
      "url": "https://roxyapi.com/mcp/astrology",
      "headers": { "X-API-Key": "$ROXY_API_KEY" }
    }
  }
}

See docs/mcp for Claude Desktop, Cursor, Windsurf, VS Code, and Claude Code setup.

This repo ships an AGENTS.md execution playbook. Cursor, Claude Code, Aider, Codex, Windsurf, RooCode, and Gemini CLI will pick it up automatically. Top level overview lives at roxyapi.com/AGENTS.md.

• Methodology and gold standard tests verified against NASA JPL Horizons
• Full API reference interactive Scalar UI
• TypeScript SDK on npm
• Python SDK on PyPI
• PHP SDK on Packagist
• C# SDK on NuGet
• Go SDK on pkg.go.dev
• WordPress plugin
• llms.txt full LLM citation index
• Top level AGENTS.md

MIT for this sample repo. See LICENSE.

Catalog licensing: Personal and commercial use, including closed source proprietary apps. No AGPL or GPL entanglement. RoxyAPI APIs and SDKs are safe to embed in commercial products. Full terms at roxyapi.com/policy/license.

• Site: roxyapi.com
• Status: roxyapi.com/api-reference