API Hari Libur Nasional Indonesia: Cek Libur dan Hitung Hari Kerja

API hari libur nasional adalah layanan HTTP yang memberi tahu apakah sebuah tanggal adalah hari libur atau cuti bersama di Indonesia, lengkap dengan keterangannya. Di APIPedia ada empat endpoint untuk ini: cek satu tanggal, daftar libur setahun, libur terdekat, dan hitung jumlah hari kerja antara dua tanggal.

Artikel ini membahas keempat endpoint tersebut, bentuk responsnya, dan contoh pemakaian yang paling sering dibutuhkan: menghitung tenggat SLA, estimasi tanggal pengiriman, dan jumlah hari kerja untuk penggajian.

Kenapa perlu API hari libur, bukan tabel manual?

Daftar tanggal merah di Indonesia berubah setiap tahun. Banyak hari raya mengikuti kalender Hijriah, Imlek, atau Saka, sehingga tanggal Masehinya bergeser. Pemerintah juga menetapkan cuti bersama lewat SKB tiga menteri, dan jadwalnya kadang direvisi.

Menyimpan tabel sendiri berarti seseorang harus ingat memperbaruinya tiap tahun. Kalau lupa, sistem tiket menghitung tenggat yang salah dan estimasi kirim di toko online meleset. Dengan API, data libur dikelola di satu tempat dan aplikasi cukup bertanya.

Apa saja endpoint API hari libur di APIPedia?

Semua endpoint memakai metode GET, base URL https://api.apipedia.id/v1, dan header Authorization: Bearer apk_xxx. Format tanggal selalu YYYY-MM-DD.

Endpoint	Fungsi	Parameter
/libur/cek/{tanggal}	Cek apakah satu tanggal libur nasional, cuti bersama, atau akhir pekan	tanggal di path
/libur/tahun/{tahun}	Daftar libur nasional dan cuti bersama dalam satu tahun	tahun di path, mis. 2026
/libur/berikutnya	Hari libur terdekat beserta sisa harinya	dari (opsional, default hari ini)
/libur/hari-kerja	Jumlah hari kerja di antara dua tanggal	mulai, sampai (wajib)

Seperti endpoint APIPedia lainnya, respons dibungkus amplop { is_success, message, data }. Cek is_success dulu sebelum membaca data.

Bagaimana cara mengecek apakah sebuah tanggal tanggal merah?

Panggil /libur/cek/{tanggal}. Endpoint ini menjawab dua pertanyaan sekaligus: apakah tanggal itu libur, dan apakah jatuh di akhir pekan.

curl https://api.apipedia.id/v1/libur/cek/2026-12-25 \
  -H "Authorization: Bearer apk_xxx"

{
  "is_success": true,
  "message": "Tanggal 2026-12-25 adalah hari libur nasional",
  "data": {
    "tanggal": "2026-12-25",
    "hari": "Jumat",
    "is_libur": true,
    "is_akhir_pekan": false,
    "jenis": "libur_nasional",
    "keterangan": "Kelahiran Yesus Kristus (Natal)"
  }
}

Field	Tipe	Keterangan
tanggal	string	Tanggal yang dicek
hari	string	Nama hari dalam bahasa Indonesia
is_libur	boolean	true bila libur nasional atau cuti bersama
is_akhir_pekan	boolean	true bila Sabtu atau Minggu
jenis	string	libur_nasional atau cuti_bersama
keterangan	string	Nama hari libur

Karena is_libur dan is_akhir_pekan dipisah, Anda bisa memutuskan sendiri aturannya. Misalnya layanan pelanggan tetap buka di hari Sabtu, tapi tutup di libur nasional.

Bagaimana mengambil daftar libur nasional dan cuti bersama setahun?

/libur/tahun/{tahun} mengembalikan jumlah dan larik libur. Setiap item berisi tanggal, keterangan, jenis, dan hari. Untuk 2026, endpoint ini mengembalikan 25 entri yang terdiri dari libur nasional dan cuti bersama.

curl https://api.apipedia.id/v1/libur/tahun/2026 \
  -H "Authorization: Bearer apk_xxx"

{
  "tahun": 2026,
  "jumlah": 25,
  "libur": [
    { "tanggal": "2026-01-01", "keterangan": "Tahun Baru Masehi 2026",
      "jenis": "libur_nasional", "hari": "Kamis" },
    { "tanggal": "2026-03-20", "keterangan": "Cuti Bersama Idulfitri 1447 H",
      "jenis": "cuti_bersama", "hari": "Jumat" }
  ]
}

Endpoint ini paling cocok untuk kalender di aplikasi HR, halaman "jadwal operasional", atau perencanaan kampanye promo. Karena isinya hanya berubah bila pemerintah merevisi SKB, ambil sekali lalu simpan di cache selama beberapa jam atau sehari.

Libur nasional vs cuti bersama

Field jenis membedakan keduanya. Libur nasional berlaku untuk semua, sedangkan cuti bersama pada praktiknya mengurangi jatah cuti tahunan karyawan dan tidak selalu diikuti sektor swasta. Kalau perusahaan Anda tetap beroperasi di hari cuti bersama, saring entri dengan jenis === "cuti_bersama" sebelum menghitung.

Bagaimana menampilkan hitung mundur ke libur berikutnya?

/libur/berikutnya mengembalikan satu hari libur terdekat beserta sisa_hari. Tanpa parameter, pencarian dimulai dari hari ini. Isi dari bila ingin mencari mulai tanggal tertentu.

curl "https://api.apipedia.id/v1/libur/berikutnya?dari=2026-10-26" \
  -H "Authorization: Bearer apk_xxx"

{
  "tanggal": "2026-12-25",
  "keterangan": "Kelahiran Yesus Kristus (Natal)",
  "jenis": "libur_nasional",
  "hari": "Jumat",
  "sisa_hari": 60
}

Hasil ini pas untuk widget "60 hari lagi menuju Natal" atau pengingat internal agar tim menyiapkan jadwal piket.

Bagaimana menghitung jumlah hari kerja antara dua tanggal?

/libur/hari-kerja menghitung berapa hari kerja di antara mulai dan sampai, dengan mengeluarkan akhir pekan dan hari libur. Kedua tanggal ikut dihitung.

curl "https://api.apipedia.id/v1/libur/hari-kerja?mulai=2026-12-01&sampai=2026-12-31" \
  -H "Authorization: Bearer apk_xxx"

{
  "mulai": "2026-12-01",
  "sampai": "2026-12-31",
  "total_hari": 31,
  "akhir_pekan": 8,
  "libur": 2,
  "hari_kerja": 21
}

Rinciannya transparan: 31 hari kalender dikurangi 8 hari Sabtu-Minggu dan 2 hari libur (cuti bersama 24 Desember dan Natal 25 Desember) menghasilkan 21 hari kerja. Perhatikan bahwa cuti bersama ikut dihitung sebagai libur, jadi sesuaikan bila kebijakan kantor Anda berbeda.

Contoh: menghitung tenggat SLA dalam hari kerja

Kasus umum di sistem tiket: "tiket harus dijawab dalam 3 hari kerja". Caranya, majukan tanggal satu per satu dan lewati hari yang bukan hari kerja. Agar hemat kuota, ambil daftar libur setahun sekali, lalu lakukan perhitungannya di kode Anda sendiri.

const BASE = "https://api.apipedia.id/v1";
const headers = { Authorization: `Bearer ${process.env.APIPEDIA_KEY}` }; // apk_xxx
const cache = new Map();

async function tanggalLibur(tahun) {
  if (cache.has(tahun)) return cache.get(tahun);
  const res = await fetch(`${BASE}/libur/tahun/${tahun}`, { headers });
  const body = await res.json();
  if (!body.is_success) throw new Error(body.message);
  const set = new Set(body.data.libur.map((l) => l.tanggal));
  cache.set(tahun, set);
  return set;
}

function iso(d) {
  return d.toISOString().slice(0, 10);
}

export async function tambahHariKerja(mulai, n) {
  const d = new Date(`${mulai}T00:00:00Z`);
  let sisa = n;
  while (sisa > 0) {
    d.setUTCDate(d.getUTCDate() + 1);
    const libur = await tanggalLibur(d.getUTCFullYear());
    const akhirPekan = d.getUTCDay() === 0 || d.getUTCDay() === 6;
    if (!akhirPekan && !libur.has(iso(d))) sisa--;
  }
  return iso(d);
}

// Tiket masuk Rabu 23 Des 2026, tenggat 3 hari kerja
console.log(await tambahHariKerja("2026-12-23", 3)); // "2026-12-30"

Pada contoh di atas, 24 dan 25 Desember serta akhir pekan dilewati, sehingga tenggat jatuh pada 30 Desember 2026, bukan 28 Desember. Fungsi yang sama bisa dipakai untuk estimasi tanggal tiba paket. Gabungkan dengan API cek ongkir untuk menampilkan biaya dan perkiraan tanggal sekaligus.

Ide pemakaian lain

• Payroll dan absensi: hitung hari kerja per bulan untuk gaji harian atau tunjangan transport.
• Penjadwalan notifikasi: tunda pengiriman email penagihan agar tidak jatuh di hari libur.
• Toko online: tampilkan banner "pengiriman libur" otomatis menjelang Idulfitri atau Natal.
• Bot internal: jawab pertanyaan "besok libur nggak?" di Slack atau WhatsApp kantor.

Pertanyaan yang sering diajukan

Apakah API hari libur ini gratis?

Ya. Keempat endpoint bisa dipakai dengan paket Free yang gratis selamanya, dengan kuota 500 request per hari dan rate limit 10 request per detik.

Apakah cuti bersama termasuk?

Termasuk, dan dibedakan lewat field jenis bernilai cuti_bersama. Endpoint hari kerja juga menghitung cuti bersama sebagai hari libur.

Apakah libur daerah ikut tercatat?

Data berfokus pada libur nasional dan cuti bersama yang berlaku secara nasional. Untuk libur khusus daerah atau kebijakan internal kantor, simpan daftar tambahan di aplikasi Anda dan gabungkan dengan hasil API.

Format tanggal apa yang diterima?

Selalu YYYY-MM-DD, misalnya 2026-12-25.

Bisakah dipakai dari asisten AI?

Bisa. Lewat server MCP APIPedia, Claude bisa langsung menjawab pertanyaan seperti "berapa hari kerja di bulan Desember?" memakai tool hitung_hari_kerja.

Mulai pakai API hari libur

Buat akun gratis di console.apipedia.id, ambil kunci di menu Token API, lalu coba perintah curl /libur/berikutnya di atas. Tenggat SLA, estimasi kirim, dan kalender kerja Anda tidak perlu lagi bergantung pada tabel yang harus diperbarui manual setiap tahun.