openapi: 3.0.0
info:
  title: Indonesian Holidays API
  description: >-
    Complete API collection for accessing Indonesian public holidays, joint holidays, national holidays, and observances.
    Features include listing holidays with comprehensive filters, checking specific dates, getting upcoming holidays with countdown,
    holiday statistics and analytics, calendar views, and long weekend detection.
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Core Endpoints
    description: Core endpoints for listing and retrieving holidays with various filters.
  - name: Date Checking
    description: Endpoints for checking specific dates and date ranges.
  - name: Upcoming & Next Holiday
    description: Endpoints for getting next and upcoming holidays with countdown.
  - name: Statistics & Analytics
    description: Endpoints for holiday statistics, analytics, and calendar views.
  - name: Metadata
    description: Metadata endpoints for available years and holiday types.
  - name: Use Cases
    description: Real-world use case examples demonstrating practical API usage.
paths:
  /holidays/indonesia/:
    get:
      tags:
        - Core Endpoints
      summary: List Holidays
      description: >-
        Get all holidays with comprehensive filtering options. Supports filtering by year, month, type,
        date range, with pagination support. **Note:** Pagination size is fixed at 100 items per page and cannot be configured.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: year
          in: query
          schema:
            type: integer
          required: false
          description: Filter by year
          example: 2025
        - name: month
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 12
          required: false
          description: Filter by month (1-12)
          example: 1
        - name: type
          in: query
          schema:
            type: string
            enum:
              - Public Holiday
              - Joint Holiday
              - National Holiday
              - Observance
          required: false
          description: Filter by holiday type
          example: 'Public Holiday'
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          required: false
          description: Filter holidays from this date (YYYY-MM-DD)
          example: '2025-01-01'
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          required: false
          description: Filter holidays until this date (YYYY-MM-DD)
          example: '2025-12-31'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          required: false
          description: Page number
          example: 1
      responses:
        '200':
          description: Success - Holidays Listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Holiday ID
                          example: 'holiday_2025_01_01'
                        date:
                          type: string
                          format: date
                          description: Holiday date (YYYY-MM-DD)
                          example: '2025-01-01'
                        name:
                          type: string
                          description: Holiday name
                          example: 'Tahun Baru 2025'
                        type:
                          type: string
                          description: Holiday type
                          example: 'Public Holiday'
                        is_national_holiday:
                          type: boolean
                          description: Whether it's a national holiday
                          example: true
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 1
                      size:
                        type: integer
                        example: 100
                      total_item:
                        type: integer
                        example: 20
                      total_page:
                        type: integer
                        example: 1
              examples:
                success:
                  summary: Success - Holidays Listed
                  value:
                    is_success: true
                    message: Success
                    data:
                      - id: 'holiday_2025_01_01'
                        date: '2025-01-01'
                        name: 'Tahun Baru 2025'
                        type: 'Public Holiday'
                        is_national_holiday: true
                      - id: 'holiday_2025_01_17'
                        date: '2025-01-17'
                        name: 'Hari Raya Idul Fitri 1446 H'
                        type: 'National Holiday'
                        is_national_holiday: true
                    paging:
                      page: 1
                      size: 100
                      total_item: 20
                      total_page: 1
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid Date Format:
                  summary: Invalid Date Format
                  value:
                    is_success: false
                    message: 'Invalid date format. Use YYYY-MM-DD'
                Invalid Month:
                  summary: Invalid Month
                  value:
                    is_success: false
                    message: 'Month must be between 1 and 12'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
                Invalid API Key:
                  summary: Invalid API Key
                  value:
                    is_success: false
                    message: 'Invalid API key'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/{id}:
    get:
      tags:
        - Core Endpoints
      summary: Get Holiday by ID
      description: Get a single holiday by its ID.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Holiday ID
          example: 'holiday_2025_01_01'
      responses:
        '200':
          description: Success - Holiday Retrieved
          content:
            application/json:
              examples:
                success:
                  summary: Success - Holiday Retrieved
                  value:
                    is_success: true
                    message: Success
                    data:
                      id: 'holiday_2025_01_01'
                      date: '2025-01-01'
                      name: 'Tahun Baru 2025'
                      type: 'Public Holiday'
                      is_national_holiday: true
                      description: 'Hari libur nasional Tahun Baru 2025'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Holiday Not Found:
                  summary: Holiday Not Found
                  value:
                    is_success: false
                    message: 'Holiday not found'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/check/date:
    get:
      tags:
        - Date Checking
      summary: Check Date
      description: Check if a specific date is a holiday.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Date to check (YYYY-MM-DD)
          example: '2025-01-01'
      responses:
        '200':
          description: Success - Date Checked
          content:
            application/json:
              examples:
                is_holiday:
                  summary: Date is a Holiday
                  value:
                    is_success: true
                    message: Success
                    data:
                      date: '2025-01-01'
                      is_holiday: true
                      holiday:
                        id: 'holiday_2025_01_01'
                        name: 'Tahun Baru 2025'
                        type: 'Public Holiday'
                not_holiday:
                  summary: Date is Not a Holiday
                  value:
                    is_success: true
                    message: Success
                    data:
                      date: '2025-01-02'
                      is_holiday: false
                      holiday: null
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing Date:
                  summary: Missing Date Parameter
                  value:
                    is_success: false
                    message: 'Date parameter is required'
                Invalid Date Format:
                  summary: Invalid Date Format
                  value:
                    is_success: false
                    message: 'Invalid date format. Use YYYY-MM-DD'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/check/range:
    get:
      tags:
        - Date Checking
      summary: Check Date Range
      description: Get all holidays within a date range.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start date (YYYY-MM-DD)
          example: '2025-01-01'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: End date (YYYY-MM-DD)
          example: '2025-01-31'
        - name: type
          in: query
          schema:
            type: string
            enum:
              - Public Holiday
              - Joint Holiday
              - National Holiday
              - Observance
          required: false
          description: Filter by holiday type
          example: 'Public Holiday'
      responses:
        '200':
          description: Success - Holidays in Range
          content:
            application/json:
              examples:
                success:
                  summary: Success - Holidays in Range
                  value:
                    is_success: true
                    message: Success
                    data:
                      - id: 'holiday_2025_01_01'
                        date: '2025-01-01'
                        name: 'Tahun Baru 2025'
                        type: 'Public Holiday'
                      - id: 'holiday_2025_01_17'
                        date: '2025-01-17'
                        name: 'Hari Raya Idul Fitri 1446 H'
                        type: 'National Holiday'
                    total: 2
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing Dates:
                  summary: Missing Date Parameters
                  value:
                    is_success: false
                    message: 'Both start_date and end_date are required'
                Invalid Date Range:
                  summary: Invalid Date Range
                  value:
                    is_success: false
                    message: 'start_date must be before end_date'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/next:
    get:
      tags:
        - Upcoming & Next Holiday
      summary: Get Next Holiday
      description: Get the next upcoming holiday with countdown information.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: type
          in: query
          schema:
            type: string
            enum:
              - Public Holiday
              - Joint Holiday
              - National Holiday
              - Observance
          required: false
          description: Filter by holiday type
          example: 'Public Holiday'
      responses:
        '200':
          description: Success - Next Holiday Retrieved
          content:
            application/json:
              examples:
                success:
                  summary: Success - Next Holiday
                  value:
                    is_success: true
                    message: Success
                    data:
                      id: 'holiday_2025_01_01'
                      date: '2025-01-01'
                      name: 'Tahun Baru 2025'
                      type: 'Public Holiday'
                      days_until: 15
                      countdown: '15 days until Tahun Baru 2025'
                no_upcoming:
                  summary: No Upcoming Holiday
                  value:
                    is_success: true
                    message: Success
                    data: null
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/upcoming:
    get:
      tags:
        - Upcoming & Next Holiday
      summary: Get Upcoming Holidays
      description: Get a list of upcoming holidays with optional limit.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          required: false
          description: Maximum number of upcoming holidays to return
          example: 5
        - name: type
          in: query
          schema:
            type: string
            enum:
              - Public Holiday
              - Joint Holiday
              - National Holiday
              - Observance
          required: false
          description: Filter by holiday type
          example: 'Public Holiday'
      responses:
        '200':
          description: Success - Upcoming Holidays Retrieved
          content:
            application/json:
              examples:
                success:
                  summary: Success - Upcoming Holidays
                  value:
                    is_success: true
                    message: Success
                    data:
                      - id: 'holiday_2025_01_01'
                        date: '2025-01-01'
                        name: 'Tahun Baru 2025'
                        type: 'Public Holiday'
                        days_until: 15
                      - id: 'holiday_2025_01_17'
                        date: '2025-01-17'
                        name: 'Hari Raya Idul Fitri 1446 H'
                        type: 'National Holiday'
                        days_until: 31
                    total: 2
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid Limit:
                  summary: Invalid Limit
                  value:
                    is_success: false
                    message: 'Limit must be between 1 and 100'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/stats:
    get:
      tags:
        - Statistics & Analytics
      summary: Get Holiday Statistics
      description: Get holiday statistics including long weekend detection for a specific year.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: year
          in: query
          required: true
          schema:
            type: integer
            minimum: 2000
            maximum: 2100
          description: Year to get statistics for
          example: 2025
      responses:
        '200':
          description: Success - Statistics Retrieved
          content:
            application/json:
              examples:
                success:
                  summary: Success - Statistics
                  value:
                    is_success: true
                    message: Success
                    data:
                      year: 2025
                      total_holidays: 20
                      public_holidays: 15
                      national_holidays: 5
                      long_weekends:
                        - date: '2025-01-01'
                          name: 'Tahun Baru 2025'
                          type: 'Public Holiday'
                        - date: '2025-01-17'
                          name: 'Hari Raya Idul Fitri 1446 H'
                          type: 'National Holiday'
                      total_long_weekends: 2
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing Year:
                  summary: Missing Year Parameter
                  value:
                    is_success: false
                    message: 'Year parameter is required'
                Invalid Year:
                  summary: Invalid Year
                  value:
                    is_success: false
                    message: 'Year must be between 2000 and 2100'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/calendar:
    get:
      tags:
        - Statistics & Analytics
      summary: Get Holiday Calendar
      description: Get holidays for a specific month in calendar format.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: year
          in: query
          required: true
          schema:
            type: integer
            minimum: 2000
            maximum: 2100
          description: Year
          example: 2025
        - name: month
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 12
          description: Month (1-12)
          example: 1
      responses:
        '200':
          description: Success - Calendar Retrieved
          content:
            application/json:
              examples:
                success:
                  summary: Success - Calendar
                  value:
                    is_success: true
                    message: Success
                    data:
                      year: 2025
                      month: 1
                      holidays:
                        - date: '2025-01-01'
                          name: 'Tahun Baru 2025'
                          type: 'Public Holiday'
                        - date: '2025-01-17'
                          name: 'Hari Raya Idul Fitri 1446 H'
                          type: 'National Holiday'
                      total: 2
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing Parameters:
                  summary: Missing Parameters
                  value:
                    is_success: false
                    message: 'Both year and month parameters are required'
                Invalid Month:
                  summary: Invalid Month
                  value:
                    is_success: false
                    message: 'Month must be between 1 and 12'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/years:
    get:
      tags:
        - Metadata
      summary: Get Available Years
      description: Get all years that have holiday data in the database.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      responses:
        '200':
          description: Success - Years Retrieved
          content:
            application/json:
              examples:
                success:
                  summary: Success - Available Years
                  value:
                    is_success: true
                    message: Success
                    data:
                      - 2020
                      - 2021
                      - 2022
                      - 2023
                      - 2024
                      - 2025
                      - 2026
                    total: 7
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /holidays/indonesia/types:
    get:
      tags:
        - Metadata
      summary: Get Holiday Types
      description: Get all available holiday types with descriptions.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      responses:
        '200':
          description: Success - Types Retrieved
          content:
            application/json:
              examples:
                success:
                  summary: Success - Holiday Types
                  value:
                    is_success: true
                    message: Success
                    data:
                      - type: 'Public Holiday'
                        description: 'Public holiday observed nationwide'
                      - type: 'Joint Holiday'
                        description: 'Joint holiday observed by multiple regions'
                      - type: 'National Holiday'
                        description: 'National holiday of significant importance'
                      - type: 'Observance'
                        description: 'Cultural or religious observance'
                    total: 4
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
