openapi: 3.0.3
info:
  title: Holiday Countries 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: Countries
  description: Country metadata, codes, languages, currencies, and subdivisions.
paths:
  /v1/countries:
    get:
      operationId: listCountries
      tags:
      - Countries
      summary: List Countries
      description: Retrieves a list of countries with their 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: Return only the country with the specified code.
        required: false
        in: query
        schema:
          type: string
        example: US
      - name: search
        description: Search countries by code and name.
        required: false
        in: query
        schema:
          type: string
          minimum: 2
        example: United
      - name: public
        description: Return only countries that have public holidays.
        required: false
        in: query
        schema:
          type: boolean
          default: false
        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/countries'
components:
  schemas:
    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.
    country:
      type: object
      required:
      - code
      - name
      - codes
      - languages
      - currencies
      - flag
      - subdivisions
      - weekend
      properties:
        code:
          type: string
          example: US
        name:
          type: string
          example: United States of America
        codes:
          type: object
          required:
          - alpha-2
          - alpha-3
          - numeric
          properties:
            alpha-2:
              type: string
              minimum: 2
              maximum: 2
              example: US
            alpha-3:
              type: string
              minimum: 3
              maximum: 3
              example: USA
            numeric:
              type: integer
              format: int32
              example: 840
        languages:
          type: array
          items:
            type: string
            minimum: 2
            example: en
        currencies:
          type: array
          items:
            type: object
            required:
            - alpha
            properties:
              alpha:
                type: string
                minimum: 3
                maximum: 3
                example: USD
        flag:
          type: string
          example: https://holidayapi.com/images/flags/64/us.png
        subdivisions:
          type: array
          items:
            type: object
            required:
            - code
            - name
            - languages
            properties:
              code:
                type: string
                minimum: 4
                example: US-TX
              name:
                type: string
                example: Texas
              languages:
                type: array
                items:
                  type: string
                  minimum: 2
                  example:
                  - en
              subdivisions:
                type: array
                items:
                  type: object
                  required:
                  - code
                  - name
                  - languages
                  properties:
                    code:
                      type: string
                      minimum: 4
                      example: US-TX
                    name:
                      type: string
                      example: Texas
                    languages:
                      type: array
                      items:
                        type: string
                        minimum: 2
                        example:
                        - en
        weekend:
          type: array
          items:
            type: object
            required:
            - name
            - numeric
            properties:
              name:
                type: string
                example: Sunday
              numeric:
                type: integer
                format: int32
                example: 7
    countries:
      allOf:
      - $ref: '#/components/schemas/response'
      - type: object
        required:
        - countries
        properties:
          countries:
            type: array
            items:
              $ref: '#/components/schemas/country'