Developer API

Calendars & holidays, as a JSON endpoint.

Free & open for fair use — no API key required. Public holidays, long-weekend planning and a live world clock for 206 countries. CORS-open, CDN-cached, CC BY 4.0.

Holidays

Public holidays per country.

GET /api/holidays lists every country; add a 2-letter code for that country’s 2026 public holidays. CORS-open, no key required.

GET https://caldays.com/api/holidays/us
{
  "code": "us", "country": "United States",
  "year": 2026, "license": "CC BY 4.0", "count": 11,
  "holidays": [
    { "date": "2026-01-01", "name": "New Year's Day" },
    { "date": "2026-07-04", "name": "Independence Day" }
  ]
}

Long weekends

Automatic bridge-day planner.

GET /api/long-weekends/{cc} — every 3+ day break in 2026 (weekends + public holidays), with the bridge days worth booking off.

GET https://caldays.com/api/long-weekends/us
{ "code": "us", "year": 2026, "count": 16,
  "longWeekends": [
    { "start": "2026-01-01", "end": "2026-01-04",
      "days": 4, "bridgeDays": 1,
      "holidays": [ { "date": "2026-01-01",
                     "name": "New Year's Day" } ] }
  ] }

World clock

Live local time, DST-correct.

GET /api/clock — current time for caldays city codes (?cities=) and/or any IANA zone (?tz=), computed from the IANA tz database.

GET https://caldays.com/api/clock?cities=jkt,lon,nyc&tz=Asia/Tokyo
{ "utc": "2026-07-19T00:23:47Z", "count": 4,
  "results": [
    { "id": "jkt", "city": "Jakarta",
      "iana": "Asia/Jakarta", "date": "2026-07-19",
      "time": "07:23:47", "weekday": "Sunday",
      "utcOffset": "UTC+7" }
  ] }

Limits & keys

Open now, metered when you scale.

Anonymous access is open for fair use — no key needed. For guaranteed volume, a metered API key raises the daily cap (see Pricing). Over-limit requests return HTTP 429.

Attribution

Free, in exchange for a credit.

The caldays holiday dataset is released under Creative Commons Attribution 4.0. You can use it commercially, redistribute it, or build paid products on top of it — we only ask that you credit caldays with a visible link, e.g. "Holiday data: caldays.com" in your footer, about page, or API response.

<!-- Suggested attribution snippet -->
<p>Public holiday data powered by 
  <a href="https://caldays.com" target="_blank" rel="noopener">caldays</a>
  (<a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>).
</p>

Developer

Get an API key