Западная синастрия API

POST/api/v1/western/synastry

Полный 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.

Нужны интерпретированные карты?

Используйте эндпоинт карточек, когда вашему UI нужны готовые к рендерингу карточки отношений вместо необработанной матрицы вычислений.

Эндпоинт просмотра карточек

Необработанные данные расчета синастрии

Эта эндпоинт возвращает детерминированные западные синастрические данные для двух натальных карт. Он предназначен для продуктов, которым необходимо отображать собственные таблицы аспектов, вкладки необработанных данных, наложенные представления домов, разбивку оценок или пользовательские слои интерпретации.

Подробный ответ включает в себя полный межаспектный список, наложения направленных домов, натальные снимки для обоих людей, участников оценки и метаданные архетипов отношений. Он поддерживает тропические и сидерические расчеты посредством settings.zodiac и settings.sidereal_ayanamsa.

Примечание к необработанным данным:Строки аспектов включают идентификаторы и точную геометрию. Названия знаков и точные положения зодиака живут в возвращенных natal снимки, чтобы клиенты могли присоединиться a_point и b_point к соответствующим позициям на графике.

Архитектура и логика

Механизм вычислений оценивает обе карты с точными положениями планет, а затем строит структурированную модель отношений:

Inter-Aspects: Очки человека А сравниваются с баллами человека Б с использованием настроенного набора аспектов и политики орбиса.
Накладки на дома: Планеты и требуемые точки каждой карты помещаются в систему домов другого человека, когда известно время рождения.
Партитуры и архетипы: Сильные стороны аспектов агрегируются в области отношений и сегменты детерминированных архетипов.

Модель необработанных данных

Используйте эти ветки ответов для создания таблиц необработанных данных, представлений отладки или собственного уровня интерпретации.

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

Накладки на дома

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

Натальные снимки

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

Результаты и участники

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

Наборы точек и аспектов

Configure settings.bodies и settings.aspect_set для управления необработанной матрицей.

Точки по умолчанию

sunmoonmercuryvenusmarsjupitersaturnuranusneptuneplutoascmcnode

Дополнительные второстепенные точки

chironlilithvertex

Производные углы

dscic

majorMajorconjunction, opposition, trine, square, sextile

major_plusМайор Плюсmajor aspects plus quincunx

extendedExtendedmajor_plus plus semisextile, semisquare, and sesquisquare

Ветви ответа

Подробная эндпоинт по умолчанию возвращает полный ответ. Параметры запроса могут удалять большие ветки, когда они вам не нужны.

metaEngine version, ephemeris version, resolved settings, warnings, aliases, and calculation hash.

natalОпциональные снимки карт для обоих людей. По умолчанию включены в 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.

Режимы эндпоинта

Режим	Path	Лучшее для	Возвращенные данные
Подробный	/synastry	Вкладки с необработанными данными, пользовательские таблицы, полные представления отладки.	Полные аспекты, накладки, натальные снимки, оценки, архетипы.
Легкий	/synastry/simplified	Краткое описание совместимости.	Основные аспекты, основные моменты, оценки, архетип.
Сводный	/synastry/summary	Небольшие повествовательные превью.	Очки, архетип, сильные стороны, проблемы, повествование.

Архетипы отношений

Механизм синтеза определяет основной шаблон поведения соединения:

Soulmates

Romance > 70 & Stability > 60

Rare blend of passion and deep durability.

Родственные души

Intimacy > 65 и напряжение < 40

Deep emotional understanding with little friction.

Противоположности притягиваются

Romance > 60 & Tension > 60

High passion fueled by intense differences.

Кармический урок

Growth > 60 & Tension > 60

Challenging dynamic meant for evolution.

Устойчивый Рок

Stability > 70

Unshakable foundation and reliability.

Интеллектуальная электростанция

Communication > 70

Exceptional mental connection and flow.

Магнитное притяжение

Dominant Romance

Strong romantic and physical chemistry.

Долгосрочный якорь

Dominant Stability

A solid foundation for building a future.

Ментальная синергия

Dominant Communication

Great intellectual rapport.

Неустойчивая искра

Dominant Tension

High energy, challenging but transformative.

Катализатор перемен

Dominant Growth

Encourages mutual expansion.

Глубокая связь

Dominant Intimacy

Profound emotional safety.

Сбалансированное соединение

Default

A stable mix of various energies.

Несогласованная планировка

Overall < 40

Significant friction requiring conscious effort.

Параметры запроса

Parameter	Type	Required	Description
person_a	Person	Да	Данные о рождении первого лица. Местоположение принимает координаты города или широты/долготы.
person_b	Person	Да	Данные о рождении второго человека. Точное время рождения необходимо для домов и углов.
settings	SynastrySettings	Нет	Настройки расчета, выбор тела, политика орбиса и флаги включения ответа.
response_format	"full" \| "flat"	Нет	По умолчанию: full. В /synastry используйте Flat для no-code платформ: возвращает плоские корневые поля плюс одно текстовое поле, содержащее оценки, аспекты, наложения домов, выделения и включенные текстовые записи.

Настройки синастрии

Parameter	Type	Required	Description
zodiac	string	Нет	tropical (по умолчанию) или sidereal.
sidereal_ayanamsa	string	Нет	Когда zodiac=sidereal: lahiri, raman, kp, fagan_bradley или yukteshwar.
house_system	string	Нет	placidus (по умолчанию), whole_sign, equal, koch, porphyry, regiomontanus, campanus или topocentric.
node_type	string	Нет	true (по умолчанию) или среднее. Используется, когда `bodys` включает `node`.
bodies	string[]	Нет	Список точек для расчета аспектов и наложений. По умолчанию это планеты, ASC, MC и узел.
aspect_set	string	Нет	основной (по умолчанию), major_plus (+квинунс) или расширенный (+второстепенные аспекты).
orb_policy	object	Нет	Custom элементы управления сферой по умолчанию, для конкретного аспекта или для тела.
include	object	Нет	Флаги для натальных снимков, аспектов, наложений, оценок, архетипов, текста, меток, диапазонов и определений оценок.

Точность часового пояса

Посмотреть технические характеристики

Точная синастрия требует точного времени рождения. tz_str Параметр управляет тем, как интерпретируется время ввода.

"AUTO"

(рекомендуется) Движок определяет часовой пояс на основе координат и даты. Он автоматически переключается на LMT (среднее местное время) для исторических дат до стандартизации.

Explicit

Используйте идентификатор часового пояса, например "Europe/Paris" когда клиент уже знает правильное правило часового пояса.

Оптимизация и фильтрация

Подробный ответ может быть большим. Используйте фильтры сжатия и ветвления, когда вам нужна только часть вычислений.

Gzip-сжатие

Send Принимающая кодировка: gzip чтобы уменьшить размер передачи для полных необработанных ответов.

Фильтрация параметров запроса

Для представлений только для оценки или только для архетипов отключите большие ветки аспекта и наложения.

POST /api/v1/western/synastry?aspects=false&overlays=false

Parameter	Type	Required	Description
aspects	boolean	Нет	Включите полную межаспектную сетку. По умолчанию: true.
overlays	boolean	Нет	Включите планеты Человека А в дома Человека Б и планеты Человека Б в дома Человека А. По умолчанию: true.
scores	boolean	Нет	Включите группы оценок отношений и участников. По умолчанию: true.
archetypes	boolean	Нет	Включите архетип детерминированных отношений. По умолчанию: true.
text	boolean	Нет	Включите сгенерированные текстовые записи для клавиш аспекта и наложения. По умолчанию: false.
display_point_labels	boolean	Нет	Включите отображаемые метки для возвращаемых точек в мета.display.
display_aspect_labels	boolean	Нет	Включите отображаемые метки для доступных аспектов в мета.display.
strength_labels	boolean	Нет	Включите диапазоны меток прочности в разрешенные настройки.
ranges	boolean	Нет	Включите решенные метаданные политики/диапазона сфер.
scoring_bucket_definitions	boolean	Нет	Включите определения сегментов оценки.

Быстрая интеграция

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

Пример ответа

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

Можно ли отправить каждого человека отдельными полями (год/месяц/день/час/минута)?

Да. API поддерживает обратную совместимость для разделения полей рождения на человека. Для каждого объекта person вы можете отправить:

Одна строка даты и времени ISO в person_*.datetime
Или поля компонентов year, month, day, hour, minute

Это удобный для разделения кода формат split input, который соответствует payload в стиле Natal, включая потоки Telegram/Chatplace, где дата и время собираются отдельно.

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

Поддерживается ли одна строка даты и времени ISO?

Да. Это предпочтительнее, если вы можете отправить одну строку:

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

Поведение эндпоинта было проверено в реальном времени 8 июня 2026 г. и вернуло HTTP 200 для этой payload.

Что происходит при полном ISO+ `tz_str: "AUTO"`?

Если вы отправляете полную строку ISO (со смещением) и tz_str: "AUTO", механизм определяет часовой пояс по местоположению и дате каждого человека, а не по смещению в строке ISO.

Если вам нужно, чтобы смещение, предоставленное ISO, было источником истины, установите явный часовой пояс в tz_str (например "UTC" или "Europe/Paris") вместо.

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