API Documentation - Ghana Ministry of Education PMDV Dashboard

Overview

This document provides comprehensive documentation for all available factory endpoints in the Ghana Ministry of Education Performance Management and Data Visualization (PMDV) Dashboard API.

Base URL: baseURL (Development) or https://yourdomain.com:5001 (Production)

Content-Type: application/json

1. Attendance Rate API

Endpoint

Description

Retrieves teacher attendance rate data aggregated by term and week number. Data includes attendance rates, absent days per teacher, and present days.

Parameters

Example cURL Requests

Get all attendance rates for default academic year:

curl -X GET "baseURL/api/attendance_rate"

Get attendance rates for a specific region:

curl -X GET "baseURL/api/attendance_rate?source=R&sourceCode=01"

Get attendance rates for a specific district:

curl -X GET "baseURL/api/attendance_rate?source=D&sourceCode=0101&academicYear=2024/2025"

Sample Response

{
  "successful": true,
  "data": {
    "term0": [
      {
        "term": "0",
        "week_number": 1,
        "school_session_days": 5,
        "teachers_present": 45,
        "teachers_absent": 5,
        "total_number_absent_days": 12,
        "total_number_present_days": 225,
        "academic_year": "2024/2025",
        "average_number_of_absent_days_per_teacher": 2.4,
        "attendance_rate": 94.94
      }
    ],
    "term1": [],
    "term2": [],
    "term3": []
  }
}

2. Locations API

Endpoint

Description

Retrieves location data (regions or districts) from the database. Used to populate location dropdowns and filters.

Parameters

Example cURL Requests

Get all regions:

curl -X GET "baseURL/api/locations?source=R"

Get all districts:

curl -X GET "baseURL/api/locations?source=D"

Get districts for a specific region:

curl -X GET "baseURL/api/locations?source=D&sourceCode=01"

Sample Response

Regions Response:

{
  "successful": true,
  "data": [
    {
      "id": 1,
      "emis_region_code": "01",
      "name": "Greater Accra",
      "status": "A",
      "type": "R"
    }
  ]
}

3. NST Scores API

Endpoint

Description

Retrieves National Standardized Test (NST) scores aggregated by subject (Mathematics and English). Includes performance levels (below basic, basic, proficient, advanced) broken down by public/private and gender.

Parameters

Example cURL Requests

curl -X GET "baseURL/api/nst_scores?source=R&sourceCode=01"

Sample Response

{
  "successful": true,
  "data": {
    "math": {
      "math_below_basic": 1500,
      "math_total_students": 7000,
      ...
    },
    "english": {
      "english_below_basic": 1800,
      "english_total_students": 7000,
      ...
    }
  }
}

4. EMIS Schools Stats API

Endpoint

Description

Retrieves statistics about schools by education level and institution status (public/private). Counts schools for different levels: creche/nursery, kindergarten, primary, JHS, SHS, and TVET.

Parameters

Example cURL Requests

curl -X GET "baseURL/api/emis_schools_stats?source=R&sourceCode=01"

Sample Response

{
  "successful": true,
  "data": {
    "creche_nursery_private_count": 50,
    "creche_nursery_public_count": 30,
    "kg_private_count": 120,
    "kg_public_count": 200,
    ...
  }
}

5. NASIA API

Endpoint

Description

The NASIA endpoint is used to insert data into MongoDB. GET requests are not supported and will return an error.

Parameters

Example cURL Request

curl -X POST "baseURL/api/nasia" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": {"field1": "value1"},
    "agencyCode": "AGENCY001"
  }'

6. Schools API

Endpoint

Description

Retrieves a list of schools with their basic information including EMIS codes, names, and location codes.

Parameters

Example cURL Requests

curl -X GET "baseURL/api/schools?source=D&sourceCode=0101"

Sample Response

{
  "successful": true,
  "data": [
    {
      "id": 1,
      "emis_region_code": "01",
      "emis_district_code": "0101",
      "name": "Accra Senior High School",
      "emis_school_code": "010101001",
      "type": "S"
    }
  ]
}

7. Enrollment Rates API

Endpoint

Description

Retrieves comprehensive enrollment rate data including GER, NER, NAR, GAR, Completion Rate, and GPI.

Parameters

Example cURL Request

curl -X GET "baseURL/api/enrollment_rates?source=R&sourceCode=01&academicYear=2024"

Sample Response

{
  "successful": true,
  "data": [
    {
      "class": "Primary 1",
      "sector": "Public",
      "GER_Male": 95.5,
      "GER_Female": 93.2,
      "NER_Total": 87.2,
      "GPI": 0.976
    }
  ]
}

Common Error Responses

400 Bad Request

{
  "successful": false,
  "error": {
    "code": "DB_ACCESS_ERROR_CODE",
    "message": "Database access error message"
  }
}

405 Method Not Allowed

{
  "message": "Unsupported HTTP method"
}

Notes

API Endpoints Summary Table

Legend: R = Region, D = District, ESC = EMIS School Code