Salary data

About 37% of postings carry a parsed salary — coverage_pct.salary on /v1/meta gives the live figure. The rest don't state one, and no amount of filtering will conjure them: this is a parsing result, not a coverage gap we're working through. A posting either advertised a figure or it didn't.

That number sets the ceiling on every salary question you can ask. has_salary=true doesn't narrow the dataset to the jobs that pay well — it narrows it to the jobs that said what they pay, which is a third of the market and not a random third.

The salary object#

{
  "salary": {
    "min": 180000,
    "max": 240000,
    "currency": "USD",
    "unit": "YEAR",
    "annual_min": 180000,
    "annual_max": 240000,
    "summary": "$180k–$240k"
  }
}

Always compare on annual_*#

The normalisation is done at parse time and guards against the arithmetic that trips up hand-rolled versions of this: an hourly rate has to be multiplied by ~2,080, not by 52, and a semi-monthly figure is already half-monthly, so multiplying it by 12 double-counts. If you're annualising min yourself, you're re-implementing a solved problem and will probably reintroduce one of those.

The salary_gte and salary_lte filters compare against these annualised bounds, so an hourly posting competes fairly with a salaried one server-side too.

Currency is not normalised#

// Wrong: mixes currencies into one distribution.
const avg = jobs.reduce((s, j) => s + j.salary.annual_min, 0) / jobs.length;

The salary_gte filter means "could pay this much"#

CAST(salary_annual_max AS REAL) >= N

There is no salary_min parameter — sending it is a 400. An early draft of this API had one, with these same overlap semantics while its name promised a floor; the rename to salary_gte is the fix.

A true floor filter#

Cut the result set server-side with has_salary=true and salary_currency, then apply the real predicate client-side:

const key = process.env.HYPERJOBS_KEY;
const qs = new URLSearchParams({
  skill: "rust",
  has_salary: "true",
  salary_currency: "USD",
  limit: "200",
});
 
const { data } = await fetch(`https://api.hyperjobs.io/v1/jobs?${qs}`, {
  headers: { Authorization: `Bearer ${key}` },
}).then((r) => r.json());
 
const FLOOR = 150_000;
 
const matches = data.filter((j) => {
  // has_salary only guarantees min OR max is set — annual_min can still be null
  // on a "up to $200k" posting.
  const s = j.salary;
  return s?.annual_min != null && s.annual_min >= FLOOR;
});

Building a comp benchmark#

Getting this right is mostly the three rules above applied at once. The histogram below buckets on annual_min, pins to one currency, and refuses rows that can't answer the question.

async function histogram({ skill, currency = "USD", width = 25_000 }) {
  const qs = new URLSearchParams({
    skill,
    has_salary: "true",
    salary_currency: currency,
    limit: "200",
  });
  const { data } = await fetch(`https://api.hyperjobs.io/v1/jobs?${qs}`, {
    headers: { Authorization: `Bearer ${process.env.HYPERJOBS_KEY}` },
  }).then((r) => r.json());
 
  const buckets = new Map();
 
  for (const job of data) {
    const s = job.salary;
    if (s?.annual_min == null) continue; // "up to $X" rows can't answer a floor question
 
    // Bucket on the annualised floor — `min` would put hourly roles in the $0 bin.
    const bucket = Math.floor(s.annual_min / width) * width;
    buckets.set(bucket, (buckets.get(bucket) ?? 0) + 1);
  }
 
  return [...buckets.entries()].sort((a, b) => a[0] - b[0]);
}

Two things to say out loud when you publish the result:

It describes postings, not people. Each row is one advertised range, not one filled job. A company that posts the same role in twelve cities contributes twelve observations to your distribution — collapsing folds those into one row if that's not what you want.

It describes postings that stated a salary. That's about 37% of the dataset, self-selected. Report it as "the range advertised by roles that disclose", because that's the only claim the data actually supports.

For a distribution rather than a sample, page the full filtered set with cursor — see pagination. The 200 rows above are one page, newest-first, which is a recency sample and not a random one.

Next#