Public stats (marketing)
Public stats (marketing)
Section titled “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 }).
Caching and freshness
Section titled “Caching and freshness”- 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.generatedAtis 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.
Conventions
Section titled “Conventions”- All-time stock. Counts cover the whole platform, not a yearly cohort. (The authenticated
GET /admin/dashboardstays cohort-based.) - Status keys are public names, not raw database strings — e.g.
inProgress, notIN_PROGRESS. Every known status is always present (zero when empty). - Breakdowns omit unknowns.
byState,byTrade,byLevel,bySectoretc. drop rows with no resolvable key, so they can sum to less than the matchingtotal. - 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 oneLagosrow. - 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.
byMonthis 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.
CAP — GET /v1/public/stats
Section titled “CAP — GET /v1/public/stats”| 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 |
LMS — GET /v1/public/stats
Section titled “LMS — GET /v1/public/stats”| 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 ids vs names
Section titled “LMS ids vs names”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.
Example (CAP, trimmed)
Section titled “Example (CAP, trimmed)”{ "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 } }}Implementation
Section titled “Implementation”- CAP:
apps/cap/src/modules/public-stats/(public-stats.service.ts,ttl-cache.ts), controllercontrollers/v1/public-stats.controller.ts, mounted before the auth gate inroutes/v1/index.ts. - LMS: same layout under
apps/lms/src/. - Loading (Prisma
groupBy/countplus 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.tsin each app).