API Documentation & Endpoints — India Calendar API

API Overview

Welcome to the India Calendar API documentation. This open-source REST API serves official Indian government holidays (Central and State level) directly from structured datasets with zero keys and sub-50ms latency.

Zero Setup: The API is completely keyless, requires no registration or billing tokens, and serves data instantly.

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	Uppercase 2-letter state code or `central`. Defaults to central.

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	Uppercase 2-letter state code or `central`.

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	Uppercase 2-letter state code or `central`.

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	Uppercase 2-letter state code or `central`.

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	Uppercase 2-letter state code or `central`.

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.
meta: Contains payload metadata like apiVersion, totalResults and generation timestamp.

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 uppercase 2-letter code or 'central'	The state code was lowercase or did not match the 2-letter format.
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.
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.
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
}