Core concepts

Foundational concepts and domain model used throughout the Mapademics Embedded API.

This page defines the foundational concepts used throughout the Mapademics Embedded API. Understanding these concepts will help you interpret API responses correctly, design your data model, and build integrations that reflect how academic offerings and labor market intelligence actually relate.

---

The mental model

The Embedded API supports two distinct workflows that connect through aggregation, not through a single API call.

Course
  ↓
Syllabus (PDF)
  ↓
Skills (from the Mapademics Skills Library)

Aggregation of Courses
  ↓
Program / Certificate / Non-Credential
  ↓
Matched Occupations
  ↓
Labor Market Intelligence

Key points:

• Skills extraction happens at the course level

• Labor market intelligence is evaluated at the program level

• The connection between the two happens through aggregation in your product

• Skills extraction and labor market intelligence are not sequential APIs

---

Course

A course is a unit of instruction in your system.

Mapademics does not manage courses directly. Courses are owned by your product and typically include:

• Metadata (term, credits, department, etc.)

• An associated syllabus PDF

Courses are the unit at which skills are extracted.

---

Syllabus

A syllabus is the authoritative input for skills extraction.

• Input format: PDF only

• Represents intended learning outcomes, topics, and assessments

• Used exclusively to derive structured skill data

A syllabus must be text-based. Scanned or image-only PDFs should be OCR'd upstream to ensure extraction quality.

---

Skill (Mapademics Skills Library)

A skill represents a normalized human capability drawn from the Mapademics Skills Library (MSL).

Skills are:

• Extracted from syllabus PDFs

• Returned with proficiency levels

• Stable and comparable across courses and programs

Skill object

{
  skillId: string;
  level: number;        // 1–5
  mode: "explicit" | "implicit";
  rationale?: string;
}

Skill levels

Skill levels are returned as a numeric value with the following semantics:

Level	Name	Meaning
1	Foundational	Basic awareness or introduction
2	Developing	Building competency through practice
3	Proficient	Consistent application in standard contexts
4	Advanced	Application in complex or novel situations
5	Expert	Mastery and ability to teach others

Levels are a core product signal and are intended to be used directly in downstream logic and UI.

---

Aggregation (product-owned)

Aggregation is something your product owns.

It typically involves:

• Grouping courses into a:

  • Program

  • Certificate

  • Non-credential offering

• Combining course-level skills into a program-level representation

Mapademics does not infer program structure automatically.

Labor market intelligence is evaluated against the aggregated academic offering, not individual courses.

This distinction is intentional and important.

---

Program / Certificate / Non-Credential

A program (or equivalent offering) represents a collection of courses that form a coherent academic pathway.

Programs:

• Are identified by one or more CIP codes

• Are the unit of analysis for labor market intelligence

• May represent degrees, certificates, or non-credit offerings

The same mental model applies regardless of credential type.

---

CIP codes

CIP (Classification of Instructional Programs) codes categorize academic programs.

• Required input to labor market intelligence

• One or more CIP codes may be supplied per request

• Used to match programs to relevant occupations

Format: XX.XXXX (e.g., 11.0701 for Computer Science)

Example request:

{
  "cipCodes": ["11.0701"]
}

CIP codes are maintained by the National Center for Education Statistics (NCES).

---

Occupation

An occupation represents a workforce role aligned to an academic offering.

Occupations:

• Are returned by the labor market API

• Are identified by SOC codes

• Are matched to programs via CIP codes

• Are not inferred directly from individual courses or syllabi

Each occupation includes:

• Job title and description

• Alternative titles

• Labor market metrics

• Skill requirements

---

SOC codes

SOC (Standard Occupational Classification) codes categorize occupations.

Format: XX-XXXX (e.g., 15-1252 for Software Developers)

SOC codes are maintained by the Bureau of Labor Statistics (BLS).

---

Skill requirements (occupation-level)

Occupations include grouped skill requirements that describe workforce expectations.

Skill requirements are grouped as:

Category	Description
Core skills	Central to the occupation
Relevant skills	Commonly required
Transferable skills	Broadly applicable across roles

All skills reference the Mapademics Skills Library.

---

Labor market intelligence

Labor market intelligence provides workforce outcomes for a program-level offering.

It includes:

• Employment and wage data

• Growth and demand signals

• Typical education and experience levels

• Skill requirements for matched occupations

Labor market intelligence:

• Is queried synchronously

• Is scoped by CIP codes + region

• Is designed to be heavily cached

---

Geographic regions

Labor market data can be scoped geographically.

Region types

regionType	Description	region requirement
national	Country-wide data	Optional (defaults to United States)
state	State-level data	Required
msa	Metropolitan statistical area	Required

Region selection affects:

• Data availability

• Caching strategy

• User experience defaults

Next steps

• Syllabus Skills Extraction — Extract skills from course syllabi

• Labor Market Intelligence — Query workforce outcomes

• Integration Patterns — Common implementation approaches

• The Mapademics Skills Library — Browse and search skills