# How salary_lookup.py Benchmarks Compensation During Job Evaluation

> Discover how salary_lookup.py benchmarks compensation during job evaluation. Compare industry salary indices and percentage differences to understand relative pay. Optimize your job search and negotiation.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: performance
- Published: 2026-07-14

---

**salary_lookup.py benchmarks compensation by comparing company-specific salary indices against a configurable baseline index, calculating percentage differences across categories like base salary and bonuses to reveal how a prospective employer pays relative to industry standards.**

The [`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py) script in the [MadsLorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search) repository is a command-line utility designed to help job seekers benchmark compensation quickly. It ingests structured salary data from a JSON file and performs fuzzy matching against company names to retrieve relevant pay statistics. By comparing these figures against a baseline index, the tool provides instant context on whether an offer sits above or below market standards.

## The Three-Step Benchmarking Pipeline

### Load and Validate Salary Data

The process begins in [`salary_lookup.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_lookup.py) with the `load_data()` function, which reads the user-provided [`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json) file. Immediately after loading, `validate_data()` (lines 86‑101) enforces schema compliance, ensuring the JSON contains the required `metadata` object (including the `index_baseline` value) and a `companies` array where each entry provides salary categories with `count` and `index` values.

### Fuzzy Match the Target Company

To locate the correct employer, `search_company()` (lines 103‑129) normalizes the user’s query string and optionally filters by city. The function leverages `match_score_optimized()` (lines 30‑90) to score every company record against the query, retaining only entries with a match score of **30 or higher**. This threshold ensures the tool returns a tight roster of the most probable matches without noise.

### Calculate Percentage Differences Against Baseline

For each matching company, `format_entry()` (lines 132‑192) extracts the `categories` dictionary and computes the benchmark comparison. The script retrieves the global `baseline` value from the file’s metadata (defaulting to 100) and applies the formula:

```python
diff_pct = ((index - baseline) / baseline) * 100  # Lines 66-70

```

This calculation yields the percentage difference displayed in the "vs Baseline" column, instantly communicating whether the company’s **compensation index** sits above or below the reference standard.

## Running Salary Lookup from the Command Line

Execute the utility from the repository root to query specific employers:

```bash

# Basic lookup showing top matching companies

python salary_lookup.py "Novo Nordisk"

# Filter results to a specific location

python salary_lookup.py "Novo Nordisk" --city "Aarhus"

# Output raw JSON for integration with other tools

python salary_lookup.py "Novo Nordisk" --json

```

## Interpreting the Benchmark Output

The console displays a formatted table for each matched company:

```

============================================================
  Novo Nordisk
  Location: København
============================================================

  Category               Count   Index      vs Baseline
  --------------------------------------------------
  Base Salary            120   108.5        +8.5%
  Bonus                  115    95.0       -5.0%
  Stock Options           80    12.0       -88.0%

```

The **Index** represents the company’s compensation level for that category, while **vs Baseline** shows the calculated variance from the baseline of 100. Positive values indicate above-market pay, and negative values signal below-market rates. The **Count** column displays the sample size (e.g., number of surveyed employees) used to derive that index.

## Summary

- **salary_lookup.py** ingests [`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json) and validates it against a strict schema before processing.
- The `search_company()` function uses fuzzy matching with a threshold of ≥30 to identify relevant employers.
- Compensation benchmarks are calculated using `((index - baseline) / baseline) * 100`, comparing category indices against the metadata baseline.
- The CLI supports city filtering and JSON output modes for flexible integration into job evaluation workflows.

## Frequently Asked Questions

### What data format does salary_lookup.py require?

The utility expects a JSON file named [`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json) containing a `metadata` object with an `index_baseline` field and a `companies` array. Each company entry must include `name`, `location`, and a `categories` dictionary with numeric `count` and `index` values.

### How does the fuzzy matching algorithm work?

The `match_score_optimized()` function normalizes both the query and company names, then calculates a similarity score. Only companies scoring 30 or higher proceed to the final output, ensuring high-confidence matches even with slight spelling variations.

### Can I customize the baseline index?

Yes. The baseline defaults to 100 but is configurable via the `index_baseline` field in your [`salary_data.json`](https://github.com/MadsLorentzen/ai-job-search/blob/main/salary_data.json) metadata section. This allows you to adjust the reference point to reflect specific industry standards or geographic adjustments.

### Where can I find instructions for preparing the salary data?

Documentation for structuring your JSON or Excel source data is available in [`tools/README_SALARY_TOOL.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tools/README_SALARY_TOOL.md) within the repository. This file explains how to format categories and indices for optimal compatibility with the benchmarking tool.