Bỏ qua tới nội dung
Nhà phát triển

API Lịch Đỏ

Tài liệu cho nhà phát triển. Các endpoint công khai lấy lịch âm, ngày tốt, ngày lễ, quy đổi và file iCalendar.

Tất cả endpoint đều hỗ trợ CORS, không cần key. Dùng cho ứng dụng web, mobile, widget. Dữ liệu theo múi giờ Việt Nam (UTC+7).

GET

/api/today

Thông tin ngày hôm nay theo múi giờ Việt Nam.

Tham số

Không tham số.

Ví dụ
GET /api/today
Response mẫu
{
  "solar": { "day": 21, "month": 9, "year": 2026, "weekday": "Thứ Hai" },
  "lunar": { "day": 10, "month": 8, "year": 2026, "leap": false },
  "canChi": { "year": "Bính Ngọ", "month": "Giáp Thân", "day": "Giáp Tý" },
  "nowChi": 9
}

Cache 1 giờ.

GET

/api/day

Chi tiết một ngày (dương lịch): âm lịch, can chi, giờ hoàng đạo, sao, trực, ngày lễ, ngày nghỉ.

Tham số

?d=21&m=9&y=2026 (mặc định hôm nay nếu không truyền).

Ví dụ
GET /api/day?d=21&m=9&y=2026
Response mẫu
{
  "solar": { "day": 21, "month": 9, "year": 2026, "weekday": "Thứ Hai" },
  "lunar": { "day": 10, "month": 8, "year": 2026, "leap": false },
  "canChi": { "year": "Bính Ngọ", "month": "Giáp Thân", "day": "Giáp Tý" },
  "hours": [
    { "chi": "Tý", "range": "23:00-01:00", "canChi": "Giáp Tý", "lucky": true },
    ...
  ],
  "holiday": null,
  "isToday": false,
  "tietKhi": { "index": 14, "name": "Bạch Lộ", "span": { "startJd": 2461291, "endJd": 2461306, "start": { "day": 7, "month": 9, "year": 2026 }, "end": { "day": 22, "month": 9, "year": 2026 } } },
  "truc": { "index": 9, "monthChi": "Dậu", "name": "Thành", "tot": true, "meaning": "...", "nen": "...", "ky": "..." },
  "sao28": { "index": 20, "name": "Tất", "tot": false, "nen": "...", "ky": "..." },
  "nguHanh": { "napAm": "Tích Lịch Hỏa", "hanh": "Hỏa" },
  "saoTot": ["Thiên Đức", "Ngọc Đường"],
  "saoXau": ["Thiên Cẩu"],
  "ngayKy": [{ "name": "Ngày Tam Nương", "note": "..." }],
  "huong": { "hyThan": "Đông Nam", "taiThan": "Bắc", "hacThan": "Tây Nam" },
  "thaiThan": "Bắc",
  "nhanThan": "Tây",
  "dayOff": null
}

Cache 1 giờ (hoặc 24 giờ nếu chỉ định ngày).

GET

/api/month

Lịch tháng: các ngày trong tháng kèm âm lịch, ngày lễ, ngày nghỉ, isToday.

Tham số

?month=&year= (mặc định tháng hiện tại).

Ví dụ
GET /api/month?month=9&year=2026
Response mẫu
{
  "month": 9,
  "year": 2026,
  "lead": 1,
  "cells": [
    { "day": 1, "month": 9, "year": 2026, "lunarDay": 20, "lunarMonth": 7, "isToday": false, "isSunday": false, "isSaturday": false, "isCurrentMonth": true },
    ...
  ]
}

Cache 1 giờ (24 giờ nếu chỉ định tháng/năm).

GET

/api/convert

Quy đổi dương ↔ âm lịch.

Tham số

?dir=s2l&d=21&m=9&y=2026 hoặc ?dir=l2s&d=10&m=8&y=2026&leap=0

Ví dụ
GET /api/convert?dir=s2l&d=21&m=9&y=2026
Response mẫu
{
  "ok": true,
  "lunar": { "day": 10, "month": 8, "year": 2026, "leap": false }
}

dir=l2s cần &leap=1 nếu là ngày nhuận. Trả lỗi nếu ngày không hợp lệ.

GET

/api/holidays

Ngày lễ sắp tới và nổi bật trong năm nay + năm sau.

Tham số

Không tham số.

Ví dụ
GET /api/holidays
Response mẫu
{
  "next": {
    "name": "Tết Trung Thu",
    "slug": "trung-thu",
    "date": { "day": 4, "month": 10, "year": 2026 },
    "daysUntil": 13,
    "isPublicHoliday": false,
    "description": "Rằm tháng 8 âm lịch, ngày hội trăng tròn.",
    "daysOff": null
  },
  "upcoming": [ ... ],
  "featured": [ ... ]
}

Cache 1 giờ. daysOff chỉ có với lễ công.

GET

/api/ics

Lịch iCalendar (.ics) các ngày lễ trong năm hoặc theo slug.

Tham số

?year= hoặc ?slug= (năm hoặc lễ cụ thể).

Ví dụ
GET /api/ics?year=2026
Response mẫu
BEGIN:VCALENDAR
VERSION:2.0
... VEVENT cho các ngày lễ ...
END:VCALENDAR

Trả text/calendar (không phải JSON). Cache 1 giờ hoặc 24 giờ. Slug hỗ trợ cả lễ lặp.

Ghi chú sử dụng

  • JSON: UTF-8, không index bởi robot (x-robots-tag).
  • Cache: public max-age 3600s (1 giờ) cho dữ liệu hôm nay; 86400s (24 giờ) cho ngày/tháng/năm chỉ định.
  • ICS: text/calendar theo RFC 5545, có thể import vào Google Calendar, Outlook, Apple Calendar.
  • Ngày tháng luôn dương lịch trừ khi ghi rõ âm.
  • Phạm vi năm: 1900–2100.

Câu hỏi thường gặp

01API có giới hạn tốc độ không?

Hiện không giới hạn cứng. Sử dụng hợp lý, cache header được trả về để bạn tận dụng. Nên cache phía client theo max-age.

02Định dạng response là gì?

Tất cả endpoint JSON trả application/json; charset=utf-8 (trừ /api/ics trả text/calendar). Các trường ngày tháng dùng số nguyên, không có 0-leading.

03Làm sao lấy ngày âm hôm nay?

Gọi /api/today hoặc /api/day. Kết quả lunar chứa day, month, year, leap.

04Quy đổi ngày nhuận âm?

Với /api/convert?dir=l2s thêm &leap=1. Endpoint sẽ kiểm tra hợp lệ.

05Dữ liệu ngày lễ có cập nhật không?

Dựa trên dữ liệu nghỉ lễ công khai và dự kiến. /api/holidays và /api/ics phản ánh thông tin hiện tại.

Xem thêm công cụ trên site: Lịch hôm nay, Xem ngày tốt, Năm nhuận.