api-ninjas-com Bank Holidays API

openapi: 3.2.0
info:
  title: Ninjas Bank 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: Bank Holidays
  description: 'The Bank Holidays API returns each country''s national banking calendar: the days banks are closed for business, in 240+ countries and territories, mostly from 1980 to 2050. It includes bank-only closures and leaves out public holidays on which banks open (for example, Federal Reserve Banks stay open on the Friday before a holiday that falls on a Saturday). Holidays that apply only in some states or regions list them in `regions`.'
paths:
  /v1/bankholidays:
    get:
      summary: Get bank holidays for a given country and year
      description: Returns bank holidays for a country and calendar year. Requires a `country`. To test a single date use /isbankholiday.
      operationId: getBankHolidays
      tags:
      - Bank 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. An unrecognized country, or one without bank holiday data, returns a 400 error.
        required: true
        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.
        required: false
        schema:
          type: integer
          minimum: 1980
          maximum: 2050
      responses:
        '200':
          description: A list of bank holiday entries for the specified country and year. Each entry contains the holiday name, date, country, year, and the regions it applies to.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankHoliday'
        '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 "IN" 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/isbankholiday:
    get:
      summary: Check if a specific date is a bank holiday for a given country
      description: Checks whether banks are closed nationwide on a given date in a country, or in one of its regions when `subdivision` is given. Requires `date` and `country`. For a whole year's calendar use /bankholidays.
      operationId: isBankHoliday
      tags:
      - Bank 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. An unrecognized country, or one without bank holiday data, returns a 400 error.
        required: true
        schema:
          type: string
      - name: subdivision
        in: query
        required: false
        schema:
          type: string
        description: ISO 3166-2 code of a state, province or region (e.g. `GB-SCT`, or just its suffix). Regional holidays count only when you pass the region they apply to. An unknown code returns a 400 error.
        example: GB-SCT
      responses:
        '200':
          description: An object indicating whether the given date is a bank holiday in the specified country.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IsBankHolidayResult'
        '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 "IN" 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:
    BankHoliday:
      type: object
      properties:
        name:
          type: string
          description: Name of the bank holiday.
        date:
          type: string
          format: date
          description: Date of the bank holiday in YYYY-MM-DD format.
        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`).
        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: GB.new_years_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
    IsBankHolidayResult:
      type: object
      properties:
        is_bank_holiday:
          type: boolean
          description: Whether the date is a bank holiday in the specified country.
        holiday_name:
          type: string
          description: Name of the bank 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. `GB` when you pass `UK`).
        subdivision:
          type: string
          description: The ISO 3166-2 code you passed, normalized.
          example: GB-SCT
    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