Calendarific API

72 B

Metadata Score Metadata estimate · not endpoint-tested

Visit Official Site Compare Alternatives

Overview

Calendarific is a REST API that returns public holidays for over 230 countries and territories, supporting both Gregorian and non-Gregorian calendars. It accepts a country code, year, and optional month parameter to return structured holiday data including holiday type (national, local, religious). An API key is required and obtained by signing up on their website.

Beginner Tip

Start with the free tier, which provides 1,000 requests/month. Pass your API key as a query parameter: ?api_key=YOUR_KEY&country=US&year=2024.

Available Data

The kind of data this API exposes, based on its documentation. We could not call the endpoint to confirm the exact field names.

event dates and names

holiday lists by country

date metadata

Use case: Integrate worldwide holidays data into web and mobile applications

Example Response

Illustrative shape only — we were not able to call this endpoint (it requires credentials or exposes no public sample URL), so the fields below show the kind of data this API returns rather than a recorded response.

JSON Response · Illustrative

{
  "status": "success",
  "data": {
    "result": "Data from Calendarific",
    "description": "Worldwide Holidays",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

Field Reference

response.holidays[].name Official name of the holiday, e.g., "Christmas Day".

response.holidays[].description Short description of the holiday's origin or significance.

response.holidays[].date.iso ISO 8601 date string of the holiday, e.g., "2024-12-25".

response.holidays[].type List of holiday types such as "National holiday", "Local holiday", or "Religious holiday".

response.holidays[].locations Applicable locations within the country; "All" means the holiday is nationwide.

Implementation Example

Calls a real endpoint of this API. Replace any placeholder credentials with your own key.

Request

const url = "https://calendarific.com/api/v2/holidays?api_key=YOUR_KEY&country=US&year=2024";
// Replace headers or query params with the values required by this API.
const response = await fetch(url, {
  headers: {
  "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();
console.log(data);

What Can You Build?

Note: These code examples are AI-generated and unverified. Always refer to the official API documentation for accurate usage.

Common Errors & Troubleshooting

Generated guidance based on this API's documentation, not observed by us. Treat it as a starting point and check against the provider's own error reference.

401 Unauthorized Missing or invalid api_key query parameter

✓ Ensure you append ?api_key=YOUR_KEY to every request; do not put it in the request body.

Empty response / no holidays returned Invalid country code or unsupported year range

✓ Use ISO 3166-1 alpha-2 country codes (e.g., US, GB, JP) and years between 2010 and 2049.

429 Too Many Requests Exceeded the monthly request quota for your plan

✓ Cache responses locally; one call per country/year combination is sufficient for a whole year of data.

Metadata Score Breakdown

Estimated from metadata — endpoint not independently tested

This score is estimated from observable metadata — HTTPS support, authentication model, declared CORS, and documentation reachability — because the API requires authentication or exposes no publicly testable endpoint. The five-signal breakdown is only shown for live-tested APIs.

Metadata estimate · endpoint not independently tested

How is this scored? →