NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Public Holidays API

The Public Holidays API provides public holiday information for countries around the world. Get holiday data from 1980 to 2050 for over 100 countries.

For non-public holidays, religious holidays, and other special events, please use the Holidays API instead.

(4.7)

From 5,929 users

2,400+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average
P50
P75
P90
P95
308ms330ms359ms615ms1103ms

Didn't find what you were looking for? Suggest an improvement

/v1/publicholidays GET

https://api.api-ninjas.com/v1/publicholidays

Returns a list of public holidays for a given country and year.

To look up whether a given date is a public holiday, use the /v1/ispublicholiday endpoint instead.

Parameters

  • country  required

    2-letter ISO country code or full country name.

  • year  optional premium only

    Calendar year between 1980 and 2050 (inclusive). Defaults to current year.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON array of objects, each containing the following fields, or an error if the request is unsuccessful.

  • name

    Holiday name.

  • local_name

    Local holiday name. This is often (but not always) the same as the name.

  • date

    Holiday date.

  • country

    2-letter ISO country code.

  • year

    Calendar year.

  • regions

    List of regions where the holiday is observed.

  • federal

    Whether the holiday is a federal holiday.

Sample Request Live Demo!

country
year premium

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/publicholidays?country=US

Headers

X-Api-KeyLog in or sign up to get your API Key

Sample Response

JSON
[
    {
      name:"New Year's Day",
      local_name:"New Year's Day",
      date:"2025-01-01",
      country:"US",
      year:2025,
      regions:[],
      federal:true
    },
    {
      name:"Martin Luther King, Jr. Day",
      local_name:"Martin Luther King, Jr. Day",
      date:"2025-01-20",
      country:"US",
      year:2025,
      regions:[],
      federal:true
    },
    {
      name:"Presidents Day",
      local_name:"Washington's Birthday",
      date:"2025-02-17",
      country:"US",
      year:2025,
      regions:[],
      federal:true
    },
    "..."
]

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/publicholidays?country=US&year=2024" \ -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.

/v1/ispublicholiday GET

https://api.api-ninjas.com/v1/ispublicholiday

Returns whether a given date is a public holiday for a given country.

Parameters

  • country  required

    2-letter ISO country code.

  • date  required

    Date in YYYY-MM-DD format. Must be between 1980-01-01 and 2050-12-31 (inclusive).

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON object with the following fields or an error if the request is unsuccessful.

  • is_public_holiday

    Whether the date is a public holiday.

  • public_holiday_name

    Name of the public holiday.

  • date

    Holiday date in YYYY-MM-DD format.

  • country

    2-letter ISO country code.

Sample Request Live Demo!

country
date

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/ispublicholiday?country=US&date=2025-01-01

Headers

X-Api-KeyLog in or sign up to get your API Key

Sample Response

JSON
{
    date:"2025-01-01",
    country:"US",
    is_public_holiday:true,
    public_holiday_name:"New Year's Day"
}

Frequently Asked Questions

  • Yes, but you must have a premium subscription. Commercial use of the Public Holidays API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.
  • Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.
  • Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.
  • The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.
  • The /v1/publicholidays endpoint returns public holiday data from 1980 to 2050 for over 100 countries, accepting either a 2-letter ISO country code or a full country name in the country parameter. For non-public, religious, or other special events, use the Holidays API instead.
  • The /v1/publicholidays endpoint returns a full list of public holidays for a given country and year, while /v1/ispublicholiday checks whether a single date (in YYYY-MM-DD format) is a public holiday and returns an is_public_holiday boolean plus the public_holiday_name. To count business days that exclude these holidays, see the Working Days API.
  • Each object in the JSON array includes name, local_name, date, country, year, a regions list of where the holiday is observed, and a federal flag indicating whether it is a federal holiday. If a request is unsuccessful you will instead receive an error described in the error codes reference.
  • Pass the optional year parameter (any calendar year between 1980 and 2050 inclusive) to the /v1/publicholidays endpoint; it defaults to the current year and is a premium-only feature, so see pricing for access. For looking up country codes and names, the Country API can help.