Chinese zodiac compatibility API

Each date is resolved to its solar year, which opens at the Li Chun instant taken from the ephemeris rather than at 1 January or at Chinese New Year. That year gives the earthly branch and its animal. The score then reads the relation between the two branches: the 三合 trines, which group four sets of three branches spaced evenly around the circle, and the 六冲 clashes, which pair each branch with the one directly opposite. Neighbouring and neutral relations fall between. The response returns both resolved animals, a numeric score, a category and a short note explaining what the pairing means, so a UI can show the verdict without a second lookup table.

curl -X POST https://api.astroway.info/v1/chinese/zodiac/compatibility \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "person1": { "date": "1990-05-15" },
    "person2": { "date": "1988-02-20" }
  }'

{
  "ok": true,
  "data": {
    "person1": { "solarYear": 1990, "animal": "Horse" },
    "person2": { "solarYear": 1988, "animal": "Dragon" },
    "compatibility": {
      "score": 65,
      "category": "good",
      "notes": ["Compatible enough; complementary differences."]
    }
  }
}

Reach for it when you want a fast, cheap compatibility signal keyed to a date alone: a matchmaking filter, a shareable card, a quiz, a marketing widget, an onboarding step where asking for a birth time would cost you the conversion. It is the coarsest reading in the catalogue and it is honest about that, since a year animal knows exactly one character out of a person's eight. When the product warrants a real reading, take the full BaZi chart for both people and look at the interactions across all four pillars instead.

The score is derived from 三合 and 六冲 canonical doctrine, not from a hand-written opinion matrix, which is why it is reproducible and explains itself. A birth within a day of Li Chun is the one case where the hour matters: pass time and timezoneOffset and the boundary is resolved to the second. Animal names translate into 21 languages; the English token stays in place.