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).
/api/today
Thông tin ngày hôm nay theo múi giờ Việt Nam.
Không tham số.
GET /api/today{
"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ờ.
/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ỉ.
?d=21&m=9&y=2026 (mặc định hôm nay nếu không truyền).
GET /api/day?d=21&m=9&y=2026{
"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).
/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.
?month=&year= (mặc định tháng hiện tại).
GET /api/month?month=9&year=2026{
"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).
/api/convert
Quy đổi dương ↔ âm lịch.
?dir=s2l&d=21&m=9&y=2026 hoặc ?dir=l2s&d=10&m=8&y=2026&leap=0
GET /api/convert?dir=s2l&d=21&m=9&y=2026{
"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ệ.
/api/holidays
Ngày lễ sắp tới và nổi bật trong năm nay + năm sau.
Không tham số.
GET /api/holidays{
"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.
/api/ics
Lịch iCalendar (.ics) các ngày lễ trong năm hoặc theo slug.
?year= hoặc ?slug= (năm hoặc lễ cụ thể).
GET /api/ics?year=2026BEGIN:VCALENDAR
VERSION:2.0
... VEVENT cho các ngày lễ ...
END:VCALENDARTrả 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.