api-ninjas-com Working Days API

openapi: 3.2.0
info:
  title: Ninjas Working Days 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: Working Days
  description: The Working Days API provides working and non-working days (weekends and public holidays) for 240+ countries and territories. It uses each country's own weekend, including regional weekend rules, counts official make-up working days as working days, and counts public holidays that apply nationwide, plus one region's holidays when `subdivision` is given. With `public_holidays=false`, weekend-only results are available for any country.
paths:
  /v1/workingdays:
    get:
      summary: Get working and non-working days
      description: Returns the working and non-working days for a country across a year or a single month, with configurable weekends. Requires `country`. For one date use /isworkingday.
      operationId: getWorkingDays
      parameters:
      - name: country
        in: query
        required: true
        schema:
          type: string
        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 returns a 400 error, as does a country without public holiday data unless `public_holidays` is `false`.
      - name: year
        in: query
        schema:
          type: integer
          minimum: 1980
          maximum: 2050
        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.
      - name: month
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 12
        description: Month number from 1 to 12. If provided, returns data for just that month.
      - name: weekend
        in: query
        schema:
          type: string
        description: 'Comma-separated weekend day codes from mon, tue, wed, thu, fri, sat and sun (e.g. `fri,sat`). Overrides the country''s default weekend. If omitted or empty, the country''s default weekend is used: Saturday and Sunday in most countries, Friday and Saturday in countries such as Saudi Arabia, Egypt and Israel. An unrecognized day code returns a 400 error.'
      - name: public_holidays
        in: query
        schema:
          type: boolean
        description: Whether to count public holidays as non-working days (true/false). Defaults to true. With false, only weekends are non-working days, and any valid country can be used, including countries without public holiday data.
      - name: subdivision
        in: query
        required: false
        schema:
          type: string
        description: ISO 3166-2 code of a state, province or region (e.g. `US-CA`, or just its suffix). Regional holidays count only when you pass the region they apply to. An unknown code returns a 400 error.
        example: US-CA
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkingDaysResponse'
        '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: []
      tags:
      - Working Days
  /v1/isworkingday:
    get:
      summary: Check if a specific date is a working day
      description: Reports whether one specific date is a working day in a given country. Requires `country` and `date`. For a whole month or year use /workingdays.
      operationId: isWorkingDay
      parameters:
      - name: country
        in: query
        required: true
        schema:
          type: string
        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 returns a 400 error, as does a country without public holiday data unless `public_holidays` is `false`.
      - name: date
        in: query
        required: true
        schema:
          type: string
          format: date
        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.
      - name: weekend
        in: query
        schema:
          type: string
        description: 'Comma-separated weekend day codes from mon, tue, wed, thu, fri, sat and sun (e.g. `fri,sat`). Overrides the country''s default weekend. If omitted or empty, the country''s default weekend is used: Saturday and Sunday in most countries, Friday and Saturday in countries such as Saudi Arabia, Egypt and Israel. An unrecognized day code returns a 400 error.'
      - name: public_holidays
        in: query
        schema:
          type: boolean
        description: Whether to count public holidays as non-working days (true/false). Defaults to true. With false, only weekends are non-working days, and any valid country can be used, including countries without public holiday data.
      - name: subdivision
        in: query
        required: false
        schema:
          type: string
        description: ISO 3166-2 code of a state, province or region (e.g. `US-CA`, or just its suffix). Regional holidays count only when you pass the region they apply to. An unknown code returns a 400 error.
        example: US-CA
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IsWorkingDayResponse'
        '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: []
      tags:
      - Working Days
components:
  schemas:
    IsWorkingDayResponse:
      type: object
      properties:
        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).
        day_of_week:
          type: string
          description: Day of the week (Monday through Sunday).
        is_workday:
          type: boolean
          description: Whether the date is a working day.
        non_working_reason:
          type: array
          items:
            type: string
          description: List of reasons why the date is not a working day (if applicable).
        public_holiday_name:
          type: string
          description: Name of the public holiday (if applicable).
        subdivision:
          type: string
          description: The ISO 3166-2 code you passed, normalized.
          example: DE-BY
    WorkingDaysResponse:
      type: object
      properties:
        num_working_days:
          type: integer
          description: Total number of working days in the period.
        num_non_working_days:
          type: integer
          description: Total number of non-working days in the period.
        working_days:
          type: array
          items:
            type: string
            format: date
            description: List of dates that are working days.
        non_working_days:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                description: Date of the non-working day.
              reasons:
                type: array
                items:
                  type: string
                description: Reasons why the day is non-working.
              holiday_name:
                type: string
                description: Name of the public holiday, if applicable.
          description: List of dates that are non-working days, with reasons and holiday names if applicable.
        year:
          type: integer
          description: The calendar year the results cover.
    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