# Feng Shui API

> Free REST API (JSON over HTTPS) for Chinese astrology and feng shui: zodiac signs and Four Pillars stems/branches for year, month, day and hour; astrological allies, enemy, secret friend and Peach Blossom; love and business compatibility; Kua number with favourable directions; Eight Mansions house charts; Xuan Kong Flying Star charts; Lu Ban ruler (lucky dimensions). Dates from 1700-01-01 to 2300-12-31.

Base URL: https://fengshui-api.com/api/v2
OpenAPI 3.1 specification: https://fengshui-api.com/openapi.yaml (JSON: https://fengshui-api.com/openapi.json)
Interactive reference: https://fengshui-api.com/docs
Code examples (cURL, JavaScript, Python, PHP, Go, Java, C#, Ruby): https://fengshui-api.com/examples
Integration ideas: https://fengshui-api.com/use-cases

## Free online calculators (no key needed)

- [Chinese zodiac year sign](https://fengshui-api.com/calculators/chinese-zodiac-year): Your year animal, element and year pillar, with the exact start and end of the Chinese year.
- [Chinese zodiac month sign](https://fengshui-api.com/calculators/chinese-zodiac-month): The lunar or solar month of a date, its animal and month pillar.
- [Chinese zodiac day sign](https://fengshui-api.com/calculators/chinese-zodiac-day): The day animal and Day Master pillar of the 60-day cycle.
- [Chinese zodiac hour sign](https://fengshui-api.com/calculators/chinese-zodiac-hour): Which of the twelve animals rules the two-hour period of your birth.
- [Astrological allies](https://fengshui-api.com/calculators/astrological-allies): The two animals of your trine who share your energy.
- [Astrological enemy (clash)](https://fengshui-api.com/calculators/astrological-enemy): The animal opposite yours on the zodiac wheel.
- [Secret friend](https://fengshui-api.com/calculators/secret-friend): Your "six harmonies" partner — a quiet, loyal ally.
- [Peach Blossom animal](https://fengshui-api.com/calculators/peach-blossom): Your romance-luck animal and its compass direction.
- [Chinese zodiac love compatibility](https://fengshui-api.com/calculators/love-compatibility): How well two birth years match in love, scored 1–4.
- [Chinese zodiac business compatibility](https://fengshui-api.com/calculators/business-compatibility): How well two birth years work together, scored 1–4.
- [Kua number calculator](https://fengshui-api.com/calculators/kua-number): Your Kua number, East/West group and your four best and four worst directions.
- [Eight Mansions (Ba Zhai) house chart](https://fengshui-api.com/calculators/eight-mansions): The good and bad sectors of a home from its facing direction.
- [Flying Star chart calculator](https://fengshui-api.com/calculators/flying-star): The Xuan Kong natal chart of a building for any period and facing.
- [Lucky dimensions (Lu Ban ruler)](https://fengshui-api.com/calculators/lucky-dimensions): Whether a length is auspicious on the Lu Ban ruler, with better alternatives.
## Authentication

Every /api/v2 request (except account creation and key re-issue) needs an API key in the `X-API-Key` header, or `Authorization: Bearer <key>`.
Create a free account at https://fengshui-api.com/account, or with `POST https://fengshui-api.com/api/v2/accounts` and JSON `{"name": "...", "email": "...", "password": "at least 10 characters", "useCase": "optional"}`. The response contains `apiKey`, shown only once. Confirm the e-mail address within 7 days to keep the key active.
Lost key: `POST https://fengshui-api.com/api/v2/api-keys` with JSON `{"email": "...", "password": "..."}` issues a new key (the old one stops working).
Check a key: `GET /api/v2/me`. Delete the account: `DELETE /api/v2/me`.

## Conventions

- Dates are ISO 8601 `YYYY-MM-DD`; times `HH:MM` (24 h).
- `calendar=lunar` (default): years begin at the lunar new year, months at new moons. `calendar=solar`: years begin at Li Chun (about 4 February), months at the 12 "jie" solar terms (Ba Zi convention).
- Calendar data is computed for China Standard Time (UTC+8).
- Errors are RFC 9457 problem details (`application/problem+json`); 422 responses list invalid parameters in `errors`.
- Quota: 1000 requests per key per hour, advertised in the `RateLimit-Policy` and `RateLimit` headers; 429 with `Retry-After` when exceeded.

## Endpoints

- GET /api/v2/zodiac/year?date=1990-06-15[&calendar=lunar|solar] — year animal, element, stem–branch pillar, year start/end
- GET /api/v2/zodiac/month?date=...[&calendar=...] — month animal and pillar; lunar month number and leap flag, or the opening solar term
- GET /api/v2/zodiac/day?date=... — day animal and pillar
- GET /api/v2/zodiac/hour?time=14:30 — double-hour animal (Rat = 23:00–00:59)
- GET /api/v2/zodiac/allies?date=...|animal=Horse — the two trine allies
- GET /api/v2/zodiac/enemy?date=...|animal=... — the clashing animal
- GET /api/v2/zodiac/secret-friend?date=...|animal=... — the six-harmonies partner
- GET /api/v2/zodiac/peach-blossom?date=...|animal=... — Peach Blossom animal and direction
- GET /api/v2/compatibility/love?date1=...&date2=... (or animal1/animal2) — score 1–4 and rating
- GET /api/v2/compatibility/business?date1=...&date2=... — score 1–4 and rating
- GET /api/v2/feng-shui/kua?date=...&gender=male|female — Kua number, East/West group, 4 favourable and 4 unfavourable directions
- GET /api/v2/feng-shui/eight-mansions?facing=180 (degrees) or facing=S — house trigram and the star of each sector
- GET /api/v2/feng-shui/flying-star?facing=0&period=9 (or constructionYear=2025) — base, mountain and water stars per palace and chart type; facing accepts degrees, N1…NW3 or mountain names
- GET /api/v2/feng-shui/lucky-dimension?length=85&unit=cm — Lu Ban ruler section, auspiciousness and nearest auspicious ranges
- GET /health — service health (no key)

## Example

curl -H "X-API-Key: $FENGSHUI_API_KEY" "https://fengshui-api.com/api/v2/feng-shui/kua?date=1985-03-15&gender=female"

## Source

https://github.com/fengshui-api/restApi (MIT licence)