api-ninjas-com Holidays API

openapi: 3.2.0
info:
  title: Ninjas Holidays API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Holidays
  description: The Holidays API provides holiday information for over 230 countries and territories around the world, from 2005 to 2039. The data includes public holidays, religious dates, bank holidays, and many other categories.
paths:
  /v2/holidays:
    get:
      summary: Get holidays for a given country and year
      description: Returns holidays for a country and calendar year, optionally filtered by holiday type. Requires a `country`. For holidays falling on one date use /v1/isholiday.
      operationId: getHolidays
      tags:
      - Holidays
      parameters:
      - name: country
        in: query
        description: 'Country as a 2-letter ISO 3166-1 alpha-2 code (preferred, e.g. `US`), a 3-letter alpha-3 code (e.g. `USA`) or an English country name (e.g. `United States`). Not case-sensitive. Names must match exactly; common short names such as `UK`, `USA`, `UAE` and `South Korea` also work. Territories have their own codes: for example, Curaçao is `CW` and Sint Maarten is `SX`, not `NL`. An unrecognized country, or one without data, returns a 400 error.'
        required: true
        schema:
          type: string
      - name: year
        in: query
        description: Calendar year between 2005 and 2039 (inclusive). Defaults to the current year. Free plans can omit it or pass the current year; other years are for premium subscribers only.
        required: false
        schema:
          type: integer
          minimum: 2005
          maximum: 2039
      - name: type
        in: query
        description: 'Return only one type of holiday. Not case-sensitive: `PUBLIC_HOLIDAY` and `public_holiday` are equivalent, and `major_holiday` is accepted as an alias of `public_holiday`. An unknown value returns a 400 error. Omit to return every type.'
        required: false
        schema:
          type: string
          enum:
          - PUBLIC_HOLIDAY
          - STATE_HOLIDAY
          - LOCAL_HOLIDAY
          - PROVINCE_TERRITORY_HOLIDAY
          - DE_FACTO_HOLIDAY
          - SUBSTITUTE_HOLIDAY
          - BANK_HOLIDAY
          - GOVERNMENT_HOLIDAY
          - PRIVATE_SECTOR_HOLIDAY
          - OPTIONAL_HOLIDAY
          - RESTRICTED_TRADING_DAY
          - CHRISTIAN_HOLIDAY
          - ORTHODOX_HOLIDAY
          - MUSLIM_HOLIDAY
          - JEWISH_HOLIDAY
          - HINDU_HOLIDAY
          - OBSERVANCE
          - UNITED_NATIONS_OBSERVANCE
          - FLAG_DAY
          - SILENT_DAY
          - HALF_DAY
          - WORKING_DAY
          - SEASON
          - CLOCK_CHANGE
          - COVID_19_MEASURE
          - SPORTING_EVENT
      responses:
        '200':
          description: A list of holiday entries for the specified country and year.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Holiday'
        '400':
          description: Bad Request - a parameter is missing or invalid, the country is not recognized, or this endpoint has no data for the country. The `error` message explains the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_country:
                  summary: Unrecognized country
                  value:
                    error: Invalid country "Atlantis". Use a 2-letter ISO 3166-1 code (e.g. US) or an English country name.
                unsupported_country:
                  summary: Country without data
                  value:
                    error: Country "AQ" is not supported by this endpoint.
        '401':
          description: Unauthorized - API key is missing or invalid.
        '500':
          description: Internal Server Error - We had a problem with our server. Try again later.
      security:
      - ApiKeyAuth: []
  /v1/isholiday:
    get:
      summary: Get all holidays that fall on a given date
      description: Returns all holidays that fall on a given date, optionally restricted to one country. Requires a `date`. For a full year's calendar use /v2/holidays.
      operationId: isHoliday
      tags:
      - Holidays
      parameters:
      - name: date
        in: query
        description: Date in YYYY-MM-DD format (e.g. 2025-12-25). Dates in future calendar years are for premium subscribers only; Free plans can query past years and the current year.
        required: true
        schema:
          type: string
          format: date
      - name: country
        in: query
        description: Country as a 2-letter ISO 3166-1 alpha-2 code (preferred, e.g. `US`), a 3-letter alpha-3 code (e.g. `USA`) or an English country name (e.g. `United States`). Not case-sensitive. Names must match exactly; common short names such as `UK`, `USA`, `UAE` and `South Korea` also work. If not specified, holidays from all countries are returned. An unrecognized country, or one without data, returns a 400 error.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A list of holiday entries matching the specified date.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Holiday'
        '400':
          description: Bad Request - a parameter is missing or invalid, the country is not recognized, or this endpoint has no data for the country. The `error` message explains the problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_country:
                  summary: Unrecognized country
                  value:
                    error: Invalid country "Atlantis". Use a 2-letter ISO 3166-1 code (e.g. US) or an English country name.
                unsupported_country:
                  summary: Country without data
                  value:
                    error: Country "AQ" is not supported by this endpoint.
        '401':
          description: Unauthorized - API key is missing or invalid.
        '500':
          description: Internal Server Error - We had a problem with our server. Try again later.
      security:
      - ApiKeyAuth: []
components:
  schemas:
    Holiday:
      type: object
      properties:
        country:
          type: string
          description: The name of the country or territory.
        iso:
          type: string
          description: 2-letter ISO 3166-1 alpha-2 code of the country or territory, in upper case.
        year:
          type: integer
          description: The calendar year of the holiday.
        date:
          type: string
          format: date
          description: The date of the holiday in YYYY-MM-DD format.
        day:
          type: string
          description: The day of the week on which the holiday falls.
        name:
          type: string
          description: The name of the holiday.
        type:
          type: string
          description: 'The type of holiday, in upper case. Possible values:

            - `PUBLIC_HOLIDAY`: A national day off for the general population. Includes national holidays with a religious origin, such as Good Friday and Christmas Day in Germany.

            - `STATE_HOLIDAY`: A holiday observed at the state or regional level within a country, applicable to residents of that state but not necessarily the nation as a whole.

            - `LOCAL_HOLIDAY`: A holiday observed only within a specific city, district, or municipality, with no broader regional or national application.

            - `PROVINCE_TERRITORY_HOLIDAY`: A holiday specific to a province or territory within a federal state, such as those observed in Canadian provinces or Australian territories.

            - `DE_FACTO_HOLIDAY`: A day that is widely treated as a holiday in practice (through informal tradition, employer convention, or cultural norm) without a formal legal mandate.

            - `SUBSTITUTE_HOLIDAY`: A replacement day off granted when an official holiday falls on a weekend or non-working day, or when a holiday is moved to another date.

            - `BANK_HOLIDAY`: A day on which banks and financial institutions are officially closed. May or may not align with a general public holiday.

            - `GOVERNMENT_HOLIDAY`: A day off that applies specifically to government employees and public sector workers, which may not extend to the private sector or general population.

            - `PRIVATE_SECTOR_HOLIDAY`: A day off that applies specifically to private sector employees, which may differ from public sector or general population holidays.

            - `OPTIONAL_HOLIDAY`: A holiday that individuals or employers may choose to observe, but which carries no universal legal obligation.

            - `RESTRICTED_TRADING_DAY`: A day on which commercial or retail activity is permitted but subject to legal restrictions, such as limited trading hours. Not a full day off.

            - `CHRISTIAN_HOLIDAY`: A Western Christian (Catholic or Protestant) religious observance that is not a national day off.

            - `ORTHODOX_HOLIDAY`: An Eastern Orthodox Christian religious observance that is not a national day off.

            - `MUSLIM_HOLIDAY`: An Islamic religious observance that is not a national day off.

            - `JEWISH_HOLIDAY`: A Jewish religious observance that is not a national day off.

            - `HINDU_HOLIDAY`: A Hindu religious observance that is not a national day off.

            - `OBSERVANCE`: A recognized day of cultural, civic, or commemorative significance that is not an official day off. A holiday that is suspended or cancelled in a given year is also typed `OBSERVANCE` for that year.

            - `UNITED_NATIONS_OBSERVANCE`: An observance designated by the United Nations or another international body, recognised globally rather than within a single country or region.

            - `FLAG_DAY`: A day designated to honour a nation''s flag, often marked by ceremonies or displays.

            - `SILENT_DAY`: A day on which noise, public gatherings, or commercial activity is restricted by law or strong cultural convention, typically for remembrance or mourning.

            - `HALF_DAY`: A partial holiday on which businesses or institutions close for only part of the day, typically the afternoon.

            - `WORKING_DAY`: A regular working day that may coincide with a notable calendar event but is not a day off.

            - `SEASON`: An astronomical event marking the start of a new season: an equinox or solstice.

            - `CLOCK_CHANGE`: A day on which clocks are adjusted for daylight saving time. Not a day off, but a notable calendar event affecting daily schedules.

            - `COVID_19_MEASURE`: A non-working day or closure introduced in response to the COVID-19 pandemic, such as a lockdown, work suspension, or emergency public holiday.

            - `SPORTING_EVENT`: A day designated around a major sporting event, which may result in altered working hours, public gatherings, or unofficial closures.'
          enum:
          - PUBLIC_HOLIDAY
          - STATE_HOLIDAY
          - LOCAL_HOLIDAY
          - PROVINCE_TERRITORY_HOLIDAY
          - DE_FACTO_HOLIDAY
          - SUBSTITUTE_HOLIDAY
          - BANK_HOLIDAY
          - GOVERNMENT_HOLIDAY
          - PRIVATE_SECTOR_HOLIDAY
          - OPTIONAL_HOLIDAY
          - RESTRICTED_TRADING_DAY
          - CHRISTIAN_HOLIDAY
          - ORTHODOX_HOLIDAY
          - MUSLIM_HOLIDAY
          - JEWISH_HOLIDAY
          - HINDU_HOLIDAY
          - OBSERVANCE
          - UNITED_NATIONS_OBSERVANCE
          - FLAG_DAY
          - SILENT_DAY
          - HALF_DAY
          - WORKING_DAY
          - SEASON
          - CLOCK_CHANGE
          - COVID_19_MEASURE
          - SPORTING_EVENT
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: What was wrong with the request.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api