api-ninjas-com Public Holidays API

openapi: 3.2.0
info:
  title: Ninjas Public 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: Public Holidays
  description: The Public Holidays API provides the statutory days off for 240+ countries and territories, including regional holidays for states and provinces and the day a holiday is observed when it falls on a weekend. Most countries are covered from 1980 to 2050.
paths:
  /v1/publicholidays:
    get:
      summary: Get public holidays for a given country and year
      description: Returns public holidays for a country and calendar year. Requires a `country`. To test whether one date is a public holiday use /ispublicholiday.
      operationId: getPublicHolidays
      tags:
      - Public Holidays
      parameters:
      - name: country
        in: query
        required: true
        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. An unrecognized country, or one without public holiday data, returns a 400 error.
        schema:
          type: string
      - name: year
        in: query
        description: Calendar year between 1980 and 2050 (inclusive). Defaults to the current year. Free plans can omit it or pass the current year; other years are for premium subscribers only. Most countries cover 1980-2050; a year outside a country's range returns a 400 error listing the available years.
        schema:
          type: integer
          minimum: 1980
          maximum: 2050
      responses:
        '200':
          description: A list of public holidays
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicHoliday'
        '400':
          $ref: '#/components/responses/PublicHolidaysOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/PublicHolidaysOpenapi_Unauthorized'
        '500':
          $ref: '#/components/responses/PublicHolidaysOpenapi_InternalServerError'
      security:
      - ApiKeyAuth: []
  /v1/ispublicholiday:
    get:
      summary: Check if a given date is a public holiday for a given country
      description: Checks whether a given date is a nationwide public holiday in a country, or in one of its regions when `subdivision` is given. Requires `country` and `date`. For a whole year of public holidays use /publicholidays.
      operationId: isPublicHoliday
      tags:
      - Public Holidays
      parameters:
      - name: country
        in: query
        required: true
        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. An unrecognized country, or one without public holiday data, returns a 400 error.
        schema:
          type: string
      - name: date
        in: query
        required: true
        description: Date in YYYY-MM-DD format. Must be between 1980-01-01 and 2050-12-31 (inclusive). Dates in future calendar years are for premium subscribers only; Free plans can query past years and the current year.
        schema:
          type: string
          format: date
      - name: subdivision
        in: query
        required: false
        schema:
          type: string
        description: ISO 3166-2 code of a state, province or region (e.g. `DE-BY`, or just its suffix). Regional holidays count only when you pass the region they apply to. An unknown code returns a 400 error.
        example: DE-BY
      responses:
        '200':
          description: Public holiday information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IsPublicHoliday'
        '400':
          $ref: '#/components/responses/PublicHolidaysOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/PublicHolidaysOpenapi_Unauthorized'
        '500':
          $ref: '#/components/responses/PublicHolidaysOpenapi_InternalServerError'
      security:
      - ApiKeyAuth: []
components:
  responses:
    PublicHolidaysOpenapi_BadRequest:
      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 "IN" is not supported by this endpoint.
    PublicHolidaysOpenapi_InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    PublicHolidaysOpenapi_Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  schemas:
    PublicHoliday:
      type: object
      properties:
        name:
          type: string
          description: Holiday name. An observed or substitute day off is a separate row named e.g. "Independence Day (observed)".
        local_name:
          type: string
          description: Local holiday name.
        date:
          type: string
          format: date
          description: Date of the day off (YYYY-MM-DD).
        country:
          type: string
          description: 2-letter ISO 3166-1 alpha-2 country code.
        year:
          type: integer
          description: Calendar year of `date`.
        regions:
          type: array
          items:
            type: string
          description: ISO 3166-2 codes of the states, provinces or regions where the holiday applies (e.g. `GB-SCT`).
        federal:
          type: boolean
          description: '`true` when the holiday applies nationwide. When `false`, `regions` lists where it applies.'
        actual_date:
          type: string
          format: date
          description: Calendar date of the holiday itself. Differs from `date` only on observed days.
          example: '2026-07-04'
        observed:
          type: boolean
          description: True when `date` is an observed or substitute day off for a holiday that falls on another day.
          example: true
        holiday_id:
          type: string
          description: Stable identifier of the holiday, the same every year (e.g. `US.independence_day`). An observed day shares the id of its holiday.
          example: US.independence_day
        status:
          type: string
          enum:
          - confirmed
          - tentative
          description: '`tentative` for dates that depend on a lunar sighting or have not yet been officially announced; they may move by a day.'
          example: confirmed
    IsPublicHoliday:
      type: object
      properties:
        is_public_holiday:
          type: boolean
          description: Whether the date is a public holiday.
        public_holiday_name:
          type: string
          description: Name of the public holiday.
        date:
          type: string
          format: date
          description: The queried date in YYYY-MM-DD format.
        country:
          type: string
          description: The resolved 2-letter ISO 3166-1 alpha-2 country code (e.g. `DE` when you pass `Germany`).
        subdivision:
          type: string
          description: The ISO 3166-2 code you passed, normalized.
          example: DE-BY
    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