Feng Shui API

Paste your API key and call any endpoint. Requests go to /api/v2 with the X-API-Key header. No key yet? Create a free account — or use the calculators, which need none.

Reference

The complete, machine-readable contract is the OpenAPI 3.1 specification (JSON), browsable in the interactive docs. The essentials:

Base URL & authentication

All endpoints live under https://fengshui-api.com/api/v2, accept GET query parameters and return JSON. Send your key in the X-API-Key header, or as Authorization: Bearer <key>. Keys never go in the URL.

curl -H "X-API-Key: $FENGSHUI_API_KEY" \
  "https://fengshui-api.com/api/v2/zodiac/year?date=1990-06-15"

Endpoints

Dates and calendars

Dates use ISO 8601 (YYYY-MM-DD) and must fall between 1700-01-01 and 2300-12-31. With calendar=lunar (default) years begin at the lunar new year and months at new moons. With calendar=solar years begin at Li Chun (about 4 February) and months at the twelve "jie" solar terms — the Four Pillars convention. The calendar is computed for China Standard Time (UTC+8).

Errors

Errors follow RFC 9457 (application/problem+json) with the proper HTTP status: 401 missing or invalid key, 404 unknown endpoint, 422 invalid parameters (each listed in errors), 429 quota exceeded.

{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "One or more parameters are invalid.",
  "errors": [{ "parameter": "date", "message": "Must be between 1700-01-01 and 2300-12-31." }]
}

Rate limits

Each key may make 1000 requests per hour. Every response carries the IETF RateLimit-Policy and RateLimit headers (e.g. "hourly";r=998;t=0 — remaining requests and seconds until more are available). When the quota is used up the API answers 429 with Retry-After.

Code examples

# Create an account (or use the sign-up page); the key is shown once
curl -X POST https://fengshui-api.com/api/v2/accounts \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane","email":"[email protected]","password":"a long passphrase","useCase":"Feng shui app"}'

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

# Flying Star chart, period 9, facing 180°
curl -H "X-API-Key: $FENGSHUI_API_KEY" \
  "https://fengshui-api.com/api/v2/feng-shui/flying-star?facing=180&period=9"

import os
import requests

session = requests.Session()
session.headers["X-API-Key"] = os.environ["FENGSHUI_API_KEY"]
BASE = "https://fengshui-api.com/api/v2"

year = session.get(f"{BASE}/zodiac/year", params={"date": "1990-06-15"}).json()
print(year["animal"], year["pillar"]["name"])  # Horse Geng Wu

kua = session.get(f"{BASE}/feng-shui/kua", params={"date": "1985-03-15", "gender": "female"})
kua.raise_for_status()
for d in kua.json()["favorableDirections"]:
    print(d["direction"], d["star"])

const BASE = "https://fengshui-api.com/api/v2";

async function fengShui(path, params) {
  const response = await fetch(`${BASE}${path}?${new URLSearchParams(params)}`, {
    headers: { "X-API-Key": process.env.FENGSHUI_API_KEY },
  });
  if (!response.ok) throw new Error((await response.json()).detail);
  return response.json();
}

const match = await fengShui("/compatibility/love", { date1: "1990-06-15", date2: "1992-03-10" });
console.log(match.score, match.rating);

<?php
$context = stream_context_create(['http' => [
    'header' => 'X-API-Key: ' . getenv('FENGSHUI_API_KEY'),
    'ignore_errors' => true,
]]);
$query = http_build_query(['length' => 85, 'unit' => 'cm']);
$result = json_decode(file_get_contents("https://fengshui-api.com/api/v2/feng-shui/lucky-dimension?$query", false, $context), true);

echo $result['auspicious'] ? 'Lucky' : 'Unlucky', ': ', $result['section']['meaning'];

Flying Star periods

The cycle repeats every 180 years (period 1 again from 2044). Pass constructionYear to let the API choose the period.

The 24 mountains

Measure the facing with a compass standing inside the main entrance and looking out.

Frequently asked questions

Is the API free? Yes — an account gives you a key instantly, with 1000 requests per hour.

Which dates are supported? Every date from 1 January 1700 to 31 December 2300.

How is the Kua number calculated? From the Chinese year and gender following the nine-year Luo Shu cycle: male (11 − year mod 9) mod 9, female (year mod 9 + 4) mod 9, 0 read as 9; a 5 becomes 2 for men and 8 for women.

Lunar or solar calendar? Both — lunar by default, calendar=solar for the Four Pillars convention.

Changelog