Daily Alignment

Today's (or any date's) Chinese almanac page, tong shu (通勝 / 黄历), computed from real astronomical positions and shown as a Daily Alignment card: Chinese lunar date (农历), year and day pillars (ganzhi 干支), day officer (建除) and whether the day is favorable, current and next solar term (节气), the day's zodiac animal (生肖) and its relationships, five-phase colour, exact moon phase and the next new and full moon. Covers questions like 'what is today in the Chinese calendar', 'today's almanac', 'lunar date today', 'what day is it in the Chinese calendar', '今天农历', '今天黄历'. Uses the location the client shares when no city is given. Dates 1901 to 2099.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD. Omit for today."
    },
    "city": {
      "type": "string",
      "description": "Optional. City name, e.g. 'Los Angeles' or 'Paris, France'. Omit to use the user's location."
    },
    "timezone": {
      "type": "string",
      "description": "Optional. IANA timezone, e.g. America/Los_Angeles. Omit to use the user's location."
    },
    "include_planetary_hours": {
      "type": "boolean",
      "description": "Include the 24 planetary hours. Default false."
    }
  },
  "additionalProperties": false
}

A month of the Chinese calendar (农历 / 黄历), one entry per day: lunar date, day pillar, day officer and whether it is favorable, moon phase, plus the exact times of new and full moons, the start of each solar term (节气) and each new lunar month. Answers which days are favorable by day officer, when the next new or full moon is, when a solar term or lunar month begins, or when Lunar New Year falls. Uses the location the client shares when no city is given.

{
  "type": "object",
  "properties": {
    "month": {
      "type": "string",
      "description": "YYYY-MM"
    },
    "city": {
      "type": "string",
      "description": "Optional. City name, e.g. 'Los Angeles' or 'Paris, France'. Omit to use the user's location."
    },
    "timezone": {
      "type": "string",
      "description": "Optional. IANA timezone, e.g. America/Los_Angeles. Omit to use the user's location."
    }
  },
  "required": [
    "month"
  ],
  "additionalProperties": false
}

Look up a city to get its IANA timezone and coordinates; useful when a place name may be ambiguous.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

How Daily Alignment calculates each almanac value, with the tradition and sources behind it. Answers how something is computed or what a term means (for example day officer 建除, solar term 节气, day pillar 日柱).

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "Optional key, e.g. dayOfficer, solarTerm, lunarDate, dayPillar, moon. Omit for all."
    }
  },
  "additionalProperties": false
}

The Chinese zodiac animal (生肖), element and yin/yang for a birth date, computed correctly at the boundary: by the popular Lunar New Year rule and by the Start of Spring (立春) rule used in BaZi. Also gives the lunar birthday. Covers questions like 'what is my Chinese zodiac', 'what animal is someone born in January 1990', '我属什么', '生肖'.

{
  "type": "object",
  "properties": {
    "birth_date": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "birth_time": {
      "type": "string",
      "description": "Optional. Local birth time, 24-hour HH:MM."
    },
    "birth_city": {
      "type": "string",
      "description": "Optional. City of birth, e.g. 'Taipei' or 'Paris, France'."
    },
    "birth_timezone": {
      "type": "string",
      "description": "Optional. IANA timezone of the birth place, if no city."
    }
  },
  "required": [
    "birth_date"
  ],
  "additionalProperties": false
}

The Four Pillars of Destiny (BaZi, 八字 / 四柱): year, month, day and hour pillars, the Day Master (日主) and the five-phase count, from a birth date, time and place, using the exact Start of Spring and solar months. Covers questions like 'what is my BaZi', 'my four pillars', 'my day master', '我的八字'. Facts only, no readings.

{
  "type": "object",
  "properties": {
    "birth_date": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "birth_time": {
      "type": "string",
      "description": "Optional. Local birth time, 24-hour HH:MM."
    },
    "birth_city": {
      "type": "string",
      "description": "Optional. City of birth, e.g. 'Taipei' or 'Paris, France'."
    },
    "birth_timezone": {
      "type": "string",
      "description": "Optional. IANA timezone of the birth place, if no city."
    }
  },
  "required": [
    "birth_date"
  ],
  "additionalProperties": false
}

Converts a Chinese lunar calendar date (农历 / 阴历: lunar year, month, day, leap month) to the Western (Gregorian) date. Covers questions like 'when is my lunar birthday this year', 'when is the 15th of the 8th lunar month in 2027', 'Mid-Autumn Festival date', '农历八月十五是哪天'.

{
  "type": "object",
  "properties": {
    "lunar_year": {
      "type": "integer",
      "description": "Lunar year, named by the Western year in which it begins, e.g. 2027."
    },
    "lunar_month": {
      "type": "integer",
      "description": "1 to 12"
    },
    "lunar_day": {
      "type": "integer",
      "description": "1 to 30"
    },
    "is_leap_month": {
      "type": "boolean",
      "description": "True for a leap (intercalary) month. Default false."
    }
  },
  "required": [
    "lunar_year",
    "lunar_month",
    "lunar_day"
  ],
  "additionalProperties": false
}

All 24 solar terms (节气) of a year with their exact local date and time, plus the date of Lunar New Year (春节) and the new zodiac year. Covers questions like 'when is Chinese New Year 2027', 'when is the winter solstice', 'when does spring start in the Chinese calendar', '二十四节气'. Local times use the location the client shares when no city is given.

{
  "type": "object",
  "properties": {
    "year": {
      "type": "integer",
      "description": "Western year, 1901 to 2099"
    },
    "city": {
      "type": "string",
      "description": "Optional. City name. Omit to use the user's location."
    },
    "timezone": {
      "type": "string",
      "description": "Optional. IANA timezone. Omit to use the user's location."
    }
  },
  "required": [
    "year"
  ],
  "additionalProperties": false
}

Where the Sun, Moon and planets are (tropical zodiac sign and degree), which planets are retrograde, and the Moon phase, computed from real astronomy for now or any date. Covers questions like 'what sign is the Moon in', 'is Mercury retrograde', 'where are the planets today', 'today's astrology'. Facts only, no horoscope text. Uses the location the client shares when no city is given.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "YYYY-MM-DD. Omit for right now."
    },
    "city": {
      "type": "string",
      "description": "Optional. City name. Omit to use the user's location."
    },
    "timezone": {
      "type": "string",
      "description": "Optional. IANA timezone. Omit to use the user's location."
    }
  },
  "additionalProperties": false
}