@vantigo/bls-soc-map

Maps free-text job titles to U.S. Bureau of Labor Statistics (BLS) Standard Occupational Classification (SOC) codes. Includes 299 occupation patterns, role normalization, and Levenshtein fuzzy matching.

Installation

npm install @vantigo/bls-soc-map

Quick Start

const { getSocCode, normalizeRole } = require('@vantigo/bls-soc-map');

getSocCode('senior frontend engineer');   // → '15-1252'
getSocCode('registered nurse');           // → '29-1141'
getSocCode('data scientist');             // → '15-2051'

normalizeRole('Sr. Software Developer');  // → 'software engineer'
normalizeRole('RN');                      // → 'registered nurse'

API

getSocCode(role, options?) → string | null

Returns the BLS SOC code for a free-text job title. Uses exact match first, then Levenshtein fuzzy matching.

getSocCode('machine learning engineer');             // → '15-2051'
getSocCode('mlops', { fuzzyThreshold: 0.6 });        // → '15-1244'
getSocCode('not a real job title');                  // → null

Options: | Option | Type | Default | Description | |---|---|---|---| | fuzzyThreshold | number | 0.75 | Minimum similarity score (0–1) for fuzzy match |

normalizeRole(raw) → string

Lowercases, strips punctuation, and expands common abbreviations to the canonical role name.

normalizeRole('Sr. SWE');                 // → 'software engineer'
normalizeRole('VP of Engineering');       // → 'engineering manager'
normalizeRole('RN, BSN');                 // → 'registered nurse'

getSocTitle(socCode) → string | null

Returns the official BLS occupation title for a SOC code.

getSocTitle('15-1252');  // → 'Software Developers'
getSocTitle('29-1141');  // → 'Registered Nurses'

getRolesForCode(socCode) → string[]

Returns all normalized role names that map to a given SOC code.

getRolesForCode('15-1252');
// → ['software engineer', 'software developer', 'senior software engineer', ...]

getAllCodes() → string[]

Returns all unique SOC codes in the dataset.

SOC_MAP

The raw mapping object: { [normalizedRole]: socCode }. 299 entries across 30+ occupational categories.

Coverage

| Category | Roles Covered | |---|---| | Software Engineering | 25 patterns | | Data / ML / AI | 18 patterns | | Product & Design | 12 patterns | | Healthcare | 22 patterns | | Finance & Accounting | 18 patterns | | Legal | 8 patterns | | Sales & Marketing | 16 patterns | | Operations & HR | 14 patterns | | Education | 10 patterns | | Skilled Trades | 18 patterns | | … and 20+ more categories | … |

Dataset

The underlying mapping data is also available as a public CSV dataset:

• GitHub: data/soc-mappings.csv
• Hugging Face: (link to be added)
• Kaggle: (link to be added)

Format: role_input, normalized_role, soc_code, soc_title, confidence

Citation

If you use this package in academic research, please cite:

@software{ogirala2026blssocmap,
  author = {Ogirala, Kranthi Kumar},
  title  = {Vantigo BLS SOC Map: Job Title Normalization to BLS Standard Occupational Classification Codes},
  year   = {2026},
  url    = {https://github.com/ogkranthi/earnmore},
  note   = {npm package @vantigo/bls-soc-map}
}

Related Packages

• @vantigo/career-score — Multi-dimensional career health scoring
• @vantigo/geo-arbitrage — Net take-home geographic arbitrage calculator

License

MIT © Kranthi Kumar Ogirala / Vantigo