openapi: 3.0.3
info:
  title: Holiday Countries Holidays 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: Holidays
  description: Public holidays and observances for countries, states, and provinces.
paths:
  /v1/holidays:
    get:
      operationId: listHolidays
      tags:
      - Holidays
      summary: List Holidays
      description: Retrieves a list of public holidays and observances for countries, states and provinces.
      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: year
        description: ISO 8601 format
        required: true
        in: query
        schema:
          type: integer
          format: int32
        example: 2015
      - name: month
        description: 1 or 2 digit month (1-12)
        required: false
        in: query
        schema:
          type: integer
          format: int32
        example: 7
      - name: day
        description: 1 or 2 digit day (1-31 depending on the month). Must be used with month.
        required: false
        in: query
        schema:
          type: integer
          format: int32
        example: 4
      - name: public
        description: Return only public holidays.
        required: false
        in: query
        schema:
          type: boolean
          default: false
        example: true
      - name: subdivisions
        description: Return state / province holidays alongside countrywide holidays. Available on our States & Provinces plan.
        required: false
        in: query
        schema:
          type: boolean
          default: false
        example: true
      - name: search
        description: Search holidays by name.
        required: false
        in: query
        schema:
          type: string
          minimum: 5
        example: Independence Day
      - name: language
        description: ISO 639-1 format (with exceptions).
        required: false
        in: query
        schema:
          type: string
        example: en
      - name: previous
        description: Return the first day of holidays that occur before the specific date. month and day are required. Cannot be used with upcoming.
        required: false
        in: query
        schema:
          type: boolean
        example: true
      - name: upcoming
        description: Return the first day of holidays that occur after the specific date. month and day are required. Cannot be used with previous.
        required: false
        in: query
        schema:
          type: boolean
        example: true
      - 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/holidays'
components:
  schemas:
    holidays:
      allOf:
      - $ref: '#/components/schemas/response'
      - type: object
        required:
        - holidays
        properties:
          holidays:
            type: array
            items:
              $ref: '#/components/schemas/holiday'
    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.
    holiday:
      type: object
      required:
      - name
      - date
      - observed
      - public
      - country
      - uuid
      - weekday
      properties:
        name:
          type: string
          example: Independence Day
        date:
          type: string
          format: date
          example: '2015-07-04'
        observed:
          type: string
          format: date
          example: '2015-07-03'
        public:
          type: boolean
          example: true
        country:
          type: string
          example: US
        uuid:
          type: string
          format: uuid
          example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
        weekday:
          $ref: '#/components/schemas/weekday'
        subdivisions:
          type: array
          items:
            type: string
            example:
            - US-FL
            - US-TX
    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