Vietnamese Zodiac & Age API

From a birth date: lunar year (from Tết), can chi, zodiac animal, nạp âm element (mệnh), cung phi, lunar age, lucky colours and compatible signs.

GETPOSThttps://apibox.io.vn/v1/vn-zodiac

Developer utilities▶ Try it online

The Vietnamese zodiac API computes the traditional attributes of a birth year that many Vietnamese apps show: the lunar year (people born before Tết belong to the previous year, computed with the lunar calendar), the can chi name (Canh Ngọ, Giáp Tý…), the animal (the Vietnamese zodiac has the Cat instead of the Rabbit), the nạp âm destiny element (Lộ Bàng Thổ – “road-side earth”), and its generating and overcoming elements with associated colours.

With gender it adds the cung phi of the Eight Mansions (Khảm, Ly, Càn…), its element, direction and East / West group; without it both are returned. The response also gives the western age and the lunar age (tuổi mụ, counted from 1 and incremented at Tết), and the signs in tam hợp (harmony) and tứ hành xung (conflict).

These are cultural beliefs, useful for wedding, feng-shui, gift and entertainment features; the calculations follow the common traditional tables.

Parameters

Name	In	Type	Required
`birth_date`	query\|body	string	no	Birth date `YYYY-MM-DD` (or `year=YYYY`).
`year`	query\|body	number	no	Lunar birth year only.
`gender`	query\|body	string	no	`male` / `female` (or `nam` / `nữ`) for the cung phi.

Example

curl "https://apibox.io.vn/v1/vn-zodiac?birth_date=1990-05-20&gender=male" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-zodiac?birth_date=1990-05-20&gender=male', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/vn-zodiac?birth_date=1990-05-20&gender=male",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-zodiac?birth_date=1990-05-20&gender=male');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "input": "1990-05-20",
  "solar_year": 1990,
  "lunar_year": 1990,
  "can_chi": "Canh Ngọ",
  "can": "Canh",
  "chi": "Ngọ",
  "con_giap": {
    "vi": "Ngựa",
    "en": "Horse"
  },
  "age": {
    "western": 36,
    "lunar": 37
  },
  "menh": {
    "nap_am": "Lộ Bàng Thổ",
    "meaning": "Đất ven đường",
    "element": "Thổ",
    "element_en": "Earth",
    "generated_by": "Hỏa",
    "generates": "Kim",
    "overcomes": "Thủy",
    "overcome_by": "Mộc",
    "lucky_colors": [
      "vàng",
      "nâu đất",
      "đỏ",
      "hồng",
      "cam",
      "tím"
    ],
    "colors_to_avoid": [
      "xanh lá"
    ]
  },
  "cung_phi": {
    "number": 1,
    "cung": "Khảm",
    "element": "Thủy",
    "direction": "Bắc",
    "group": "Đông tứ mệnh"
  },
  "compatible": {
    "tam_hop": [
      "Dần",
      "Tuất"
    ],
    "tu_hanh_xung": [
      "Tý",
      "Mão",
      "Dậu"
    ]
  },
  "disclaimer": "Traditional beliefs, for culture and entertainment."
}

Use cases

Horoscope and lunar calendar apps
Wedding and event planning features
Personalised greetings and gift suggestions
Real-estate apps showing house directions by cung phi

FAQ

Why is my lunar year different from my birth year?

If you were born in January or February before Tết, you belong to the previous lunar year (e.g. 20/01/2000 → Kỷ Mão 1999).

What is tuổi mụ?

The traditional Vietnamese age: 1 at birth, plus one at each lunar new year, so usually 1–2 more than the western age.

Why does gender matter?

The cung phi (Eight Mansions trigram) is computed differently for men and women; the nạp âm element does not depend on gender.

Vietnamese Zodiac & Age API

Parameters

Example

Response

Use cases

FAQ

Related APIs

UUID Generator

Cron Expression Parser

Time & Timezone Converter