Feng Shui API 開發者文檔

Q: Can AI agents call it?

Yes — there is a native MCP endpoint at /v1/mcp (JSON-RPC 2.0, stateless). Add it to Claude Desktop, Cursor or any MCP client and the full tool catalogue becomes available.

A public, keyless API for traditional Chinese calendar and feng shui computation — the same kernel that powers this site's browser tools, serving provenance with every response. If you can curl, you can feng shui.

REST reference: /docs/api/ · AI agents: /docs/mcp/ · Verification format: /docs/fif/

Sixty-second quickstart

$ curl "https://fengshuicalculator.com/v1/calendar?date=1985-02-20"
{
  "ok": true,
  "data": {
    "date_gregorian": "1985-02-20",
    "lunar":    { "display": "农历1985正月初一", "is_leap_month": false },
    "ganzhi":   { "year": "乙丑", "month": "戊寅", "day": "庚寅", "zodiac": "牛",
                  "year_convention": "lichun", "day_boundary": "midnight" },
    "daily_almanac": { "jian_chu": "…", "huang_hei": "…", "liu_yao": "…" }
  },
  "provenance": { "engine_version": "…", "ruleset_id": "…", "input_digest": "…" },
  "disclaimer": "…"
}

That's the whole auth story: none. Endpoints are public, idempotent GETs (plus one POST for replay, one POST for MCP). The response above is real — open it.

What's on offer

Calendar — Gregorian↔lunar with leap months (GB/T 33661-2017 rules), day officers 建除， yellow/black path, six-day cycle, cross-checked against the Hong Kong Observatory 1901–2100.
Four pillars (BaZi) — under both year conventions (Lichun vs Lunar New Year) × both day boundaries (midnight vs 23:00). Where schools differ, all answers are returned side by side.
Solar terms — 24 exact instants per year, DE441-based, with ΔT and midnight-uncertainty margins.
Ming Gua (Kua number) — with the Lichun year boundary computed astronomically, both five-yellow conventions, and eight favourable/unfavourable directions.
Flying stars — full Xuan Kong natal charts with classical pattern labels, 下卦 and 替卦.
MCP — the same catalogue as tools for Claude, Cursor and any MCP client: POST /v1/mcp.

Why this one is different: provenance by default

Every response embeds provenance — engine version, ruleset id, and a SHA-256 input digest over the JCS-canonicalised request (format spec). Anyone can re-send the original request to /v1/replay and check the digest matches: byte-identical reproduction, or an honest mismatch with the reason. The kernel also ships as WebAssembly, so third parties can verify without trusting this server at all — see the engine comparison page for the philosophy in action.

Unimplemented features are listed, not hidden: each endpoint carries rules_not_implemented where anything from the spec is still missing. No endpoint claims a school as "correct" — where lineages differ (year conventions, day boundaries), the API returns the alternatives side by side and links the public dispute register.

Honesty notes

No hard rate limit today; fair use for humans and agents. Bulk jobs: talk to us instead of hammering.
Results are cultural/educational computation, not predictions — every response carries the disclaimer.
All fields are Beijing time (UTC+8) unless stated; historical LMT caveats are surfaced per response, not buried.

FAQ

Is the Feng Shui API free?

Yes. All endpoints are public with no key and no signup — fair-use, idempotent GETs. There is no paid tier yet; when one exists, the free tier will not shrink.

What can it compute?

The Chinese calendar (lunar dates with leap months, day officers, yellow/black path), BaZi four pillars under both year and day-boundary conventions, 24 solar terms with exact instants, Ming Gua (Kua number) with the Lichun boundary, San Yuan periods, and Xuan Kong flying-star charts with pattern labels.

How do I verify a response?

Every response carries provenance: engine version, ruleset id, and a SHA-256 input digest computed over the JCS-canonicalised request. POST the original request to /v1/replay and compare digests — byte-identical reproduction or an honest mismatch. The same kernel runs in your browser, so you can also verify locally with zero trust in this server.

Can AI agents call it?

Yes — there is a native MCP endpoint at /v1/mcp (JSON-RPC 2.0, stateless). Add it to Claude Desktop, Cursor or any MCP client and the full tool catalogue becomes available — setup guide.

What are the limits?

No hard rate limit is enforced today; the service is sized for humans and agents, not bulk scraping. Heavy jobs should use the differential-scripts pattern instead — or ask, before being throttled.

Reference index

REST API reference (all endpoints, parameters, real examples) · MCP endpoint & client setup · Fingerprint Interchange Format (JCS + SHA-256) · Machine-readable index (GET /v1) · Verify a chart in the browser