openapi: 3.0.0
info:
  title: Api Jadwal Sholat Indonesia
  description: >-
    Complete API collection for Indonesian prayer times (jadwal sholat) by regency.
    Features include listing available regencies with prayer time data, getting prayer times by regency code
    with optional date range filtering, and fixed pagination support.
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Prayer Times
    description: Endpoints for accessing Indonesian prayer times by regency.
paths:
  /regional/indonesia/prayer-times/regencies:
    get:
      tags:
        - Prayer Times
      summary: List Available Regencies
      description: >-
        Get all regencies that have prayer time data available.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
          required: false
          nullable: true
          description: 'Page number (optional, default: 1). Pagination size is fixed at 100 items per page.'
          example: 1
      responses:
        '200':
          description: Success - Available Regencies
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Regency code (4 digits)
                          example: '1101'
                        name:
                          type: string
                          description: Regency name
                          example: 'KABUPATEN SIMEULUE'
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      size:
                        type: integer
                      total_item:
                        type: integer
                      total_page:
                        type: integer
              examples:
                success:
                  summary: Success - Available Regencies
                  value:
                    is_success: true
                    message: Success
                    data:
                      - code: '1101'
                        name: 'KABUPATEN SIMEULUE'
                      - code: '1102'
                        name: 'KABUPATEN ACEH SINGKIL'
                      - code: '1103'
                        name: 'KABUPATEN ACEH SELATAN'
                      - code: '3171'
                        name: 'KOTA JAKARTA SELATAN'
                      - code: '3172'
                        name: 'KOTA JAKARTA TIMUR'
                    paging:
                      page: 1
                      size: 100
                      total_item: 514
                      total_page: 6
        '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'
                    data: null
                Invalid API Key:
                  summary: Invalid API Key
                  value:
                    is_success: false
                    message: 'Invalid API key'
                    data: null
        '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'
                    data: null
  /regional/indonesia/prayer-times:
    get:
      tags:
        - Prayer Times
      summary: Get Prayer Times by Regency Code
      description: >-
        Get prayer times for a specific regency code with optional date range filtering.
        Returns prayer times sorted by date (ascending). Each entry includes date information,
        GMT offset, and all prayer times (Imsyak, Shubuh, Terbit, Dhuha, Dzuhur, Ashr, Maghrib, Isya).
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: regency_code
          in: query
          required: true
          schema:
            type: string
            pattern: '^\d{4}$'
          description: Regency code (required, 4 digits, e.g., 3171 for Jakarta Selatan)
          example: '3171'
        - name: start_date
          in: query
          schema:
            type: string
            format: date
          required: false
          nullable: true
          description: 'Start date filter (optional, format: YYYY-MM-DD). Only prayer times on or after this date are returned.'
          example: '2024-01-01'
        - name: end_date
          in: query
          schema:
            type: string
            format: date
          required: false
          nullable: true
          description: 'End date filter (optional, format: YYYY-MM-DD). Only prayer times on or before this date are returned.'
          example: '2024-01-31'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
          required: false
          nullable: true
          description: 'Page number (optional, default: 1). Pagination size is fixed at 100 items per page.'
          example: 1
      responses:
        '200':
          description: Success - Prayer Times
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        regency_code:
                          type: string
                          description: Regency code (4 digits)
                        regency_name:
                          type: string
                          description: Regency name
                        gmt:
                          type: integer
                          description: GMT offset
                        date:
                          type: string
                          format: date
                          description: Prayer time date in YYYY-MM-DD format
                        year:
                          type: integer
                        month:
                          type: integer
                        day:
                          type: integer
                        imsyak:
                          type: string
                          description: 'Pre-dawn time (HH:MM format)'
                          example: '04:30'
                        shubuh:
                          type: string
                          description: 'Dawn prayer / Fajr (HH:MM format)'
                          example: '04:40'
                        terbit:
                          type: string
                          description: 'Sunrise (HH:MM format)'
                          example: '05:55'
                        dhuha:
                          type: string
                          description: 'Mid-morning prayer (HH:MM format)'
                          example: '06:25'
                        dzuhur:
                          type: string
                          description: 'Noon prayer / Dhuhr (HH:MM format)'
                          example: '12:05'
                        ashr:
                          type: string
                          description: 'Afternoon prayer / Asr (HH:MM format)'
                          example: '15:20'
                        maghrib:
                          type: string
                          description: 'Sunset prayer (HH:MM format)'
                          example: '18:15'
                        isya:
                          type: string
                          description: 'Night prayer (HH:MM format)'
                          example: '19:30'
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      size:
                        type: integer
                      total_item:
                        type: integer
                      total_page:
                        type: integer
              examples:
                success:
                  summary: Success - Prayer Times
                  value:
                    is_success: true
                    message: Success
                    data:
                      - id: 1
                        regency_code: '3171'
                        regency_name: 'KOTA JAKARTA SELATAN'
                        gmt: 7
                        date: '2024-01-01'
                        year: 2024
                        month: 1
                        day: 1
                        imsyak: '04:30'
                        shubuh: '04:40'
                        terbit: '05:55'
                        dhuha: '06:25'
                        dzuhur: '12:05'
                        ashr: '15:20'
                        maghrib: '18:15'
                        isya: '19:30'
                      - id: 2
                        regency_code: '3171'
                        regency_name: 'KOTA JAKARTA SELATAN'
                        gmt: 7
                        date: '2024-01-02'
                        year: 2024
                        month: 1
                        day: 2
                        imsyak: '04:30'
                        shubuh: '04:40'
                        terbit: '05:56'
                        dhuha: '06:26'
                        dzuhur: '12:05'
                        ashr: '15:20'
                        maghrib: '18:15'
                        isya: '19:30'
                      - id: 3
                        regency_code: '3171'
                        regency_name: 'KOTA JAKARTA SELATAN'
                        gmt: 7
                        date: '2024-01-03'
                        year: 2024
                        month: 1
                        day: 3
                        imsyak: '04:31'
                        shubuh: '04:41'
                        terbit: '05:56'
                        dhuha: '06:26'
                        dzuhur: '12:06'
                        ashr: '15:21'
                        maghrib: '18:16'
                        isya: '19:31'
                    paging:
                      page: 1
                      size: 100
                      total_item: 366
                      total_page: 4
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing Regency Code:
                  summary: Missing Regency Code Parameter
                  value:
                    is_success: false
                    message: 'regency_code query parameter is required'
                    data: null
                Invalid Regency Code:
                  summary: Invalid Regency Code
                  value:
                    is_success: false
                    message: 'Invalid regency_code format'
                    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'
                    data: null
                Invalid API Key:
                  summary: Invalid API Key
                  value:
                    is_success: false
                    message: 'Invalid API key'
                    data: null
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Regency Not Found:
                  summary: Regency Not Found
                  value:
                    is_success: false
                    message: 'Regency code not found or no prayer time data available'
                    data: null
        '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'
                    data: null

