Taxonomy & Metadata API

Explore subject catalogs, examination years, topic taxonomies, curriculum trees, and platform metrics with zero discovery friction.

Discovery · 0 credits (Free)Curriculum / L2 · 3 creditsFree & Developer tiers

2.2.0Overview

The Taxonomy & Metadata API allows developer applications to dynamically bootstrap dropdown pickers, verify available examination years, search subjects by curriculum track, and inspect platform vitality metrics.

To support seamless developer onboarding, all catalog and taxonomy discovery endpoints (/subjects, /subjects/{subject}, /subjects/{subject}/years, /subjects/years/{year}, and /metrics) are 0 credits (Free). Deep curriculum mapping (/curriculum) and per-question knowledge metadata are accessible on Layer 2 (3 credits).

2.2.1Endpoints & Discovery Layer

Explore the available endpoints for subject discovery, years drilldown, and platform metrics:

METHODPATHDESCRIPTION

GET/subjectsCatalog of subjects with codes, categories, and feature flags. (0 credits)

GET/subjects/{subject}Single subject profile, topics count, and per-exam breakdown. Supports codes (e.g. MTH). (0 credits)

GET/subjects/{subject}/topicsTopics and subtopics taxonomy for a subject. (0 credits)

GET/subjects/{subject}/yearsAvailable years for a subject with counts split by exam type. (0 credits)

GET/subjects/years/{year}Available subjects for a specific year with exam breakdown. (0 credits)

GET/curriculumCurriculum syllabus tree with Bloom’s taxonomy and objectives. (3 credits)

GET/metricsPublic platform stats: total questions and total requests served. (0 credits)

GET/metrics/subjects-callCumulative usage request volume grouped by subject. (0 credits)

2.2.2Per-Question Metadata Properties (L2)

When calling the Questions API with metadata filters (e.g., ?topic=algebra) or on Developer plans, questions include the enriched metadata object:

PROPERTYTYPEDESCRIPTION

topicstringCurriculum topic name, e.g. "algebra".

subtopicstringSpecific subtopic, e.g. "quadratic-equations".

difficultyScoreinteger (1-5)Calculated difficulty, where 1 is easiest and 5 is hardest.

estimatedTimeinteger (sec)Estimated student solving time in seconds.

tagsarray [string]Descriptive keywords for concept mapping.

curriculumAlignmentstringSpecific syllabus match code (e.g. WAEC-SSCE-MTH-2024).

classificationConfidencefloat (0-1)Accuracy confidence score of the classifier.

2.2.3Example Responses

GET /api/v1/subjects0 credits

{
  "data": [
    {
      "name": "mathematics",
      "displayName": "Mathematics",
      "code": "MTH",
      "category": "sciences",
      "aliases": ["math", "maths", "general-mathematics"],
      "questionCount": 1250,
      "features": {
        "hasPassages": false,
        "hasEquations": true,
        "hasDiagrams": true
      },
      "examTypes": ["waec", "jamb", "neco"],
      "yearRange": { "min": 2000, "max": 2024 }
    }
  ]
}

GET /api/v1/subjects/mathematics/years0 credits

{
  "data": [
    {
      "year": 2021,
      "questionCount": 120,
      "examTypes": ["waec", "jamb"],
      "breakdown": {
        "waec": 70,
        "jamb": 50
      }
    }
  ]
}

GET /api/v1/metrics0 credits

{
  "data": {
    "totalQuestions": 50000,
    "totalRequests": 1250000
  }
}