DocsHari Libur

API Hari Libur

Kalender lengkap hari libur nasional, hari libur keagamaan, dan cuti bersama Indonesia.

Ringkasan

Base URL:/api/v1/holidays
Total Data:~25-30 per tahun
Sumber Data:SKB 3 Menteri
Update:Tahunan (sekitar Agustus)

Apa itu Data Hari Libur?

API Hari Libur menyediakan data kalender libur resmi Indonesia yang ditetapkan pemerintah melalui Surat Keputusan Bersama (SKB) 3 Menteri. Data ini mencakup:

TypeDeskripsiContoh
nationalHari libur nasional yang berlaku untuk semua wargaHari Kemerdekaan, Tahun Baru
religiousHari libur keagamaan resmiIdul Fitri, Natal, Nyepi, Waisak
regionalHari libur yang hanya berlaku di daerah tertentuHUT Provinsi, Hari Jadi Kota

Tentang Cuti Bersama

Cuti bersama (isJointLeave: true) adalah hari libur tambahan yang ditetapkan pemerintah, biasanya di antara hari libur resmi dan akhir pekan. Cuti bersama wajib diganti dengan cuti tahunan karyawan atau kebijakan perusahaan.

Endpoints

GET/api/v1/holidays

Mendapatkan daftar hari libur (tanpa pagination)

Query Parameters

ParameterTipeDefaultDeskripsi
yearintegerTahun sekarangTahun kalender yang diinginkan
typestring-Filter tipe: national, religious, regional

Contoh Request

cURL
curl -X GET "https://api.portaldata.id/api/v1/holidays?year=2025" \
  -H "X-API-Key: YOUR_API_KEY"

Contoh Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "date": "2025-01-01",
      "name": "Tahun Baru Masehi",
      "nameEn": "New Year's Day",
      "type": "national",
      "isJointLeave": false,
      "regionId": null,
      "regionName": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "date": "2025-01-29",
      "name": "Tahun Baru Imlek 2576 Kongzili",
      "nameEn": "Chinese New Year 2576",
      "type": "religious",
      "isJointLeave": false,
      "regionId": null,
      "regionName": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "date": "2025-03-29",
      "name": "Hari Raya Nyepi Tahun Baru Saka 1947",
      "nameEn": "Nyepi Day - Hindu New Year 1947",
      "type": "religious",
      "isJointLeave": false,
      "regionId": null,
      "regionName": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "date": "2025-03-31",
      "name": "Cuti Bersama Idul Fitri",
      "nameEn": "Joint Leave for Eid al-Fitr",
      "type": "national",
      "isJointLeave": true,
      "regionId": null,
      "regionName": null
    }
  ],
  "meta": {
    "source": "SKB 3 Menteri",
    "apiVersion": "1.0.0",
    "riskLevel": "medium",
    "nextExpectedUpdate": "2025-08-01"
  },
  "disclaimer": "Reference data only. Not legal or tax advice."
}

Penjelasan Field Response

FieldTipeDeskripsi
idUUIDID unik hari libur
datestringTanggal libur (format: YYYY-MM-DD)
namestringNama hari libur dalam Bahasa Indonesia
nameEnstring | nullNama hari libur dalam Bahasa Inggris
typeenumTipe: national, religious, regional
isJointLeavebooleanTrue jika cuti bersama (mengurangi cuti tahunan)
regionIdinteger | nullID wilayah jika regional holiday
regionNamestring | nullNama wilayah jika regional holiday

Contoh Penggunaan

1. Kalender Libur Tahunan

Menampilkan semua hari libur dalam satu tahun

GET /api/v1/holidays?year=2025

2. Hanya Hari Libur Keagamaan

Filter hanya hari libur keagamaan

GET /api/v1/holidays?year=2025&type=religious

3. Identifikasi Cuti Bersama

Mengambil data dan filter cuti bersama di aplikasi

// Filter isJointLeave === true dari response

Contoh Kode Lengkap

JavaScript - Menghitung Hari Kerja
// Fungsi untuk mengambil hari libur
async function getHolidays(year) {
  const response = await fetch(
    `https://api.portaldata.id/api/v1/holidays?year=${year}`,
    { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
  );
  const { data } = await response.json();
  return data;
}

// Fungsi untuk mengecek apakah tanggal adalah hari kerja
function isWorkday(date, holidays) {
  const dayOfWeek = date.getDay();

  // Cek weekend (Sabtu = 6, Minggu = 0)
  if (dayOfWeek === 0 || dayOfWeek === 6) {
    return false;
  }

  // Cek hari libur
  const dateStr = date.toISOString().split('T')[0];
  const isHoliday = holidays.some(h => h.date === dateStr);

  return !isHoliday;
}

// Fungsi untuk menghitung jumlah hari kerja antara dua tanggal
function countWorkdays(startDate, endDate, holidays) {
  let count = 0;
  const current = new Date(startDate);

  while (current <= endDate) {
    if (isWorkday(current, holidays)) {
      count++;
    }
    current.setDate(current.getDate() + 1);
  }

  return count;
}

// Fungsi untuk menghitung tanggal selesai berdasarkan jumlah hari kerja
function addWorkdays(startDate, workdays, holidays) {
  let count = 0;
  const current = new Date(startDate);

  while (count < workdays) {
    current.setDate(current.getDate() + 1);
    if (isWorkday(current, holidays)) {
      count++;
    }
  }

  return current;
}

// Contoh penggunaan
const holidays2025 = await getHolidays(2025);

// Hitung hari kerja di Januari 2025
const jan1 = new Date('2025-01-01');
const jan31 = new Date('2025-01-31');
const workdaysInJan = countWorkdays(jan1, jan31, holidays2025);
console.log(`Hari kerja di Januari 2025: ${workdaysInJan}`);

// Hitung deadline: 10 hari kerja dari sekarang
const today = new Date();
const deadline = addWorkdays(today, 10, holidays2025);
console.log(`Deadline (10 hari kerja): ${deadline.toDateString()}`);
Python - Kalender dengan Hari Libur
import requests
from datetime import datetime, timedelta
import calendar

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.portaldata.id/api/v1'

class HolidayCalendar:
    def __init__(self, year):
        self.year = year
        self.holidays = self._fetch_holidays()
        self.holiday_dates = {h['date']: h for h in self.holidays}

    def _fetch_holidays(self):
        response = requests.get(
            f'{BASE_URL}/holidays',
            params={'year': self.year},
            headers={'X-API-Key': API_KEY}
        )
        return response.json()['data']

    def is_holiday(self, date):
        """Cek apakah tanggal adalah hari libur"""
        date_str = date.strftime('%Y-%m-%d')
        return date_str in self.holiday_dates

    def get_holiday_info(self, date):
        """Dapatkan info hari libur"""
        date_str = date.strftime('%Y-%m-%d')
        return self.holiday_dates.get(date_str)

    def is_workday(self, date):
        """Cek apakah tanggal adalah hari kerja"""
        # Weekend check
        if date.weekday() >= 5:  # Sabtu = 5, Minggu = 6
            return False
        return not self.is_holiday(date)

    def count_workdays_in_month(self, month):
        """Hitung hari kerja dalam sebulan"""
        _, num_days = calendar.monthrange(self.year, month)
        count = 0
        for day in range(1, num_days + 1):
            date = datetime(self.year, month, day)
            if self.is_workday(date):
                count += 1
        return count

    def get_joint_leaves(self):
        """Dapatkan daftar cuti bersama"""
        return [h for h in self.holidays if h['isJointLeave']]

    def get_long_weekends(self):
        """Identifikasi long weekend potensial"""
        long_weekends = []
        for h in self.holidays:
            if h['isJointLeave']:
                continue
            date = datetime.strptime(h['date'], '%Y-%m-%d')
            weekday = date.weekday()
            # Libur di Jumat atau Senin = long weekend
            if weekday in [0, 4]:  # Senin atau Jumat
                long_weekends.append({
                    'holiday': h,
                    'type': 'long_weekend'
                })
        return long_weekends

# Contoh penggunaan
cal = HolidayCalendar(2025)

# Hitung hari kerja per bulan
for month in range(1, 13):
    workdays = cal.count_workdays_in_month(month)
    month_name = calendar.month_name[month]
    print(f"{month_name}: {workdays} hari kerja")

# Tampilkan cuti bersama
print("\nCuti Bersama 2025:")
for leave in cal.get_joint_leaves():
    print(f"  {leave['date']}: {leave['name']}")

# Long weekend
print("\nLong Weekend 2025:")
for lw in cal.get_long_weekends():
    h = lw['holiday']
    print(f"  {h['date']}: {h['name']}")

Hari Libur Nasional 2025 (Contoh)

TanggalNamaTipeCuti Bersama
2025-01-01Tahun Baru Masehinational-
2025-01-29Tahun Baru Imlekreligious-
2025-03-29Hari Raya Nyepireligious-
2025-03-31Idul Fitri 1446 Hreligious-
2025-04-01Cuti Bersama Idul FitrinationalYa
2025-08-17Hari Kemerdekaan RInational-
2025-12-25Hari Natalreligious-

* Data contoh. Gunakan API untuk mendapatkan data lengkap dan terbaru.

Best Practices

Cache Data Kalender

Kalender hari libur hanya berubah sekali setahun. Cache data per tahun untuk mengurangi request API.

Perhatikan Cuti Bersama

Jangan lupa mengecek field isJointLeave. Cuti bersama perlu penanganan khusus karena memotong cuti tahunan karyawan.

Tanggal Dapat Berubah

Beberapa hari libur keagamaan (seperti Idul Fitri) berdasarkan pengamatan bulan dan dapat bergeser 1 hari. Pastikan sistem Anda siap menerima update.

Lihat Juga