Indonesian National Holidays API: Check Holidays and Calculate Working Days

The national holiday API is an HTTP service that notifies whether a date is a holiday or collective leave in Indonesia, complete with the description. In APIPedia there are four endpoints for this: check a single date, list a year's holidays, nearby holidays, and count the number of working days between two dates.

This article discusses these four endpoints, their response forms, and examples of the most frequently required uses: calculating SLA deadlines, estimated delivery dates, and number of working days for payroll.

Why need a holiday API, not a manual table?

The list of red dates in Indonesia changes every year. Many holidays follow the Hijri, Chinese New Year or Saka calendar, so the Gregorian date shifts. The government also stipulates joint leave through the SKB of three ministers, and the schedule is sometimes revised.

Keeping one's own tables means one has to remember to update them every year. If you forget, the ticket system calculates the wrong deadline and the delivery estimate in the online shop is missed. With APIs, holiday data is managed in one place and applications can simply ask.

What are the holiday API endpoints in APIPedia?

All endpoints use method GET, base URL https://api.apipedia.id/v1, and header Authorization: Bearer apk_xxx. The date format is always YYYY-MM-DD.

Like other APIPedia endpoints, the response is wrapped in an envelope { is_success, message, data }. Check is_success first before reading data.

How do you check whether a date is a red date?

Dial /libur/cek/{tanggal}. This endpoint answers two questions at once: whether the date is a holiday, and whether it falls on a weekend.

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)"
  }
}

Since is_libur and is_akhir_pekan are separated, you can decide for yourself what the rules are. For example, customer service remains open on Saturdays, but is closed on national holidays.

How to take a list of national holidays and annual collective leave?

/libur/tahun/{tahun} returns jumlah and an array of libur. Each item contains tanggal, keterangan, jenis, and hari. For 2026, this endpoint returns 25 entries consisting of national holidays and collective leave.

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" }
  ]
}

This endpoint is best suited for calendars in HR applications, "operational schedule" pages, or promo campaign planning. Because the contents only change if the government revises the SKB, take it once and then save it in cache for a few hours or a day.

National holidays vs collective leave

Field jenis differentiates the two. National holidays apply to all, while collective leave in practice reduces employees' annual leave allowance and is not always followed by the private sector. If your company continues to operate on collective leave days, filter the entries with jenis === "cuti_bersama" before calculating.

How to display the countdown to the next holiday?

/libur/berikutnya returns the nearest holiday along with sisa_hari. No parameters, search starts from today. Fill in dari if you want to search from a certain date.

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
}

These results are perfect for a "60 days until Christmas" widget or an internal reminder for the team to prepare a picket schedule.

How to calculate the number of working days between two dates?

/libur/hari-kerja calculates how many weekdays there are between mulai and sampai, excluding weekends and holidays. Both dates are counted.

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
}

The details are transparent: 31 calendar days minus 8 Saturday-Sunday days and 2 holidays (collective leave 24 December and Christmas 25 December) results in 21 working days. Note that shared leave also counts as holiday, so adjust if your office policy is different.

Example: calculating SLA deadlines in working days

Typical case in ticket systems: "tickets must be answered within 3 business days". To do this, advance the dates one by one and skip days that are not working days. To save quota, take a list of holidays once a year, then do the calculations in your own code.

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"

In the example above, December 24 and 25 and weekends are skipped, so the deadline falls on December 30, 2026, not December 28. The same function can be used to estimate the package arrival date. Combine it with the shipping check API to display costs and estimated dates at once.

Other usage ideas

• Payroll and attendance: calculate working days per month for daily salary or transport allowance.
• Notification scheduling: delay sending billing emails so they don't fall on holidays.
• Online shop: display an automatic "holiday shipping" banner before Eid al-Fitr or Christmas.
• Internal bot: answer the question "Is there a holiday tomorrow?" in the office Slack or WhatsApp.

Frequently asked questions

Is this holiday API free?

Yes. The four endpoints can be used with the Free package which is free forever, with a quota of 500 requests per day and a rate limit of 10 requests per second.

Is shared leave included?

Included, and differentiated via field jenis with value cuti_bersama. The working day endpoint also counts shared leave as a holiday.

Are regional holidays included?

The data focuses on national holidays and collective leave that apply nationally. For regional-specific holidays or internal office policies, store additional lists in your application and combine them with API results.

What date formats are accepted?

Always YYYY-MM-DD, for example 2026-12-25.

Can it be used from an AI assistant?

Can. Via the MCP APIPedia server, Claude can immediately answer questions like "how many working days are there in December?" using tool hitung_hari_kerja.

Get started with the holiday API

Create a free account at console.apipedia.id, grab the key in the API Token menu, then try the curl /libur/berikutnya command above. Your SLA deadlines, shipping estimates, and work calendar no longer need to rely on tables that have to be updated manually every year.