Skills & taxonomies

Postings carry two independent classification vocabularies, and they answer different questions:

• skills — specific, granular capabilities. python, kubernetes, cpp. About 84% of postings have at least one (504,787 of 603,335).
• taxonomies — the job family. Software, Healthcare, Finance & Accounting. 28 fixed values, on about 64% of postings (385,246).

They're orthogonal. A posting can be Software with no skills, carry kubernetes with no taxonomy, or have both. Neither is guaranteed, which matters more than it sounds: filtering on either one silently excludes the postings that were never classified.

curl -G https://api.hyperjobs.io/v1/jobs \
  -H "Authorization: Bearer $HYPERJOBS_KEY" \
  --data-urlencode "skill=kubernetes" \
  --data-urlencode "taxonomies=Software"

The token model#

Skills are stored as canonical lower-case tokens with no spaces and no punctuation. Not free text, not the words that appeared in the posting — a normalised token drawn from a fixed vocabulary. Machine Learning in a job description becomes the token machinelearning.

skill= is a token match, not a substring match. skill=java does not match javascript, and skill=py matches nothing at all. Contrast with title= and description=, which are Google-style searches — see filtering.

Two alias tables, pointing opposite ways#

There are two separate translation layers, and conflating them is the source of almost every "but I can see that skill in the response" bug.

The full query-alias table:

The punctuated forms are not stored — c++ as a stored token is 0 rows, and c# is 0. They work only because the input alias rewrites them before the query runs. That's the whole table; anything not on it is sent through untranslated.

The round-trip problem#

// Turns a displayed skill back into a queryable token.
const toToken = (displayed) => displayed.replace(/[\s/]/g, "").toLowerCase();
 
toToken("Machine Learning"); // → "machinelearning"
toToken("CI/CD");            // → "cicd"

Comma means AND — but only for skill#

Comma means OR on every multi-value filter, with one exception: skill, where each value is another required condition, not an alternative.

# Tagged BOTH python AND aws. Not "either" — skill is the AND exception.
curl "…/v1/jobs?skill=python,aws"
 
# Either family — taxonomies is OR (overlap match).
curl "…/v1/jobs?taxonomies=Software,Healthcare"

skill's AND is exactly right when you mean it: skill=react,typescript,graphql finds roles that need all three, which is what a skill list usually means. Just don't carry the habit elsewhere — every other comma list in the API reads as OR now, and vice versa: a comma in skill= narrows where a comma anywhere else widens.

Getting OR across skills#

taxonomies no longer needs this — taxonomies=Software,Data & Analytics is a native union. skill still does: run one request per value and merge client-side.

const key = process.env.HYPERJOBS_KEY;
 
// The union of single-skill queries — the OR that `skill=` won't express.
async function anyOf(param, values) {
  const pages = await Promise.all(
    values.map((v) =>
      fetch(
        `https://api.hyperjobs.io/v1/jobs?${param}=${encodeURIComponent(v)}&limit=200`,
        { headers: { Authorization: `Bearer ${key}` } },
      ).then((r) => r.json()),
    ),
  );
 
  // Dedupe by id — a posting can legitimately carry several of the values.
  const byId = new Map(pages.flatMap((p) => p.data).map((j) => [j.id, j]));
  return [...byId.values()];
}
 
const rustOrGo = await anyOf("skill", ["rust", "go"]);

N values costs N requests against your rate limit. To mix AND with OR, put the AND terms in each request's comma list and vary the OR term across requests — skill=rust,kubernetes and skill=go,kubernetes unions to "(Rust or Go) and Kubernetes".

The 28 taxonomies#

Exact, Title-Case values. A casing miss or a value off this list is a 400 naming the allowed values — never a silent zero-row response.

Which one should you filter on?#

The practical guidance:

• Start with skill for anything technology-shaped. It's the highest-signal filter and has the best coverage of the three classifiers.
• Use taxonomies to scope, not to find. It's good for narrowing a broad query to a sector and bad as the only filter, because a third of postings carry no taxonomy and are invisible to it.
• Reach for title when the concept isn't a skill or a family. "Staff" and "Principal" are seniority signals in the title that no vocabulary captures — though note seniority is its own exact-match filter.
• Don't combine all three defensively. Every classifier you add is another AND, and each one drops the postings it never classified. Three filters at 84%, 64%, and 100% coverage intersect to a much smaller set than you expect, and it won't be obvious that's what happened.

Next#