Is There a Chinese Almanac API? Tong Shu Data Explained

Search for a Chinese almanac API and most of what comes back is a lunar date converter and a zodiac animal. Those are the easy half. The almanac itself, the printed page a family opens before setting a wedding date or opening a shop, is a per-day reading: which of the twelve officers governs the day, which of the 28 lunar mansions is on duty, which zodiac animal the day clashes with, and the two short lists of what the day suits and what it opposes. That reading is what people search for when they type Tong Shu, and it is a structured document, not prose. This post shows what a Chinese almanac API returns per day, why one field is keyed by number instead of a name, and how to search a planning window for a date instead of reading thirty days by hand.

Is there a Chinese almanac API, and what does it return?

Yes. RoxyAPI serves the almanac as two calls on the Chinese Astrology API. GET /chinese-astrology/calendar/day/{date} returns one day in full, and POST /chinese-astrology/calendar/auspicious-days searches a range for the days a named activity is favoured on. A supporting GET /chinese-astrology/calendar/monthly returns a whole month in one request, and POST /chinese-astrology/calendar/lunar-date converts in both directions.

The naming is worth getting right, because the two words point at different objects. 黄历, written 黃曆 in traditional script, is the almanac itself, the same register in both scripts. Tong Shu, 通書, is the commentary layer that a printed almanac wraps around those tables, and it is the label that reaches English search boxes. Neither word means lunar calendar. A lunar date is one line of an almanac day, alongside the pillars, the officer, the mansion and the activity lists.

Ready to build this? The Chinese Astrology API gives you the almanac day, the month grid, and date selection on one key. See pricing.

What does one Tong Shu day actually contain?

An almanac day is a stack of independent readings that a date choice weighs together, not a single score. Here is a real response for 1 October 2026, captured from production. The three pillars date the day in the sexagenary cycle, the officer rules what the day is for, the mansion tracks the 28 day rotation, and favours and avoids are the two activity lists a reader scans first.

{
  "date": "2026-10-01",
  "lunar": { "year": 2026, "month": 8, "day": 21, "isLeapMonth": false, "monthLength": 29 },
  "yearPillar": { "id": "bing-wu", "chinese": "丙午", "naYin": "Water of the Sky River" },
  "monthPillar": { "id": "ding-you", "chinese": "丁酉", "naYin": "Fire at the Foot of the Hill" },
  "dayPillar": { "id": "wu-shen", "chinese": "戊申", "naYin": "Earth of the Post Road" },
  "dayOfficer": { "id": "bi", "name": "Close", "chinese": "閉", "quality": "inauspicious" },
  "mansion": { "number": 15, "name": "Legs", "chinese": "奎", "planet": "Wood" },
  "clashAnimal": "tiger",
  "favours": ["burial"],
  "avoids": ["opening-business", "wedding", "travel"]
}

Two things in that payload are easy to misread. lunar.month is 8 while the Gregorian month is 10, so a lunisolar month number is never a Gregorian one and treating it as one shifts every date you derive from it. And clashAnimal is a property of the day, not of the reader: anyone born in a Tiger year is the one who traditionally stays away from this date.

Why are the 28 lunar mansions keyed by number and not by name?

Because pinyin cannot tell them apart. The 28 mansions are keyed by their cycle number, 1 to 28, in every response and in every language, since three mansions romanise to wei once tone marks are dropped and two romanise to bi. Any API that used a pinyin identifier here would collide five ways, and the collisions are not rare edge cases. All five fall inside a single month.

This is the mansion column of GET /chinese-astrology/calendar/monthly?year=2026&month=10, filtered to the colliding rows:

October 2026 alone carries all three wei mansions and both bi mansions. The number is the stable key, chinese carries the character, and name plus pinyin are display fields. The same month exposes a second detail worth knowing: the day officer zhi repeats on 7 and 8 October, because the officer sequence is counted against the branch of the solar month and Cold Dew opens a new solar month on the eighth.

How do you find an auspicious wedding date across a whole quarter?

Send an activity and a window, and read back the days that qualify. POST /chinese-astrology/calendar/auspicious-days takes activity, startDate and endDate, plus an optional avoidAnimal, and returns each qualifying day as a complete almanac day rather than a bare date. The range is capped at 93 days, one planning quarter, which is the horizon a date is actually chosen inside.

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/calendar/auspicious-days" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activity":"wedding","startDate":"2026-10-01","endDate":"2026-12-31","avoidAnimal":"rat"}'

const res = await fetch(
  'https://roxyapi.com/api/v2/chinese-astrology/calendar/auspicious-days',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ROXY_API_KEY as string,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      activity: 'wedding',
      startDate: '2026-10-01',
      endDate: '2026-12-31',
      avoidAnimal: 'rat',
    }),
  },
);

const { total, days } = await res.json();
console.log(total, days.map((d) => d.date));

import os, requests

r = requests.post(
    "https://roxyapi.com/api/v2/chinese-astrology/calendar/auspicious-days",
    headers={
        "X-API-Key": os.environ["ROXY_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "activity": "wedding",
        "startDate": "2026-10-01",
        "endDate": "2026-12-31",
        "avoidAnimal": "rat",
    },
)
data = r.json()
print(data["total"], [d["date"] for d in data["days"]])

The unfiltered call returns 14 dates from 6 October to 24 December. Adding "avoidAnimal": "rat" removes 11 October, 23 October and 4 November, the three whose clashAnimal is rat, and total falls to 11. That filter is the difference between a date chosen in the abstract and a date chosen around the people who will be in the room. The ten activity identifiers are wedding, travel, moving-house, opening-business, signing-contracts, construction, groundbreaking, burial, medical-treatment and praying, and sending anything else returns a 400 that lists the full set.

How does the API convert a lunar date without breaking on a leap month?

By taking the leap month as an explicit flag rather than inferring it. POST /chinese-astrology/calendar/lunar-date converts a Gregorian date forward or a lunar year, month and day back, and isLeapMonth decides which pass through a repeated month number you mean. A Chinese lunisolar year of thirteen months repeats one month number, so the same three numbers name two different real dates in those years.

curl -X POST "https://roxyapi.com/api/v2/chinese-astrology/calendar/lunar-date" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lunarYear":2025,"lunarMonth":6,"lunarDay":1,"isLeapMonth":true}'

Lunar year 2025, month 6, day 1 resolves to 25 June 2025. The leap repetition of those same numbers resolves to 25 July 2025, a full month later, and the response reports leapMonthOfYear as 6 so a caller can branch on presence rather than guess. The lunar month lengths differ too, 30 days for the first pass and 29 for the leap one, which is why counting forward from a converted date fails when the flag is dropped.

Which almanac fields stay English when the response is translated?

The ones your code compares against. Every almanac response separates machine values from display values, so ?lang= never changes the shape of a branch in your application. The day officer keeps its pinyin id, favours and avoids keep their kebab case activity identifiers, clashAnimal keeps its English animal id, and the four mansion palaces stay azure-dragon, black-tortoise, white-tiger and vermilion-bird. Everything a human reads is what moves.

Here is 1 October 2026 across four of the ten languages this domain answers in, including simplified and traditional Chinese:

Switch on id and favours, render name and clashAnimalLocalized. The same rule holds when the almanac is read by an AI agent over Remote MCP, where the identifiers are what the model reasons over and the localized strings are what it repeats back to a user.

FAQ

Is there a Chinese almanac API?

Yes. RoxyAPI returns the Chinese almanac as JSON on GET /chinese-astrology/calendar/day/{date}, with the lunisolar date, the year, month and day pillars, the jian chu day officer, the lunar mansion on duty, the clash animal, and the activity lists the day favours and opposes. A month grid and an auspicious date search sit beside it on the same key.

What is the Tong Shu?

Tong Shu, 通書, is the commentary layer of the Chinese almanac, the text a printed almanac wraps around its day tables. The almanac itself is 黄历 in simplified script and 黃曆 in traditional. RoxyAPI serves the day tables that layer is built on, so an application can render the officer, the mansion and the activity lists directly.

How do I find an auspicious wedding date with an API?

Send activity, startDate and endDate to POST /chinese-astrology/calendar/auspicious-days and read the days array. Add avoidAnimal to drop the days that clash with a zodiac animal you want to protect. The window is capped at 93 days and every returned day carries its officer, its pillars and its lunar date, so an application can show the reasoning rather than a bare verdict.

Does the Chinese almanac API return simplified and traditional Chinese?

Yes. The Chinese astrology domain answers in ten languages, including zh-Hans and zh-Hant, on one API key with no extra charge. Machine values such as the officer id and the favours list stay canonical English in every language, so translated output never changes a branch in your code.

Is the Chinese almanac the same as the Chinese lunar calendar?

No. The lunisolar date is one field of an almanac day. The almanac adds the sexagenary pillars, the twelve day officers, the 28 lunar mansions, the clash animal and the activity lists on top of it. RoxyAPI returns the lunar date on its own through POST /chinese-astrology/calendar/lunar-date, and the full reading through the almanac day endpoint.

Conclusion

A Chinese almanac API is a day document, not a date converter: pillars, officer, mansion, clash animal, and the two activity lists that a date choice is actually made from. Add the activity and window search on top and the question stops being what today means and becomes which day in the next quarter to pick. Both live on the Chinese Astrology API, part of 209+ endpoints across 14 insight domains like Western astrology, Vedic astrology and tarot, all on one key.