Labor market intelligence

Retrieve labor market insights for programs, occupations, and skills using the Mapademics Embedded API.

Retrieve structured labor market intelligence tied to academic programs, occupations, and skills.

The Labor Market Intelligence capability allows you to query workforce outcomes and demand using academic CIP codes. It returns matched occupations, compensation, demand signals, and skill requirements in a single, structured response—ready to power catalogs, planning tools, and analytics.

---

What this enables

Use labor market intelligence to:

• Power program and course catalogs with workforce outcomes

• Support academic planning and prioritization

• Show employment, wage, and demand signals alongside programs

• Map programs to real occupations and required skills

• Drive advising, reporting, and strategy workflows

This capability is designed for discovery, comparison, and decision-making, not document analysis.

---

Typical use cases

• Program catalogs — Show outcomes on program detail pages

• Strategic planning — Compare programs by demand, growth, or salary

• Advising tools — Help students understand career paths tied to programs

• Institutional reporting — Support workforce alignment and outcomes narratives

• Market analysis — Identify high-demand or emerging fields of study

---

How it works

Labor market intelligence queries follow a straightforward pattern:

1. Query — Submit one or more CIP codes and a region

2. Match — The API matches relevant occupations

3. Return — Labor market metrics, demand signals, and skill requirements are returned in one response

This is a synchronous API: results are returned immediately.

---

Authentication

All requests require:

• Platform API key

• Customer API key (required for most production requests)

See Authentication.

---

Inputs

Required inputs

• CIP codes — One or more academic program identifiers

• Region type — One of: national, state, or msa

Optional inputs

• includeSkills — Set to true to include skill requirements for each occupation (default: false)

• fallbackFromMsaToState — Set to true to use state-level projection data when MSA-level data is unavailable (default: false)

Region rules

• If regionType is national, region is optional (defaults to United States)

• If regionType is state or msa, region is required

Example valid region combinations:

regionType	region
national	optional (defaults to United States)
state	required (e.g., "California")
msa	required (e.g., "San Francisco-Oakland-Berkeley, CA")

---

Integration walkthrough

This section describes the canonical integration pattern for querying labor market data by CIP code.

---

Step 1 — Query labor market data

Submit a request using one or more CIP codes and a region.

cURL

curl -X POST https://embedded-api.mapademics.com/v1/labor-market-intelligence/by-cip \
  -H "Authorization: Bearer $MAPADEMICS_API_KEY" \
  -H "X-Customer-Key: $MAPADEMICS_CUSTOMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cipCodes": ["11.0701"],
    "regionType": "national",
    "includeSkills": true
  }'

JavaScript

If you query with a state or msa region type, include the corresponding region value:

curl -X POST https://embedded-api.mapademics.com/v1/labor-market-intelligence/by-cip \
  -H "Authorization: Bearer $MAPADEMICS_API_KEY" \
  -H "X-Customer-Key: $MAPADEMICS_CUSTOMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cipCodes": ["11.0701"],
    "regionType": "state",
    "region": "California"
  }'

---

What you get back

A typical response is scoped to the requested CIP codes and region and includes labor market intelligence for matched occupations.

Response structure

Skill requirements are not included by default. Set includeSkills: true in your request body to receive them. The example below shows a response with includeSkills: true.

{
  "object": "cip_labor_market",
  "data": {
    "cipCodes": ["11.0701"],
    "regionType": "national",
    "region": "United States",
    "matchedOccupations": [
      {
        "name": "Software Developers",
        "description": "Research, design, and develop computer and network software or specialized utility programs.",
        "socCode": "15-1252",
        "alternativeTitles": [
          "Software Engineer",
          "Application Developer",
          "Backend Developer"
        ],
        "laborMarketData": {
          "medianAnnualSalary": 127260,
          "totalEmployment": 1795300,
          "forecastedEmploymentGrowth": 0.252,
          "averageAnnualOpenings": 0.174,
          "typicalDegreeLevel": "Bachelor's degree",
          "typicalWorkExperience": "None",
          "demand": {
            "score": 2,
            "factors": ["Rapid Growth", "High Hiring Demand"],
            "growthPercentile": 95,
            "openingsPercentile": 85
          }
        },
        "skillRequirements": {
          "coreSkills": [
            {
              "skillId": "msl_skill_0127",
              "name": "Software Development",
              "description": "Design, code, test, and maintain software applications."
            }
          ],
          "relevantSkills": [
            {
              "skillId": "msl_skill_0134",
              "name": "Database Management",
              "description": "Design and manage database systems."
            }
          ],
          "transferableSkills": [
            {
              "skillId": "msl_skill_0412",
              "name": "Problem Solving",
              "description": "Identify problems and determine effective solutions."
            }
          ]
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123xyz",
    "timestamp": "2025-01-30T12:00:00Z"
  }
}

---

Understanding the data

Matched occupations

Each CIP code may map to multiple occupations. These represent the most relevant workforce outcomes for the program.

Labor market data

Key workforce metrics include:

Field	Description
medianAnnualSalary	Median annual wage in USD
totalEmployment	Total employment count
forecastedEmploymentGrowth	Projected 10-year growth as a decimal (0.252 = 25.2%)
averageAnnualOpenings	Annual openings as a ratio of total employment
typicalDegreeLevel	Most common education requirement
typicalWorkExperience	Common experience requirement
demand.score	Number of demand factors present (0–2)
demand.factors	Contributing factors (e.g., "Rapid Growth", "High Hiring Demand")
demand.growthPercentile	How this occupation's growth compares nationally (0–100)
demand.openingsPercentile	How this occupation's openings compare nationally (0–100)

The demand score indicates how many positive demand signals apply to an occupation. A higher score indicates stronger overall demand. Use growthPercentile and openingsPercentile to rank and compare occupations across queries.

Skill requirements

Skill requirements are only included when includeSkills: true is set in the request.

Skill requirements are grouped into:

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

All skills are normalized to the Mapademics Skills Library and can be used consistently across products.

---

MSA fallback behavior

When querying MSA-level data, employment projections may not be available for all metropolitan areas. Set fallbackFromMsaToState: true to automatically use state-level projection data when MSA-level data is unavailable. When this fallback is used, a MSA_TO_STATE_PROJECTION_FALLBACK warning is included in the response.

---

Missing data

Not all occupations have data in every region. When data is not available for a given occupation-region pair:

• Fields return null, not zero — you never receive misleading values.

• A warnings array is included in the response explaining which data is unavailable and why.

Warning code	Meaning
INVALID_SOC_CODE / INVALID_CIP_CODE	Code not recognized
NO_EMPLOYMENT_DATA	No salary/employment data for this occupation in the requested region
NO_PROJECTION_DATA	No growth/openings data for this occupation in the requested region
MSA_TO_STATE_PROJECTION_FALLBACK	Projections use state-level data (no MSA data available)

See Data Coverage for coverage percentages across geographic levels.

---

Using the results effectively

Recommended practices:

• Treat CIP → occupation mappings as one-to-many

• Use demand scores and percentiles for ranking and comparison

• Surface alternative job titles to improve user recognition

• Use skill groupings to support curriculum alignment or advising

This data is designed to be shown, not just analyzed.

---

Common issues

Issue	Cause	Resolution
401 Unauthorized	Invalid or missing platform API key	Verify the Authorization header
403 Forbidden	Missing or invalid customer API key	Confirm the X-Customer-Key header
Empty results	CIP codes may be too narrow or invalid	Verify CIP code format (e.g., 11.0701)
Unexpected demand values	Demand is relative within region and occupation group	Use percentiles for cross-occupation comparison

For detailed error behavior, see Error Handling.

---

Next steps

• Integration Guide — Step-by-step implementation details

• API Reference — Full endpoint documentation

• Data Coverage — Coverage across occupations and regions

• Core Concepts — Understanding CIP codes, SOC codes, and demand signals

• The Mapademics Skills Library — Browse the skills taxonomy