# How to Set Up and Use the Salary Benchmarking Tool in AI Job Search

> Learn to set up and use the AI Job Search salary benchmarking tool. Get company-specific salary metrics seamlessly integrated into your application workflow. Maximize your earnings.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: how-to-guide
- Published: 2026-07-26

---

**The salary benchmarking tool uses [`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py) to query a JSON data file ([`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json)) and returns company-specific salary metrics using fuzzy matching, integrating seamlessly into the `/apply` workflow when the data file is present.**

The `MadsLorentzen/ai-job-search` repository includes an optional salary benchmarking utility that provides compensation context during your job search. This tool operates independently from the core pipeline, meaning if the data file is missing, the rest of the application generation workflow continues without interruption.

## Architecture Overview

The salary benchmarking system consists of four primary components working together to normalize, validate, and query compensation data.

- **[`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json)** — Stores raw benchmark data with a top-level object containing a `metadata` section and a `companies` array. The exact schema is documented in [`tools/README_SALARY_TOOL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/README_SALARY_TOOL.md).

- **[`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py)** — Core script exposing three key functions: `load_data()` reads and validates the JSON, `search_company()` applies fuzzy matching via `match_score_optimized()`, and `format_entry()` renders readable output with categories, employee count, index values, and baseline comparisons.

- **Fuzzy Matching Logic** — Implemented in `normalize()`, `anglicize()`, `extract_core_words()`, and `match_score_optimized()` (lines 64-130 of [`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py)). This handles Danish/Nordic characters, strips legal suffixes like "A/S" and "ApS", and evaluates word-level overlap to match company names despite spelling variations.

- **[`tools/convert_salary_excel.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/convert_salary_excel.py)** — Utility that transforms Excel workbooks into the required JSON format by detecting column types using pattern sets (`COMPANY_PATTERNS`, `COUNT_PATTERNS`, etc.) and outputting the structured data (lines 40-100).

## Setting Up the Salary Data File

You have two methods for creating the required [`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json) file.

**Option A: Manual Creation**

Write a JSON file following the schema specified in [`tools/README_SALARY_TOOL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/README_SALARY_TOOL.md). Ensure the root object includes both `metadata` and `companies` keys.

**Option B: Excel Conversion**

Use the helper script to convert existing salary spreadsheets. This requires the `openpyxl` dependency.

```bash
python3 tools/convert_salary_excel.py input.xlsx output.json

```

The converter automatically identifies company names, cities, employee counts, and index values using regex patterns defined in [`convert_salary_excel.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/convert_salary_excel.py).

## Validating Your Data

Before running lookups, validate the JSON structure to catch malformed entries or duplicate company names.

```bash
python3 salary_lookup.py --validate

```

The `collect_validation_issues` function reports critical errors (missing required fields) and warnings (usability concerns). Passing validation ensures the fuzzy matching algorithms receive well-formed input.

## Running Salary Lookups

Query the database using company names. The tool accepts several output formats and filtering options.

Basic fuzzy lookup:

```bash
python3 salary_lookup.py "Novo Nordisk"

```

Filter by specific city:

```bash
python3 salary_lookup.py "Ørsted" --city "Fredericia"

```

Machine-readable JSON output:

```bash
python3 salary_lookup.py "COWI" --json

```

List all companies in the dataset:

```bash
python3 salary_lookup.py --list-all

```

The `search_company()` function normalizes input strings, handles diacritics automatically, and returns the best match based on the optimized scoring algorithm.

## Integration with the Job Application Workflow

Once [`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json) exists in the project root, the `/apply` command automatically invokes the salary lookup for each target company. According to the command definitions in `.claude/skills/job-application-assistant/`, the tool checks for file presence before execution. If the file is absent, the lookup step is silently skipped, preserving pipeline functionality.

No additional configuration is required. The integration calls [`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py) internally, displaying formatted benchmark data alongside the generated application materials.

## Summary

- **[`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py)** provides the core functionality through `load_data()`, `search_company()`, and `format_entry()`.
- **Optional operation** — The tool only activates when [`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json) is present; missing data does not break the `/apply` workflow.
- **Fuzzy matching** handles spelling variations, legal suffixes, and Nordic characters through normalization functions in lines 64-130.
- **Excel conversion** is available via [`tools/convert_salary_excel.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/convert_salary_excel.py) for migrating existing spreadsheet data.
- **CLI interface** supports validation, city filtering, JSON output, and listing all entries.

## Frequently Asked Questions

### What happens if I don't create the salary_data.json file?

The job application pipeline continues to function normally. When running `/apply`, the system detects the missing file and skips the salary lookup step entirely, allowing you to generate applications without benchmark data.

### How does the fuzzy matching handle company name variations?

The algorithm in `match_score_optimized()` normalizes strings by removing legal suffixes (A/S, ApS, Ltd), converting Nordic characters to ASCII equivalents via `anglicize()`, and extracting core words. It then calculates word-level overlap scores, enabling matches despite typos or formatting differences like "Novo Nordisk A/S" versus "Novo Nordisk".

### Can I use my existing Excel salary spreadsheet?

Yes. Run `python3 tools/convert_salary_excel.py` with your Excel file as input. The script in [`convert_salary_excel.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/convert_salary_excel.py) uses pattern matching to identify company, city, count, and index columns, then outputs properly formatted JSON ready for validation and lookup.

### Where can I find the exact JSON schema for salary_data.json?

The complete schema specification resides in [`tools/README_SALARY_TOOL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/README_SALARY_TOOL.md). The file expects a top-level object with `metadata` and `companies` arrays, where each company entry contains fields for name, city, employee count, and categorical index values.