openapi: 3.0.3
info:
  title: Calendarific Holiday API
  description: |
    Worldwide public holidays REST API covering 230+ countries.
    Calendarific provides accurate holiday data including national, local,
    religious, and observance holidays. Useful for ecommerce, scheduling,
    HR systems, travel planning, and global operations.
  version: "2.0"
  contact:
    name: Calendarific Support
    email: info@calendarific.com
    url: https://calendarific.com/
  termsOfService: https://calendarific.com/terms
  license:
    name: Commercial
    url: https://calendarific.com/pricing
servers:
  - url: https://calendarific.com/api/v2
    description: Production
tags:
  - name: Holidays
    description: Retrieve holiday data for any country and year.
  - name: Countries
    description: List supported countries and their ISO codes.
  - name: Languages
    description: List supported languages and their ISO codes.
security:
  - apiKey: []
paths:
  /holidays:
    get:
      tags:
        - Holidays
      summary: List Holidays
      description: |
        Returns holidays for a given country and year. Supports filtering
        by month, day, location (sub-region), holiday type, and language.
      operationId: listHolidays
      parameters:
        - name: api_key
          in: query
          required: true
          description: Calendarific API key issued via the developer console.
          schema:
            type: string
        - name: country
          in: query
          required: true
          description: ISO-3166 country code (e.g., US, GB, IN).
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: year
          in: query
          required: true
          description: Year to retrieve holidays for. Historical data available through 2049.
          schema:
            type: integer
            minimum: 1900
            maximum: 2049
        - name: day
          in: query
          required: false
          description: Filter to a specific day of the month (1-31).
          schema:
            type: integer
            minimum: 1
            maximum: 31
        - name: month
          in: query
          required: false
          description: Filter to a specific month (1-12).
          schema:
            type: integer
            minimum: 1
            maximum: 12
        - name: location
          in: query
          required: false
          description: ISO-3166 state or region code (e.g., us-ca for California).
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: Filter by holiday type (national, local, religious, observance).
          schema:
            type: string
            enum:
              - national
              - local
              - religious
              - observance
        - name: language
          in: query
          required: false
          description: Premium parameter. Two-letter ISO639 language code.
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: uuid
          in: query
          required: false
          description: Premium parameter. Include UUID values for each holiday.
          schema:
            type: boolean
      responses:
        "200":
          description: A list of matching holidays.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HolidaysResponse"
        "401":
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: Invalid parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Internal server error.
        "503":
          description: Service unavailable.
  /countries:
    get:
      tags:
        - Countries
      summary: List Countries
      description: |
        Returns the full list of countries supported by Calendarific,
        including ISO-3166 codes and the languages supported per country.
      operationId: listCountries
      parameters:
        - name: api_key
          in: query
          required: true
          description: Calendarific API key.
          schema:
            type: string
      responses:
        "200":
          description: List of supported countries.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CountriesResponse"
        "401":
          description: Missing or invalid API key.
        "429":
          description: Rate limit exceeded.
  /languages:
    get:
      tags:
        - Languages
      summary: List Languages
      description: |
        Returns the full list of languages supported by Calendarific
        with their two-letter ISO639 codes.
      operationId: listLanguages
      parameters:
        - name: api_key
          in: query
          required: true
          description: Calendarific API key.
          schema:
            type: string
      responses:
        "200":
          description: List of supported languages.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LanguagesResponse"
        "401":
          description: Missing or invalid API key.
        "429":
          description: Rate limit exceeded.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as a URL query parameter.
  schemas:
    Meta:
      type: object
      properties:
        code:
          type: integer
          description: HTTP-style status code echoed in the body.
          example: 200
      required:
        - code
    Error:
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/Meta"
        error:
          type: object
          properties:
            type:
              type: string
            info:
              type: string
    HolidayDateComponents:
      type: object
      properties:
        year:
          type: integer
        month:
          type: integer
        day:
          type: integer
    HolidayDate:
      type: object
      properties:
        iso:
          type: string
          description: ISO 8601 date string.
          example: "2024-12-25"
        datetime:
          $ref: "#/components/schemas/HolidayDateComponents"
    HolidayCountry:
      type: object
      properties:
        id:
          type: string
          description: ISO-3166 alpha-2 country code (lowercase).
          example: us
        name:
          type: string
          example: United States
    Holiday:
      type: object
      properties:
        name:
          type: string
          example: Christmas Day
        description:
          type: string
          example: Christmas Day is one of the biggest Christian celebrations and falls on the 25th of December each year.
        country:
          $ref: "#/components/schemas/HolidayCountry"
        date:
          $ref: "#/components/schemas/HolidayDate"
        type:
          type: array
          items:
            type: string
          example:
            - National holiday
        primary_type:
          type: string
          example: National holiday
        canonical_url:
          type: string
          format: uri
        urlid:
          type: string
        locations:
          type: string
        states:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
        uuid:
          type: string
          format: uuid
          description: Returned only when uuid=true is requested (premium).
    HolidaysResponse:
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/Meta"
        response:
          type: object
          properties:
            holidays:
              type: array
              items:
                $ref: "#/components/schemas/Holiday"
    Country:
      type: object
      properties:
        country_name:
          type: string
          example: United States
        iso-3166:
          type: string
          example: US
        total_holidays:
          type: integer
          example: 198
        supported_languages:
          type: integer
          example: 4
        uuid:
          type: string
          format: uuid
    CountriesResponse:
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/Meta"
        response:
          type: object
          properties:
            countries:
              type: array
              items:
                $ref: "#/components/schemas/Country"
    Language:
      type: object
      properties:
        name:
          type: string
          example: English
        iso-639:
          type: string
          example: en
    LanguagesResponse:
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/Meta"
        response:
          type: object
          properties:
            languages:
              type: array
              items:
                $ref: "#/components/schemas/Language"