Home › Encyclopedia › Zi Wei Dou Shu chart API

Zi Wei Dou Shu chart API

A free, deterministic, read-only API for developers and AI assistants. It returns the 12-palace chart as structured JSON — no AI guesswork — together with the exact conventions used, so results can be reproduced and compared with other tools. Nothing is stored.

Example

GET https://9zi.ai/api/v1/chart?date=1990-05-15&time=07:30&gender=female&city=Beijing&flying=1 curl "https://9zi.ai/api/v1/chart?date=1985-07-04&time=12:00&gender=male&lon=-74&tz=America/New_York"

Parameters

date (YYYY-MM-DD, Gregorian, 1900–2099) and gender (male|female) are required. time is local clock time HH:MM (default 12:00; unknownTime=1 uses noon). Birthplace: either city (about 180 built-in cities, English or Chinese names) or lon (−180..180, east positive) together with tz (IANA time zone such as Asia/Taipei). Optional: yearDivide=normal|exact (Lunar New Year, default, or Li Chun), algorithm=default|zhongzhou, ziRule=same|next (23:00–23:59 counts as the same or the next day), trueSolar=1|0, at=YYYY-MM-DD (date for decade/annual cycles, default today), flying=1 (adds the 48 palace-stem flying transformations). GET query string or POST JSON.

What you get back

trueSolarTime shows every step (UTC offset including historical daylight saving, equation of time, date change); chart holds four pillars, Five Elements Bureau, Soul and Body stars, twelve palaces with major and minor stars (Chinese and English names, brightness, transformations, decade ages) and the birth-year transformations; cycles holds the current decade and year; conventions states year boundary, school and late-Zi rule.

Accuracy

Charts use the open-source iztro engine; its Life Palace, Body Palace, Five Elements Bureau and Zi Wei position were cross-checked against independently implemented classical formulas on 3,000 random charts with 0 mismatches. What was not verified is listed in the verification report.

Use with AI assistants

Because the output is deterministic and carries its conventions, it works well as a tool for LLM function calling: let the model call the API for chart facts and use the model only for interpretation. We also publish a zero-dependency MCP (Model Context Protocol) server that wraps this endpoint, for Claude Desktop, Cursor and other MCP clients (Node 18+): download https://9zi.ai/mcp/9zi-mcp.mjs and add {"mcpServers": {"ziwei-9zi": {"command": "node", "args": ["/absolute/path/9zi-mcp.mjs"]}}} to the client's MCP configuration. It exposes one tool, ziwei_chart, with the parameters above.

Terms

Free to use; up to 60 requests per minute per IP, best effort, no uptime guarantee. Please link back to https://9zi.ai/ when you display results. Charts are for cultural interest and self-exploration — not medical, financial or life-decision advice. The API stores nothing and logs no birth data.

Q: Is there an API key?

No. The API is open and rate limited per IP.

Q: Which year boundary does it use by default?

Lunar New Year (the standard convention); pass yearDivide=exact for Li Chun.