openapi: 3.0.0
info:
  title: Api Data Sekolah Indonesia
  description: >-
    Complete API collection for Indonesian schools data with comprehensive filtering capabilities and premium features.


    ## Features

    - Access to all schools in Indonesia

    - Filter by province, regency, district

    - Search by NPSN, school name, status, and grade

    - Filter by accreditation (premium only)

    - Advanced search endpoint (premium only)

    - Geographic data (latitude/longitude - premium only)

    - Accreditation data (premium only)

    - Fast search with dynamic query parameters

    - Pagination support

    - Integrated with Api Regional Wilayah Indonesia for location data


    ## Authentication

    All requests require an API key in the `x-api-co-id` header.


    ## Premium Features

    The following features require a premium subscription:

    - **Latitude & Longitude** - Geographic coordinates (non-premium users will see: null)

    - **Accreditation Data** - School accreditation information (non-premium users will see: null)

    - **Accreditation Filter** - Filter schools by accreditation

    - **Advanced Search** - `/regional/indonesia/schools/search` endpoint for searching by name, NPSN, or address


    ## Base URL

    ```
    https://use.api.co.id/regional/indonesia/schools
    ```


    ## Integration with Api Regional Wilayah Indonesia

    This API is connected to the [Api Regional Wilayah Indonesia](https://api.co.id/indonesia-regional-api/) for location data. You can use the `province_code`, `regency_code`, and `district_code` returned in the response to fetch detailed location information from the Regional API.

    ### Example: Get Province Details

    ```bash
    GET https://use.api.co.id/regional/indonesia/provinces/{province_code}
    ```

    ### Example: Get Regency Details

    ```bash
    GET https://use.api.co.id/regional/indonesia/regencies/{regency_code}
    ```

    ### Example: Get District Details

    ```bash
    GET https://use.api.co.id/regional/indonesia/districts/{district_code}
    ```

    Visit [https://api.co.id/indonesia-regional-api/](https://api.co.id/indonesia-regional-api/) for complete Regional API documentation.


    ## Data Fields

    - **npsn**: National School Registration Number

    - **name**: School name (sekolah)

    - **grade**: School type/level (bentuk)

    - **status**: School status - **N** = Negeri (Public), **S** = Swasta (Private)

    - **accreditation**: School accreditation (A, B, C, etc.) - **Premium Only**

    - **address**: Street address (alamat_jalan)

    - **province_code**: Province code (use with Regional API)

    - **province_name**: Province name (api_propinsi)

    - **regency_code**: Regency/city code (use with Regional API)

    - **regency_name**: Regency/city name (api_kabupaten_kota)

    - **district_code**: District code (use with Regional API)

    - **district_name**: District name (api_kecamatan)

    - **lang**: Latitude (lintang) - **Premium Only**

    - **long**: Longitude (bujur) - **Premium Only**


    ## Filtering Options

    - `province_code`: Filter by province code

    - `regency_code`: Filter by regency/city code

    - `district_code`: Filter by district code

    - `npsn`: Exact match by NPSN

    - `name`: Search by school name (case-insensitive partial match)

    - `status`: Filter by status (N = Negeri, S = Swasta)

    - `grade`: Search by school grade/type (case-insensitive partial match)

    - `accreditation`: Filter by accreditation (A, B, C, etc.) - **Premium Only**

    - `page`: Page number (default: 1)

    - **Note:** Pagination size is fixed at 100 items per page and cannot be configured
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Schools
    description: Endpoints for accessing Indonesian schools data.
  - name: Search (Premium)
    description: Advanced search endpoint for schools. Search endpoint requires premium subscription.
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. **Note:** Pagination size is fixed at 100 items per page and cannot be configured.


        ### Premium Fields

        Non-premium users will see `null` for:

        - `accreditation`

        - `lang` (latitude)

        - `long` (longitude)
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          required: true
          example: '{{api_key}}'
        - name: province_code
          in: query
          schema:
            type: string
          required: false
          description: Filter by province code
        - name: regency_code
          in: query
          schema:
            type: string
          required: false
          description: Filter by regency/city code
        - name: district_code
          in: query
          schema:
            type: string
          required: false
          description: Filter by district code
        - name: npsn
          in: query
          schema:
            type: string
          required: false
          description: Exact match by National School Registration Number (NPSN)
        - name: name
          in: query
          schema:
            type: string
          required: false
          description: Search by school name (case-insensitive partial match)
        - name: status
          in: query
          schema:
            type: string
            enum:
              - N
              - S
          required: false
          description: Filter by status (N = Negeri/Public, S = Swasta/Private)
        - name: grade
          in: query
          schema:
            type: string
          required: false
          description: Search by school grade/type (case-insensitive partial match, e.g., SD, SMP, SMA, SMK)
        - name: accreditation
          in: query
          schema:
            type: string
            nullable: true
          required: false
          description: Filter by accreditation (A, B, C, etc.) - **Premium Only**. Requires premium subscription.
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          required: false
          description: Page number
          example: 1
      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: '10100101'
                        name:
                          type: string
                          description: School name
                          example: 'SD NEGERI 1 BANDA ACEH'
                        grade:
                          type: string
                          description: School type/level
                          example: 'SD'
                        status:
                          type: string
                          description: School status (N = Negeri/Public, S = Swasta/Private)
                          example: 'N'
                        accreditation:
                          type: string
                          nullable: true
                          description: 'School accreditation (A, B, C, etc.) - Premium Only. Non-premium users will see null'
                          example: null
                        address:
                          type: string
                          description: Street address
                          example: 'JL. CUT NYAK DIEN NO. 1'
                        province_code:
                          type: string
                          description: Province code
                          example: '11'
                        province_name:
                          type: string
                          description: Province name
                          example: 'ACEH'
                        regency_code:
                          type: string
                          description: Regency/city code
                          example: '1171'
                        regency_name:
                          type: string
                          description: Regency/city name
                          example: 'KOTA BANDA ACEH'
                        district_code:
                          type: string
                          description: District code
                          example: '1171010'
                        district_name:
                          type: string
                          description: District name
                          example: 'BAITURRAHMAN'
                        lang:
                          oneOf:
                            - type: number
                              format: float
                            - type: 'null'
                          nullable: true
                          description: 'Latitude - Premium Only. Non-premium users will see null'
                          example: -5.548056
                        long:
                          oneOf:
                            - type: number
                              format: float
                            - type: 'null'
                          nullable: true
                          description: 'Longitude - Premium Only. Non-premium users will see null'
                          example: 95.319167
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 1
                      size:
                        type: integer
                        example: 100
                      total_item:
                        type: integer
                        example: 250000
                      total_page:
                        type: integer
                        example: 2500
              examples:
                premiumUser:
                  summary: Success - List Schools (Premium User)
                  value:
                    is_success: true
                    message: Success
                    data:
                      - npsn: '10100101'
                        name: 'SD NEGERI 1 BANDA ACEH'
                        grade: 'SD'
                        status: 'N'
                        accreditation: 'A'
                        address: 'JL. CUT NYAK DIEN NO. 1'
                        province_code: '11'
                        province_name: 'ACEH'
                        regency_code: '1171'
                        regency_name: 'KOTA BANDA ACEH'
                        district_code: '1171010'
                        district_name: 'BAITURRAHMAN'
                        lang: -5.548056
                        long: 95.319167
                    paging:
                      page: 1
                      size: 100
                      total_item: 250000
                      total_page: 2500
                nonPremiumUser:
                  summary: Success - List Schools (Non-Premium User)
                  value:
                    is_success: true
                    message: Success
                    data:
                      - npsn: '10100101'
                        name: 'SD NEGERI 1 BANDA ACEH'
                        grade: 'SD'
                        status: 'N'
                        accreditation: null
                        address: 'JL. CUT NYAK DIEN NO. 1'
                        province_code: '11'
                        province_name: 'ACEH'
                        regency_code: '1171'
                        regency_name: 'KOTA BANDA ACEH'
                        district_code: '1171010'
                        district_name: 'BAITURRAHMAN'
                        lang: null
                        long: null
                    paging:
                      page: 1
                      size: 100
                      total_item: 250000
                      total_page: 2500
        '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 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: 'Unauthorized: API key is required'
                Invalid API Key:
                  summary: Invalid API Key
                  value:
                    is_success: false
                    message: 'Invalid API key'
        '403':
          description: Forbidden - Premium Required
          content:
            application/json:
              examples:
                Not Premium:
                  summary: Error - Not Premium
                  value:
                    is_success: false
                    message: 'Accreditation filter is for premium members only'
        '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'
  /regional/indonesia/schools/search:
    get:
      tags:
        - Search (Premium)
      summary: Search Schools (Premium)
      description: >-
        Advanced search across school name, NPSN, and address. **This endpoint requires a premium subscription.**


        ### Query Parameters

        - `query` (required): Search term (searches name, NPSN, and address)

        - `page` (optional): Page number (default: 1)

        - **Note:** Pagination size is fixed at 100 items per page and cannot be configured


        ### Examples

        ```bash
        # Search by name
        GET /regional/indonesia/schools/search?query=SD NEGERI

        # Search by NPSN
        GET /regional/indonesia/schools/search?query=10100101

        # Search by address
        GET /regional/indonesia/schools/search?query=JL. CUT NYAK DIEN
        ```
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          required: true
          example: '{{api_key}}'
        - name: query
          in: query
          schema:
            type: string
          required: true
          description: Search term (required) - searches name, NPSN, and address
          example: 'SD NEGERI'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          required: false
          description: Page number (optional)
          example: 1
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  timestamp:
                    type: string
                    example: '2026-01-16 10:30:45'
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        npsn:
                          type: string
                          example: '10100101'
                        name:
                          type: string
                          example: 'SD NEGERI 1 BANDA ACEH'
                        grade:
                          type: string
                          example: 'SD'
                        status:
                          type: string
                          example: 'N'
                        accreditation:
                          type: string
                          example: 'A'
                        address:
                          type: string
                          example: 'JL. CUT NYAK DIEN NO. 1'
                        province_code:
                          type: string
                          example: '11'
                        province:
                          type: string
                          example: 'ACEH'
                        regency_code:
                          type: string
                          example: '1171'
                        regency:
                          type: string
                          example: 'KOTA BANDA ACEH'
                        district_code:
                          type: string
                          example: '1171010'
                        district:
                          type: string
                          example: 'BAITURRAHMAN'
                        lat:
                          type: number
                          format: float
                          example: -5.548056
                        long:
                          type: number
                          format: float
                          example: 95.319167
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                        example: 1
                      size:
                        type: integer
                        example: 100
                      total_item:
                        type: integer
                        example: 25000
                      total_page:
                        type: integer
                        example: 250
              examples:
                success:
                  summary: Success - Search Results
                  value:
                    status: success
                    timestamp: '2026-01-16 10:30:45'
                    result:
                      - npsn: '10100101'
                        name: 'SD NEGERI 1 BANDA ACEH'
                        grade: 'SD'
                        status: 'N'
                        accreditation: 'A'
                        address: 'JL. CUT NYAK DIEN NO. 1'
                        province_code: '11'
                        province: 'ACEH'
                        regency_code: '1171'
                        regency: 'KOTA BANDA ACEH'
                        district_code: '1171010'
                        district: 'BAITURRAHMAN'
                        lat: -5.548056
                        long: 95.319167
                      - npsn: '10100102'
                        name: 'SD NEGERI 2 BANDA ACEH'
                        grade: 'SD'
                        status: 'N'
                        accreditation: 'A'
                        address: 'JL. TEUKU UMAR NO. 15'
                        province_code: '11'
                        province: 'ACEH'
                        regency_code: '1171'
                        regency: 'KOTA BANDA ACEH'
                        district_code: '1171010'
                        district: 'BAITURRAHMAN'
                        lat: -5.549167
                        long: 95.320278
                    paging:
                      page: 1
                      size: 100
                      total_item: 25000
                      total_page: 250
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Unauthorized: API key is required'
        '403':
          description: Forbidden - Premium Required
          content:
            application/json:
              examples:
                Not Premium:
                  summary: Error - Not Premium
                  value:
                    is_success: false
                    message: 'This endpoint is for premium members only'
        '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'
