openapi: 3.0.3
info:
  title: Holiday Countries Workdays API
  description: Holidays are hard. We make them easy.
  termsOfService: https://holidayapi.com/terms
  contact:
    name: Holiday API
    email: hello@holidayapi.com
  version: '1.0'
servers:
- url: https://holidayapi.com
  description: Holiday API v1
tags:
- name: Workdays
  description: Working / business day calculations honoring country workweeks and holidays.
paths:
  /v1/workday:
    get:
      operationId: getWorkday
      tags:
      - Workdays
      summary: Get Workday
      description: Calculates the workday (based on a country's workweek) that occurs a given number of days after a date.
      externalDocs:
        description: Developer Documentation
        url: https://holidayapi.com/docs
      parameters:
      - name: key
        description: Your API key.
        required: true
        in: query
        schema:
          type: string
          format: uuid
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      - name: country
        description: For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For subdivisions, ISO 3166-2 format. Accepts up to 10 comma separated values.
        required: true
        in: query
        schema:
          type: string
        example: US
      - name: start
        description: The date (in YYYY-MM-DD format) from which to begin counting.
        required: true
        in: query
        schema:
          type: string
          format: date
        example: '2015-07-01'
      - name: days
        description: Number of working / business days to advance (positive integer) or retrogress (negative integer) from start.
        required: true
        in: query
        schema:
          type: integer
          format: int32
        example: 7
      - name: format
        description: Response format.
        required: false
        in: query
        schema:
          type: string
          default: json
          enum:
          - csv
          - json
          - php
          - tsv
          - yaml
          - xml
        example: json
      - name: pretty
        description: Prettifies results to be more human-readable.
        required: false
        in: query
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '200':
          description: Success! Everything is A-OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workday'
  /v1/workdays:
    get:
      operationId: getWorkdays
      tags:
      - Workdays
      summary: Get Workdays
      description: Calculates the number of workdays (based on a country's workweek) that occur between a given date range.
      externalDocs:
        description: Developer Documentation
        url: https://holidayapi.com/docs
      parameters:
      - name: key
        description: Your API key.
        required: true
        in: query
        schema:
          type: string
          format: uuid
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      - name: country
        description: For countries, ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. For subdivisions, ISO 3166-2 format. Accepts up to 10 comma separated values.
        required: true
        in: query
        schema:
          type: string
        example: US
      - name: start
        description: The date (in YYYY-MM-DD format) from which to begin counting.
        required: true
        in: query
        schema:
          type: string
          format: date
        example: '2015-07-01'
      - name: end
        description: The date (in YYYY-MM-DD format) to count until.
        required: true
        in: query
        schema:
          type: string
          format: date
        example: '2015-07-10'
      - name: format
        description: Response format.
        required: false
        in: query
        schema:
          type: string
          default: json
          enum:
          - csv
          - json
          - php
          - tsv
          - yaml
          - xml
        example: json
      - name: pretty
        description: Prettifies results to be more human-readable.
        required: false
        in: query
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '200':
          description: Success! Everything is A-OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workdays'
components:
  schemas:
    workdays:
      allOf:
      - $ref: '#/components/schemas/response'
      - type: object
        required:
        - workdays
        properties:
          date:
            type: integer
            format: int32
            example: 10
    workday:
      allOf:
      - $ref: '#/components/schemas/response'
      - type: object
        required:
        - date
        - weekday
        properties:
          date:
            type: string
            format: date
            example: '2015-07-13'
          weekday:
            $ref: '#/components/schemas/weekday'
    response:
      type: object
      required:
      - status
      - requests
      properties:
        status:
          type: integer
          format: int32
          example: 200
        requests:
          type: object
          required:
          - used
          - available
          - resets
          properties:
            used:
              type: integer
              format: int32
              example: 136
            available:
              type: integer
              format: int32
              example: 864
            resets:
              type: string
              example: '2019-09-01 00:00:00'
        error:
          type: string
          example: An error has occurred.
        warning:
          type: string
          example: An warning has occurred.
    weekday:
      type: object
      required:
      - date
      - observed
      properties:
        date:
          type: object
          required:
          - name
          - numeric
          properties:
            name:
              type: string
              example: Saturday
            numeric:
              type: string
              example: '6'
        observed:
          type: object
          required:
          - name
          - numeric
          properties:
            name:
              type: string
              example: Friday
            numeric:
              type: integer
              format: int32
              example: 5