Skip to content

Public stats (marketing)

Audience: frontend (marketing sites), backend, product
Status: built
Owns: backend
Depends on: REST — CAP, REST — LMS

Each service exposes one unauthenticated endpoint that returns platform-wide counts only — no names, emails, or row-level data. The marketing sites call these directly to show headline numbers, charts, and maps.

Service Endpoint OpenAPI operation Task
CAP GET /v1/public/stats getPublicStats (tag Public) CAP-74
LMS GET /v1/public/stats getPublicStats (tag Public) LMS-35

Both use security: [] and are listed in each service’s PUBLIC_V1_PATHS. Responses use the standard success envelope ({ success: true, data, meta }).

  • Each instance computes a snapshot at most once every 30 minutes (cacheTtlSeconds: 1800). Concurrent requests on a cold cache share one computation; a failed computation is not cached.
  • data.generatedAt is the snapshot time.
  • Cache-Control: public, max-age=<n> carries the remaining lifetime of the current snapshot, so a browser or CDN never holds a snapshot longer than the server would.
  • The cache is per instance (in memory). With several replicas, two requests may briefly see snapshots a few minutes apart.
  • All-time stock. Counts cover the whole platform, not a yearly cohort. (The authenticated GET /admin/dashboard stays cohort-based.)
  • Status keys are public names, not raw database strings — e.g. inProgress, not IN_PROGRESS. Every known status is always present (zero when empty).
  • Breakdowns omit unknowns. byState, byTrade, byLevel, bySector etc. drop rows with no resolvable key, so they can sum to less than the matching total.
  • Free-text grouping. States (and LMS gender) are grouped case- and whitespace-insensitively; the label is the most common spelling seen. "lagos " and "Lagos" become one Lagos row.
  • State values are returned as stored. CAP onboarding currently stores address-index state codes (e.g. LA, FCT), not display names, so the marketing site should map codes to names.
  • Sorting. Breakdowns are sorted by count (descending), then label. Level breakdowns are sorted by level. byMonth is the last 12 UTC months, oldest first, current month last, and always has 12 entries.
  • No test-data filtering. Seed and demo rows are counted like real ones.
Field Definition
candidates.total Candidate profiles
candidates.withApplication Distinct candidates with at least one submitted (non-draft) application
candidates.certified Distinct candidates with a CERTIFIED application or an issued certificate
candidates.byState Completed candidate onboarding residentialAddress.state
applications.total / byStatus All applications including drafts: draft, inProgress, certified, rejected, withdrawn
applications.byType Submitted applications by pathway: rpl, nsq
applications.sponsored Submitted applications paid through an organization cohort
applications.byLevel Submitted applications by qualification level (highest selected unit level, else the NSQ induction-form level)
applications.byTrade Submitted applications by Application.data.tradeId ({ id, name, count })
assessors.total / byStatus pending, approved, suspended, rejected
assessors.byQualification QAA / IQM / IV / EV holders across all statuses. Overlapping — one assessor can hold several
assessors.approvedByQualification Same, approved assessors only
assessors.approvedBySector Approved assessors by declared sector experience
assessors.approvedByState Completed assessor onboarding residentialAddress.state, approved only
centres.total / byStatus pending, approved, suspended, rejected
centres.approvedByState / approvedStatesCovered Centre.address.state for approved centres, and how many distinct states that is
centres.approvedByTrade Approved centres offering each active trade
catalogue sectors, trades (total / active / archived), nosDocuments (active / superseded), qualificationLevels, units
certificates.issued / revoked / issuedThisYear Certificate rows by status; issuedThisYear is the current UTC calendar year
certificates.byMonth / byTrade / byLevel Issued certificates over the last 12 months, by trade, by level
certificates.medianDaysToCertification Median days from first submit to certificate issue (1 dp); null with no data
awardingBodies.total Awarding bodies
jobPostings.total / byStatus open, closed, filled, cancelled
Field Definition
learners.total Learner profiles
learners.byStatus Learner membership: active, suspended
learners.certified Distinct learners holding at least one ISSUED certificate
learners.activeLast30Days Distinct learners with item progress updated in the last 30 days
learners.byState / byGender { label, count } from the learner profile
instructors.total / byStatus invited, active, suspended
levelOfferings.total / byStatus draft, published, archived
levelOfferings.publishedByQualificationLevel Published offerings by CAP QualificationLevel.id
unitOfferings Courses linked to a CAP unit (Course.unitId set): total, byStatus, publishedByTrade, publishedByQualificationLevel
standaloneCourses Courses not linked to a unit: total, byStatus
content Modules and items inside published courses; itemsByType: nativeLesson, video, quiz, assignment, scormPackage
enrollments.total / byStatus Course enrollments: pending, active, completed, expired, withdrawn
enrollments.completionRate completed ÷ (completed + active + expired), 3 dp; null when the denominator is 0
levelEnrollments.total / byStatus / sponsored pending, active, expired, withdrawn; sponsored = paid by an organization
certificates.issued / revoked / issuedThisYear / byMonth LMS completion certificates
seats Sponsored seat allocations: allocations, distinct organizations, totalSlots, seatsAssigned

LMS stores CAP catalogue references as opaque ids and has no trade or level names. That’s why publishedByTrade and publishedByQualificationLevel return { id, count }. To label them, match ids against CAP’s byTrade lists. CAP only includes a trade there once it has a count, so a full public label lookup would need a separate CAP endpoint.

{
"success": true,
"data": {
"generatedAt": "2026-10-28T12:00:00.000Z",
"cacheTtlSeconds": 1800,
"candidates": { "total": 1250, "withApplication": 980, "certified": 412, "byState": [{ "state": "Lagos", "count": 310 }] },
"assessors": { "total": 140, "byStatus": { "pending": 12, "approved": 118, "suspended": 2, "rejected": 8 }, "approvedByQualification": { "qaa": 40, "iqm": 9, "iv": 35, "ev": 21 } },
"centres": { "total": 64, "byStatus": { "pending": 5, "approved": 55, "suspended": 1, "rejected": 3 }, "approvedStatesCovered": 18 },
"catalogue": { "sectors": 6, "trades": { "total": 24, "active": 22, "archived": 2 } },
"certificates": { "issued": 430, "issuedThisYear": 190, "medianDaysToCertification": 41.5 }
}
}
  • CAP: apps/cap/src/modules/public-stats/ (public-stats.service.ts, ttl-cache.ts), controller controllers/v1/public-stats.controller.ts, mounted before the auth gate in routes/v1/index.ts.
  • LMS: same layout under apps/lms/src/.
  • Loading (Prisma groupBy / count plus a few raw SQL queries for JSON fields and array unnesting) is kept separate from shaping, so the shaping rules are unit-tested without a database (test/unit/public-stats.test.ts in each app).