Tong Shu date selection API

Every day in the window is resolved to its day pillar from the sexagenary cycle, then read through two independent registers. The twelve day officers 建除十二值星 cycle with the month branch and each one carries its own list of what it suits and what it forbids: Full suits signing and celebrating, Close suits almost nothing. The twenty-eight lunar mansions cycle on a seven-day rhythm independent of the officers, and carry their own endorsements. A day passes only when the chosen activity survives both registers. The optional clash filter then removes days whose branch stands opposite the animal you name, which is how the tradition excludes the person the day is being chosen for. The response reports scanned, matched and the breakdown of what was dropped by register and by clash, so an empty answer is legible rather than mysterious.

curl -X POST https://api.astroway.info/v1/chinese/tong-shu/select \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-06-01",
    "to": "2026-06-14",
    "activity": "marriage",
    "avoidClashWith": "Horse"
  }'

{
  "ok": true,
  "data": {
    "activity": "marriage",
    "from": "2026-06-01",
    "to": "2026-06-14",
    "scanned": 14,
    "matched": 5,
    "dropped": { "byRegister": 9, "byClash": 0 },
    "days": [
      {
        "date": "2026-06-02",
        "verdict": "suitable",
        "dayPillar": "Ding-Wei",
        "officer": { "chinese": "滿", "name": "Full", "summary": "Fullness and return. Signing, opening, celebrating." },
        "mansion": { "chinese": "尾", "name": "Tail", "quadrant": "Azure Dragon" },
        "clashesWith": "Ox"
      }
    ]
  }
}

Reach for it in booking flows, event planning, wedding and venue products, clinic scheduling, or anywhere a date picker should quietly prefer some days over others. Because it returns the reasoning and not only the verdict, you can show a user why the third Tuesday is missing rather than silently greying it out. Feed the result into a calendar component directly, or use the counts to decide whether the window needs widening before you ask again.

Both registers come from the printed almanac tradition rather than from an invented ranking, and the endpoint never invents a day: an empty result stays empty and reports which register emptied it. The day boundary is 23:00, consistent with every other Chinese endpoint here. Activity names follow the register's own list, so an unknown activity is refused with a 400 that names the field.