openapi: 3.0.0
info:
  title: Indonesia Schools API
  description: >-
    Complete API collection for Indonesian schools data with comprehensive filtering capabilities.
    Access to all schools in Indonesia with filtering by location (province, regency, district),
    searching by NPSN or name, filtering by status (Negeri/Swasta) and grade, with pagination support.
    Integrated with Indonesia Regional API for location data.
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Schools
    description: Endpoints for accessing Indonesian schools data.
paths:
  /regional/indonesia/schools:
    get:
      tags:
        - Schools
      summary: List Schools
      description: >-
        Get all schools in Indonesia with comprehensive filtering options.
        Supports filtering by location (province, regency, district), searching by NPSN or name,
        filtering by status (Negeri/Swasta) and grade, with pagination support.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: province_code
          in: query
          schema:
            type: string
          required: false
          description: Filter by province code
          example: '31'
        - name: regency_code
          in: query
          schema:
            type: string
          required: false
          description: Filter by regency/city code
          example: '3171'
        - name: district_code
          in: query
          schema:
            type: string
          required: false
          description: Filter by district code
          example: '317101'
        - name: npsn
          in: query
          schema:
            type: string
          required: false
          description: Exact match by National School Registration Number (NPSN)
          example: '20101567'
        - name: name
          in: query
          schema:
            type: string
          required: false
          description: Search by school name (case-insensitive partial match)
          example: 'SD NEGERI'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - N
              - S
          required: false
          description: Filter by status (N = Negeri/Public, S = Swasta/Private)
          example: 'N'
        - name: grade
          in: query
          schema:
            type: string
          required: false
          description: Search by school grade/type (case-insensitive partial match)
          example: 'SD'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          required: false
          description: Page number
          example: 1
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
          required: false
          description: Items per page
          example: 100
      responses:
        '200':
          description: Success - Schools 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:
                        npsn:
                          type: string
                          description: National School Registration Number
                          example: '20101567'
                        name:
                          type: string
                          description: School name
                          example: 'SD NEGERI 01 JAKARTA PUSAT'
                        grade:
                          type: string
                          description: School type/level
                          example: 'SD'
                        status:
                          type: string
                          description: School status (N = Negeri/Public, S = Swasta/Private)
                          example: 'N'
                        address:
                          type: string
                          description: Street address
                          example: 'JLN. MERDEKA SELATAN NO. 1'
                        province_code:
                          type: string
                          description: Province code
                          example: '31'
                        province_name:
                          type: string
                          description: Province name
                          example: 'DKI JAKARTA'
                        regency_code:
                          type: string
                          description: Regency/city code
                          example: '3171'
                        regency_name:
                          type: string
                          description: Regency/city name
                          example: 'KOTA ADM. JAKARTA PUSAT'
                        district_code:
                          type: string
                          description: District code
                          example: '317101'
                        district_name:
                          type: string
                          description: District name
                          example: 'GAMBIR'
                        lang:
                          type: number
                          format: float
                          description: Latitude
                          example: -6.1751
                        long:
                          type: number
                          format: float
                          description: Longitude
                          example: 106.8650
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 1
                      size:
                        type: integer
                        example: 100
                      total_item:
                        type: integer
                        example: 50000
                      total_page:
                        type: integer
                        example: 500
              examples:
                success:
                  summary: Success - Schools Listed
                  value:
                    is_success: true
                    message: Success
                    data:
                      - npsn: '20101567'
                        name: 'SD NEGERI 01 JAKARTA PUSAT'
                        grade: 'SD'
                        status: 'N'
                        address: 'JLN. MERDEKA SELATAN NO. 1'
                        province_code: '31'
                        province_name: 'DKI JAKARTA'
                        regency_code: '3171'
                        regency_name: 'KOTA ADM. JAKARTA PUSAT'
                        district_code: '317101'
                        district_name: 'GAMBIR'
                        lang: -6.1751
                        long: 106.8650
                      - npsn: '20101568'
                        name: 'SMP NEGERI 01 JAKARTA PUSAT'
                        grade: 'SMP'
                        status: 'N'
                        address: 'JLN. MERDEKA SELATAN NO. 2'
                        province_code: '31'
                        province_name: 'DKI JAKARTA'
                        regency_code: '3171'
                        regency_name: 'KOTA ADM. JAKARTA PUSAT'
                        district_code: '317101'
                        district_name: 'GAMBIR'
                        lang: -6.1752
                        long: 106.8651
                    paging:
                      page: 1
                      size: 100
                      total_item: 50000
                      total_page: 500
                filtered:
                  summary: Success - Filtered Schools
                  value:
                    is_success: true
                    message: Success
                    data:
                      - npsn: '20101567'
                        name: 'SD NEGERI 01 JAKARTA PUSAT'
                        grade: 'SD'
                        status: 'N'
                        address: 'JLN. MERDEKA SELATAN NO. 1'
                        province_code: '31'
                        province_name: 'DKI JAKARTA'
                        regency_code: '3171'
                        regency_name: 'KOTA ADM. JAKARTA PUSAT'
                        district_code: '317101'
                        district_name: 'GAMBIR'
                        lang: -6.1751
                        long: 106.8650
                    paging:
                      page: 1
                      size: 100
                      total_item: 1
                      total_page: 1
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid Page:
                  summary: Invalid Page Parameter
                  value:
                    is_success: false
                    message: 'Invalid parameter: page must be greater than or equal to 1'
                Invalid Size:
                  summary: Invalid Size Parameter
                  value:
                    is_success: false
                    message: 'Invalid parameter: size must be between 1 and 1000'
                Invalid Status:
                  summary: Invalid Status Value
                  value:
                    is_success: false
                    message: 'Invalid status value. Must be N (Negeri) or S (Swasta)'
        '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'
