Vietnamese Good Days (Almanac) API

Vietnamese almanac for any date: hoàng đạo / hắc đạo, 12 trực, 28 mansions, inauspicious days, clashing ages and lucky hours, scored per activity.

GEThttps://apibox.io.vn/v1/vn-good-days

Data & JSON▶ Try it online

The good-days API applies the rules of the traditional Vietnamese almanac (lịch vạn niên) to a date: the day’s can chi and lunar date, its guardian deity among the 12 (hoàng đạo = auspicious, hắc đạo = inauspicious), its trực (one of 12 day officers, with what it suits and what it does not), its mansion among the 28 (nhị thập bát tú), the classic days to avoid (tam nương, nguyệt kỵ, sát chủ, thọ tử, Dương Công kỵ nhật), the clashing ages (tuổi xung) and the six lucky two-hour periods (giờ hoàng đạo).

Add an activity (cuoi-hoi wedding, khai-truong opening, dong-tho groundbreaking, xuat-hanh travel, nhap-trach moving house, ky-ket contract, mua-xe buying a car, nhap-hoc school) and a lunar birth_year to get a score and a verdict (tốt, bình thường, xấu) that take the activity and a personal clash into account. With from / to (up to 366 days) it scans a period, only_good=true keeps the good days and sort=score ranks them.

Months follow the solar terms (tiết khí) for hoàng đạo and trực, and the lunar calendar for the days to avoid, as in printed almanacs. Schools differ: the result is a cultural reference, not advice.

Parameters

Name	In	Type	Required	Default
`date`	query	string	no		`YYYY-MM-DD` (default: today in Vietnam).
`from`	query	string	no		Start of a period to scan (`YYYY-MM-DD`).
`to`	query	string	no		End of the period (default: from + 29 days; at most 366 days).
`activity`	query	string	no		`cuoi-hoi`, `khai-truong`, `dong-tho`, `xuat-hanh`, `nhap-trach`, `ky-ket`, `mua-xe`, `nhap-hoc` (English aliases: wedding, opening, travel, moving…).
`birth_year`	query	number	no		Lunar year of birth (1900–2100) to check clashes.
`only_good`	query	boolean	no	`false`	Period: keep only days with verdict “tốt”.
`sort`	query	string	no		`score`: best days first.
`limit`	query	number	no	`100`	Period: maximum days returned (1–366).
`tho_tu`	query	string	no		`chi`: thọ tử by earthly branch only (some almanacs).

Example

curl "https://apibox.io.vn/v1/vn-good-days?date=2026-11-11&activity=khai-truong&birth_year=1990" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-good-days?date=2026-11-11&activity=khai-truong&birth_year=1990', {
  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-good-days?date=2026-11-11&activity=khai-truong&birth_year=1990",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-good-days?date=2026-11-11&activity=khai-truong&birth_year=1990');
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

{
  "date": "2026-11-11",
  "weekday": "Wednesday",
  "weekday_vi": "Thứ Tư",
  "lunar": {
    "day": 3,
    "month": 10,
    "year": 2026,
    "leap": false,
    "text": "03/10/2026"
  },
  "can_chi_day": "Kỷ Sửu",
  "hoang_dao": {
    "than": "Ngọc Đường",
    "type": "hoàng đạo",
    "good": true
  },
  "truc": {
    "name": "Mãn",
    "good_for": "cầu tài, cúng tế, giao dịch, nhập kho, khai trương",
    "bad_for": "nhậm chức, kiện tụng, an táng"
  },
  "sao": {
    "name": "Chẩn",
    "good": true
  },
  "bad_days": [
    {
      "name": "Tam nương",
      "severity": "hard",
      "note": "Ngày 3, 7, 13, 18, 22, 27 âm lịch"
    }
  ],
  "clashing_ages": [
    "Quý Mùi",
    "Ất Mùi"
  ],
  "clashing_chi": "Mùi",
  "lucky_hours": [
    {
      "chi": "Dần",
      "from": "03:00",
      "to": "05:00"
    },
    {
      "chi": "Mão",
      "from": "05:00",
      "to": "07:00"
    },
    {
      "chi": "Tỵ",
      "from": "09:00",
      "to": "11:00"
    },
    {
      "chi": "Thân",
      "from": "15:00",
      "to": "17:00"
    },
    {
      "chi": "Tuất",
      "from": "19:00",
      "to": "21:00"
    },
    {
      "chi": "Hợi",
      "from": "21:00",
      "to": "23:00"
    }
  ],
  "personal": {
    "birth_year": 1990,
    "can_chi": "Canh Ngọ",
    "clash": null
  },
  "activity": {
    "code": "khai-truong",
    "vi": "Khai trương",
    "en": "Business opening",
    "truc_fit": "good"
  },
  "score": 2,
  "verdict": "xấu",
  "note": "Traditional Vietnamese almanac rules (hoàng đạo by solar month / tiết khí, trực by tiết khí, ngày kỵ by lunar month). For cultural reference only; sources and schools differ."
}

Use cases

“Pick a good day” features in wedding and event apps
Suggest opening or moving dates in real-estate and retail apps
Daily almanac widgets with lucky hours
Calendars that mark tam nương and nguyệt kỵ days

FAQ

Why do almanacs sometimes disagree?

Schools use slightly different tables (for example thọ tử by can chi or by chi only: tho_tu=chi). We follow the most common rules and list each one in the answer.

Is birth_year the solar year?

It is the lunar year of birth: someone born in January 1991 before Tết is a Canh Ngọ (1990).

How is the score computed?

Hoàng đạo +2 / hắc đạo −2, good mansion +1 / bad −1, the trực’s fit with the activity ±2, minus points for days to avoid and personal clashes.

Related APIs

{✓}

Vietnamese Good Days (Almanac) API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON