KAU Open Data API

openapi: 3.1.0
x-operator: institution
x-operator-basis: >-
  opendata.kau.edu.sa is a host under kau.edu.sa, King Abdulaziz University's own
  registrable domain, resolving to 192.162.72.12 inside the university's own address
  block (the same /24 that carries sso.kau.edu.sa 192.162.72.15, iam.kau.edu.sa
  192.162.72.96, research.kau.edu.sa 192.162.72.204 and journals.kau.edu.sa
  192.162.72.203). The endpoints are published by KAU itself on its own Open Data page
  at https://www.kau.edu.sa/page/open-data (HTTP 200) and its Arabic twin
  https://kau.edu.sa/ar/page/open-data (HTTP 200), under a KAU open-data licence. No
  vendor name, vendor contact, or third-party host appears anywhere in this surface.
  This is King Abdulaziz University's own engineering, not a platform it rents.
x-provenance:
  generated: '2026-09-01'
  method: derived
  source: >-
    Derived, not fetched from a published specification — King Abdulaziz University
    publishes no OpenAPI. Two independent sources were combined. (1) The endpoint
    inventory, parameter names and permitted values are transcribed verbatim from the
    eight `https://opendata.kau.edu.sa/api/StudentsData` URLs that KAU itself links on
    its Open Data page, https://www.kau.edu.sa/page/open-data (HTTP 200, fetched
    2026-09-01) and identically on https://kau.edu.sa/ar/page/open-data (HTTP 200).
    (2) The response shape is read off a real 200 response body, not invented: the
    Internet Archive snapshot
    https://web.archive.org/web/20250417190254id_/https://opendata.kau.edu.sa/api/StudentsData?type=u&year=2023&semester=1
    (HTTP 200, application/json, 1,886 records), retrieved 2026-09-01. The Internet
    Archive CDX index records independent HTTP 200 application/json captures for seven
    further parameter combinations across 2024-03 to 2024-04, so the surface is
    corroborated across dates, not by a single snapshot.
  x-liveness-caveat: >-
    opendata.kau.edu.sa could NOT be reached from this run. It resolves normally in DNS
    but every request from two independent network egresses returned a connection
    timeout or ECONNREFUSED on 443, as did every other host in KAU's 192.162.72.0/24
    block, while www.kau.edu.sa (on AWS CloudFront, 3.173.x) answered 200 throughout.
    The consistent pattern — DNS resolves, KAU's own address block refuses, KAU's
    CDN-fronted host serves — reads as a geographic access restriction on KAU's
    self-hosted estate rather than a dead service, but this run cannot prove that. The
    last verified HTTP 200 from this API is the 2025-04-17 Internet Archive capture.
    This specification is therefore recorded as derived and NOT as probed-live.
info:
  title: King Abdulaziz University Open Data API
  version: '1.0'
  summary: KAU's institution-operated open data web service for student enrollment and graduation statistics.
  description: >-
    The web-service half of King Abdulaziz University's Open Data programme. KAU
    publishes aggregate, non-personal student counts — enrollment and graduation
    figures broken down by faculty, department, educational level, study type, gender,
    nationality and admission cohort — as JSON over a single unauthenticated GET
    endpoint, alongside spreadsheet downloads of the same material.

    This is one of very few genuinely institution-operated APIs in the higher-education
    cohort. It is KAU's own service on KAU's own domain and address space, with no
    vendor platform underneath it: not Figshare, not Elsevier Pure, not Ex Libris, not
    Dataverse. KAU's Open Data page labels the programme "Beta Version" and the earlier
    2026-06-03 profile of this institution recorded that page as an empty placeholder
    with no datasets or endpoints. That was wrong, and this specification is the
    correction: the page carries eight live API URLs and a decade of downloadable
    datasets.

    Records are aggregate counts only. No record identifies a student, and every field
    is a group label or a count, so there is no personal data in the response. Field
    values are returned in Arabic on both the Arabic and English surfaces.
  contact:
    name: King Abdulaziz University
    url: https://www.kau.edu.sa/page/open-data
  license:
    name: King Abdulaziz University Open Data Licence
    url: https://www.kau.edu.sa/page/open-data
  termsOfService: https://www.kau.edu.sa/page/open-data
servers:
  - url: https://opendata.kau.edu.sa
    description: >-
      King Abdulaziz University open data service, self-hosted in KAU's own
      192.162.72.0/24 address block. Not reachable from outside Saudi Arabia during
      this run; see x-provenance.x-liveness-caveat.
tags:
  - name: StudentsData
    description: Aggregate student enrollment and graduation statistics.
paths:
  /api/StudentsData:
    get:
      tags:
        - StudentsData
      operationId: getStudentsData
      summary: Retrieve aggregate student statistics
      description: >-
        Returns an array of aggregate student counts. Called with `type` alone the
        service returns the full series KAU publishes for that population; adding
        `year` and `semester` narrows the result to one academic term. All eight
        parameter combinations linked from KAU's Open Data page are listed in
        `x-documented-invocations` below.
      security: []
      parameters:
        - name: type
          in: query
          required: true
          description: >-
            Student population selector. Both permitted values are taken verbatim from
            the URLs KAU publishes; KAU's page does not define the letters in prose. In
            the archived `type=u` response every record carried a postgraduate
            `educationalLevel` (ماجستير / دكتوراه / دبلوم عالي), so the mapping of
            letter to population is recorded as observed rather than asserted.
          schema:
            type: string
            enum:
              - u
              - g
          examples:
            postgraduate:
              value: u
              summary: Population observed to return postgraduate levels in the 2025-04-17 capture.
            graduates:
              value: g
              summary: Second published population selector.
        - name: year
          in: query
          required: false
          description: >-
            Gregorian academic year. Only `2023` appears in KAU's published URLs; the
            service is assumed to accept other years but no other year has been
            observed returning 200, so none is claimed.
          schema:
            type: string
            pattern: '^[0-9]{4}$'
          example: '2023'
        - name: semester
          in: query
          required: false
          description: >-
            Academic term within `year`. KAU publishes semesters 1-3 for `type=u` and
            1-4 for `type=g`.
          schema:
            type: string
            enum: ['1', '2', '3', '4']
          example: '1'
      responses:
        '200':
          description: >-
            Array of aggregate student count records. The 2025-04-17 capture of
            `type=u&year=2023&semester=1` returned 1,886 records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudentsDataResponse'
              examples:
                postgraduateSemesterOne:
                  summary: First records of the archived 2025-04-17 response
                  externalValue: examples/kau-open-data-students-example.json
      x-documented-invocations:
        - https://opendata.kau.edu.sa/api/StudentsData?type=u
        - https://opendata.kau.edu.sa/api/StudentsData?type=u&year=2023&semester=1
        - https://opendata.kau.edu.sa/api/StudentsData?type=u&year=2023&semester=2
        - https://opendata.kau.edu.sa/api/StudentsData?type=u&year=2023&semester=3
        - https://opendata.kau.edu.sa/api/StudentsData?type=g
        - https://opendata.kau.edu.sa/api/StudentsData?type=g&year=2023&semester=1
        - https://opendata.kau.edu.sa/api/StudentsData?type=g&year=2023&semester=2
        - https://opendata.kau.edu.sa/api/StudentsData?type=g&year=2023&semester=3
        - https://opendata.kau.edu.sa/api/StudentsData?type=g&year=2023&semester=4
      x-undocumented:
        error_model: >-
          KAU documents no error responses and none was observed. No 4xx or 5xx
          response is described here because none has been seen; inventing one would
          credit KAU with a contract it has not published.
        rate_limits: No rate limit is documented or advertised.
        pagination: >-
          No pagination parameter is documented and the archived response returned all
          1,886 records in one unpaged array.
components:
  schemas:
    StudentsDataResponse:
      type: array
      description: Aggregate student count records, unpaged.
      items:
        $ref: '#/components/schemas/StudentsDataRecord'
    StudentsDataRecord:
      type: object
      description: >-
        One aggregate count: the number of students sharing a single combination of
        term, faculty, department, level, study type, gender, nationality and admission
        cohort. Every property below was present on all 1,886 records of the archived
        response, with the JSON type shown.
      required:
        - semesterCode
        - numberOfStudents
        - studyingType
        - educationalLevel
        - faculty
        - department
        - gender
        - nationality
        - admissionYear
        - admissionTerm
        - semesterDescription
      properties:
        semesterCode:
          type: string
          description: Term code, year followed by term number. Only '202310' observed.
          example: '202310'
        numberOfStudents:
          type: integer
          description: Count of students in this group. The only numeric field in the record.
          example: 70
        studyingType:
          type: string
          description: Mode of study, in Arabic.
          example: مشروع بحثي - خاص
        educationalLevel:
          type: string
          description: >-
            Award level, in Arabic. Observed values in the archived response were
            ماجستير (master's), دكتوراه (doctorate) and دبلوم عالي (higher diploma).
          example: ماجستير
        faculty:
          type: string
          description: Faculty name, in Arabic.
          example: الآداب و العلوم الإنسانية
        department:
          type: string
          description: Department name, in Arabic.
          example: الخدمة الاجتماعية
        gender:
          type: string
          description: Gender label, in Arabic — ذكر (male) or أنثى (female).
          example: ذكر
        nationality:
          type: string
          description: Nationality label, in Arabic.
          example: سعودي
        admissionYear:
          type: string
          description: Gregorian year of admission, as a string.
          example: '2022'
        admissionTerm:
          type: string
          description: Term of admission, as a string.
          example: '10'
        semesterDescription:
          type: string
          description: Human-readable term name, in Arabic.
          example: الفصل الدراسي الاول
  securitySchemes: {}
security: []