API Documentation & Endpoints — India Calendar API

API Overview

This open-source REST API serves official Indian government holidays for the Central Government and all 36 States and Union Territories. No API key or sign-up is needed.

Cold starts: The API runs on a free server that sleeps after 15 minutes without traffic. The first request after that can take about a minute; requests after it are fast.

Base URL

All requests are issued to the production deployment URL below. Always use HTTPS.

https://calendar-api-d7a8.onrender.com

API Endpoints

The API provides five lightweight, database-free routes to query holiday data. Review details and parameter schemas below.

GET

/v1/holidays

Returns sorted chronological lists of holidays. If a 2-letter region code is passed, state-specific holidays are dynamically combined with central holidays, and matching duplicates are automatically filtered out.

Query Parameters

Parameter	Required	Type	Description
country	Yes	string	Must be `IN`.
year	Yes	number	4-digit year, e.g. `2026`.
region	No	string	2-letter state code (any case) or `central`. Defaults to central.
scope	No	string	`all` (default) adds the Central list to a state's holidays. `state` returns only the state's own list, with no Central entries and no cross-list duplicates.

Example Response

{
  "country": "IN",
  "year": 2026,
  "region": "KA",
  "data": [
    {
      "name": "New Year's Day",
      "date": "2026-01-01",
      "type": "restricted_holiday"
    },
    {
      "name": "Makar Sankranti",
      "date": "2026-01-14",
      "type": "restricted_holiday"
    },
    {
      "name": "Republic Day",
      "date": "2026-01-26",
      "type": "gazetted_holiday"
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "totalResults": 3,
    "generatedAt": "2026-05-28T07:00:00Z"
  }
}

GET

/v1/date/is-holiday

Quickly verifies if a specific calendar date is a public holiday.

Query Parameters

Parameter	Required	Type	Description
country	Yes	string	Must be `IN`.
date	Yes	string	Format `YYYY-MM-DD`.
region	No	string	2-letter state code (any case) or `central`.
scope	No	string	`all` (default) adds the Central list to a state's holidays. `state` returns only the state's own list, with no Central entries and no cross-list duplicates.

Example Response

{
  "country": "IN",
  "year": 2026,
  "region": "central",
  "data": [
    {
      "date": "2026-01-26",
      "is_holiday": true,
      "holidays": [
        {
          "name": "Republic Day",
          "date": "2026-01-26",
          "type": "gazetted_holiday",
          "region": [
            "IN"
          ],
          "description": "Gazetted Holiday",
          "source": "https://www.india.gov.in/calendar"
        }
      ]
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "totalResults": 1,
    "generatedAt": "2026-05-28T07:00:00Z"
  }
}

GET

/v1/date/next-holiday

Finds the next upcoming holiday(s) chronologically after a given date. Automatically wraps around to check the first holiday of the following year.

Query Parameters

Parameter	Required	Type	Description
country	Yes	string	Must be `IN`.
date	Yes	string	Base date in format `YYYY-MM-DD`.
region	No	string	2-letter state code (any case) or `central`.
scope	No	string	`all` (default) adds the Central list to a state's holidays. `state` returns only the state's own list, with no Central entries and no cross-list duplicates.

Example Response

{
  "country": "IN",
  "year": 2026,
  "region": "central",
  "data": [
    {
      "name": "Hazarat Ali's Birthday",
      "date": "2026-01-03",
      "type": "restricted_holiday",
      "region": [
        "IN"
      ],
      "description": "Restricted Holiday",
      "source": "https://www.india.gov.in/calendar"
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "totalResults": 1,
    "generatedAt": "2026-05-28T07:00:00Z"
  }
}

GET

/v1/holidays/range

Filters holidays within a custom range, supporting boundary traversals.

Query Parameters

Parameter	Required	Type	Description
country	Yes	string	Must be `IN`.
start	Yes	string	Start date boundary `YYYY-MM-DD`.
end	Yes	string	End date boundary `YYYY-MM-DD`.
region	No	string	2-letter state code (any case) or `central`.
scope	No	string	`all` (default) adds the Central list to a state's holidays. `state` returns only the state's own list, with no Central entries and no cross-list duplicates.

Example Response

{
  "country": "IN",
  "year": 2026,
  "region": "KA",
  "data": [
    {
      "name": "New Year's Day",
      "date": "2026-01-01",
      "type": "restricted_holiday",
      "region": [
        "IN"
      ],
      "description": "Restricted Holiday",
      "source": "https://www.india.gov.in/calendar"
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "totalResults": 1,
    "generatedAt": "2026-05-28T07:00:00Z"
  }
}

GET

/v1/calendar

Constructs a full 365 or 366 day dataset tagged with weekends, holidays, names, classifications and business day evaluations.

Query Parameters

Parameter	Required	Type	Description
country	Yes	string	Must be `IN`.
year	Yes	number	4-digit year, e.g. `2026`.
region	No	string	2-letter state code (any case) or `central`.
scope	No	string	`all` (default) adds the Central list to a state's holidays. `state` returns only the state's own list, with no Central entries and no cross-list duplicates.
restricted	No	string	`holiday` (default) counts restricted (optional) holidays as days off. `working` keeps days that only have restricted holidays as working days.

Example Response

{
  "country": "IN",
  "year": 2026,
  "region": "KA",
  "data": [
    {
      "date": "2026-01-25",
      "day": "Sunday",
      "is_weekend": true,
      "is_holiday": false,
      "holiday_name": null,
      "holiday_type": null,
      "is_working_day": false
    },
    {
      "date": "2026-01-26",
      "day": "Monday",
      "is_weekend": false,
      "is_holiday": true,
      "holiday_name": "Republic Day",
      "holiday_type": "gazetted_holiday",
      "is_working_day": false
    },
    {
      "date": "2026-01-27",
      "day": "Tuesday",
      "is_weekend": false,
      "is_holiday": false,
      "holiday_name": null,
      "holiday_type": null,
      "is_working_day": true
    }
  ],
  "meta": {
    "apiVersion": "v1",
    "totalResults": 3,
    "generatedAt": "2026-05-28T07:00:00Z"
  }
}

Response Schema

All success requests return JSON matching the standard schema format:

country: ISO alpha 2 country code (IN).
year: The calendar year requested.
region: The state code requested, or central.
data: Array containing corresponding holiday records. Each holiday carries level: state when it is on the requested state's own list, otherwise central. Filter on level to get one state's list only.
meta: Contains payload metadata like apiVersion, totalResults and generation timestamp. When part of a request falls in a year with no published data yet, yearsWithoutData lists those years (for example a next-holiday lookup on 31 December).

Successful responses are cacheable for one hour (Cache-Control: public, max-age=3600).

Errors & Rate Limits

When queries fail, validation checks fail, or limits are exceeded, the API returns a standardized JSON structure with the corresponding HTTP status code.

Error Response Format

All error responses include the following three parameters:

error: Always set to true.
message: Human-readable explanation of why the query failed.
status: The HTTP status code corresponding to the response header.

Validation Check Catalog

Status	API Error Message (`message`)	Trigger Condition
400 Bad Request	Missing required parameter: country	The `country` query parameter was not provided.
400 Bad Request	Missing required parameter: year	The `year` parameter is required for lists and calendar endpoints.
400 Bad Request	Invalid year format. Use a 4-digit number	The `year` value is not formatted as YYYY (e.g. `26` or `20265`).
400 Bad Request	Region parameter must be a 2-letter state/UT code or 'central'	The state code did not match the 2-letter format. Any case is accepted (`ka` works like `KA`).
400 Bad Request	Missing required parameter: date	Required parameter `date` is missing for checkers or next-holiday queries.
400 Bad Request	Invalid date format. Use YYYY-MM-DD	The `date`, `start`, or `end` values are not matching standard ISO formats.
400 Bad Request	Missing required parameters: start and end	The `/holidays/range` endpoint requires both query bounds.
400 Bad Request	Start date cannot be after end date	The start range parameter occurs chronologically after the end parameter.
400 Bad Request	Parameter 'scope' must be one of: all, state	`scope` or `restricted` has a value outside the listed options.
400 Bad Request	Parameter '<name>' must be given once as plain text	A query parameter was repeated (e.g. `country=IN&country=IN`) or sent as a nested value.
400 Bad Request	Range cannot span more than 5 calendar years	The `/holidays/range` start and end fall in more than five calendar years.
404 Not Found	Only IN is supported in v1	The `country` query parameter is not `IN`.
404 Not Found	Data not available for this year	Data has not been scraped or generated for the requested year folder.
404 Not Found	Region not found	The state/UT code provided does not exist in our system database.
404 Not Found	Data not available for the requested year range	The range query dates do not match any year directories on the server.
404 Not Found	Endpoint not found	The requested API route path or method is invalid.
503 Service Unavailable	Holiday data unavailable for this region	The data file for that year and region is missing or unreadable on the server. Retry later.
500 Internal Server Error	Internal Server Error	An unexpected server error. No internal details are returned.
429 Rate Limited	Too many requests, please try again later	Your IP exceeded 100 queries within a 15-minute window.

Example Validation Error Response (400)

Errors always return in the standard format below, making handling consistent across environments.

{
  "error": true,
  "message": "Missing required parameter: country",
  "status": 400
}