Kua Number API

A person's Kua number, East or West group and eight directions

POST/v1/feng-shui/kua

1 credit · Secret key (test or live) · getKua

The year turns at Li Chun by default, or at Lunar New Year if you choose. The traditional formula needs gender.

Request body

birth Birth required
- date string (date) required
  e.g. "1990-08-13"
- time string
  pattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$ · e.g. "06:30"
- time_accuracy string
  With "unknown", lagna- and house-dependent fields are omitted and listed in warnings — never filled with a noon default.
  one of exact, approximate, unknown · default "exact"
- place Coordinates or object or object required
  Coordinates, a place_id from /v1/places/search, or a free-text query. A vague query returns 422 place_ambiguous with candidates; the API never guesses.
  
  One of:
  1. Coordinates
    Fields
    - latitude number required
      ≥ -90 · ≤ 90
    - longitude number required
      ≥ -180 · ≤ 180
    No other fields are accepted.
  2. object
    Fields
    - place_id string required
    No other fields are accepted.
  3. object
    Fields
    - query string required
      at least 2 characters · at most 120 characters
    No other fields are accepted.
- timezone string
  "auto" (from coordinates AND date), an IANA name, or a fixed offset like "+05:30".
  default "auto"
No other fields are accepted.
gender string required
The traditional formula needs it. Used for this response and not stored.
one of male, female
year_boundary string
one of li_chun, lunar_new_year · default "li_chun"
options object
- lang string required
  one of en, hi · default "en"
No other fields are accepted.

No other fields are accepted.

Response

JSON { data, meta, warnings }, where data is:

year integer required
year_boundary string required
boundaries_agree boolean required
number integer required
gua string required
chinese string required
group string required
one of east, west
home_direction object required
- id string required
- name string required
mansions array of object required
- id string required
- chinese string required
- name string required
- kind string required
  one of good, bad
- direction object required
  Fields
  - id string required
  - name string required

Errors: 400, 401, 403, 404, 422, 429, 500. See error codes.

Example request

curl -X POST 'https://api.astrologics.in/v1/feng-shui/kua' \
  -H 'Authorization: Bearer al_test_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"birth":{"date":"1990-08-13","time":"06:30","place":{"latitude":28.6139,"longitude":77.209}},"gender":"female"}'

Node.js

const res = await fetch("https://api.astrologics.in/v1/feng-shui/kua", {
  method: "POST",
  headers: { Authorization: "Bearer al_test_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    "birth": {
      "date": "1990-08-13",
      "time": "06:30",
      "place": {
        "latitude": 28.6139,
        "longitude": 77.209
      }
    },
    "gender": "female"
  }),
});
console.log(JSON.stringify(await res.json(), null, 2));

Python

import json
import urllib.error
import urllib.request

body = {
    "birth": {
        "date": "1990-08-13",
        "time": "06:30",
        "place": {
            "latitude": 28.6139,
            "longitude": 77.209,
        },
    },
    "gender": "female",
}

req = urllib.request.Request(
    "https://api.astrologics.in/v1/feng-shui/kua",
    method="POST",
    headers={"Authorization": "Bearer al_test_YOUR_KEY", "Content-Type": "application/json"},
    data=json.dumps(body).encode(),
)
try:
    with urllib.request.urlopen(req) as res:
        print(json.dumps(json.load(res), indent=2, ensure_ascii=False))
except urllib.error.HTTPError as err:
    print(err.code, err.read().decode())

PHP

<?php
$ch = curl_init('https://api.astrologics.in/v1/feng-shui/kua');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer al_test_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"birth":{"date":"1990-08-13","time":"06:30","place":{"latitude":28.6139,"longitude":77.209}},"gender":"female"}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch), PHP_EOL;

Example response

200 OK · 2,078 characters

{
  "data": {
    "year": 1990,
    "year_boundary": "li_chun",
    "boundaries_agree": true,
    "number": 8,
    "gua": "gen",
    "chinese": "艮",
    "group": "west",
    "home_direction": {
      "id": "NE",
      "name": "northeast"
    },
    "mansions": [
      {
        "id": "sheng_qi",
        "chinese": "生气",
        "name": "Life Generating",
        "kind": "good",
        "direction": {
          "id": "SW",
          "name": "southwest"
        }
      },
      {
        "id": "tian_yi",
        "chinese": "天医",
        "name": "Heavenly Doctor",
        "kind": "good",
        "direction": {
          "id": "NW",
          "name": "northwest"
        }
      },
      {
        "id": "yan_nian",
        "chinese": "延年",
        "name": "Longevity",
        "kind": "good",
        "direction": {
          "id": "W",
          "name": "west"
        }
      },
      {
        "id": "fu_wei",
        "chinese": "伏位",
        "name": "Stability",
        "kind": "good",
        "direction": {
          "id": "NE",
          "name": "northeast"
        }
      },
      {
        "id": "huo_hai",
        "chinese": "祸害",
        "name": "Mishap",
        "kind": "bad",
        "direction": {
          "id": "S",
          "name": "south"
        }
      },
      {
        "id": "wu_gui",
        "chinese": "五鬼",
        "name": "Five Ghosts",
        "kind": "bad",
        "direction": {
          "id": "N",
          "name": "north"
        }
      },
      {
        "id": "liu_sha",
        "chinese": "六煞",
        "name": "Six Killings",
        "kind": "bad",
        "direction": {
          "id": "E",
          "name": "east"
        }
      },
      {
        "id": "jue_ming",
        "chinese": "绝命",
        "name": "Life Ending",
        "kind": "bad",
        "direction": {
          "id": "SE",
          "name": "southeast"
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_example",
    "api_version": "v1",
    "engine_version": "2026.10.10",
    "mode": "live",
    "credits_charged": 1
  },
  "warnings": []
}

Try it

Test key (optional)

Leave empty to use the shared demo key (limited). Test keys only: never charged. Kept in this browser tab and sent through this site to the API. Create one

Body (JSON)

{
  "birth": {
    "date": "1990-08-13",
    "time": "06:30",
    "place": {
      "latitude": 28.6139,
      "longitude": 77.209
    }
  },
  "gender": "female"
}

Kua Number API

Request body

Response

Example request

Example response

More in Feng Shui