Taxonomy namespace

Reference for category, skill, and place resolution.

Use board.taxonomy to list and resolve the categories, skills, and places used by published jobs, and to load the board’s location directory. Keyword typeahead lives on board.search.suggest. These reads are public.

Shared behavior

Every method returns the Board API wire body unchanged and throws BoardApiError for a non-2xx response. The final FetchOptions argument passes abort signals, headers, and framework cache directives through to fetch.

The three resolve methods share this result:

1type TaxonomyResolution = {
2  object: 'taxonomy_resolution';
3  type: 'category' | 'skill' | 'place' | 'market';
4  sourceSlug: string;
5  canonicalSlug: string;
6  displayName: string;
7  redirectTo: string | null;
8  geo: TaxonomyGeo;
9};

sourceSlug is the immutable English taxonomy key. canonicalSlug and displayName reflect the board language. Emit a 308 to redirectTo when it is non-null. geo is null for categories and skills; place resolutions can include latitude/longitude, country/region codes, region, city, locality, and place type.

`board.taxonomy.categories.resolve`

Resolve a board-language or English category slug.

1board.taxonomy.categories.resolve(
2  slug: string,
3  options?: FetchOptions,
4): Promise<TaxonomyResolution>

1const category = await board.taxonomy.categories.resolve('software-engineer');
2
3if (category.redirectTo) {
4  console.log('Redirect permanently to:', category.redirectTo);
5}
6
7const jobs = await board.jobs.list({ category: category.sourceSlug });
8console.log(category.displayName, jobs.count);

An unknown category or unavailable board returns categories_not_found with status 404.

Related methods: board.jobs.list and board.companies.salaries.category.

`board.taxonomy.skills.resolve`

Resolve a board-language or English skill slug.

1board.taxonomy.skills.resolve(
2  slug: string,
3  options?: FetchOptions,
4): Promise<TaxonomyResolution>

1const skill = await board.taxonomy.skills.resolve('typescript');
2
3if (skill.redirectTo) {
4  console.log('Redirect permanently to:', skill.redirectTo);
5}
6
7const jobs = await board.jobs.list({ skill: skill.sourceSlug });
8console.log(skill.displayName, jobs.count);

An unknown skill or unavailable board returns skills_not_found with status 404.

Related method: board.jobs.list.

`board.taxonomy.categories.list`

List the board’s active job categories with localized names, canonical slugs, parent IDs, and live published-job counts.

1board.taxonomy.categories.list(
2  query?: CategoryListQuery,
3  options?: FetchOptions,
4): Promise<ListEnvelope<PublicTaxonomyTerm>>

1const categories = await board.taxonomy.categories.list({ limit: 50 });
2
3for (const category of categories.data) {
4  console.log(category.displayName, category.canonicalSlug, category.jobCount);
5}
6
7const top = await board.taxonomy.categories.list({
8  limit: 8,
9  sort: 'jobCount',
10});

CategoryListQuery accepts the shared list fields below plus topLevel:

Field	Type	Behavior
`topLevel`	`boolean`	`true` returns only top-level categories (those with no parent). Combines with `q` and `sort`, and is bound into the cursor. Omit it, or pass `false`, to list every category.

Top-level categories

Each category carries parentId, the id of its parent category, or null for a top-level category. Pass topLevel: true to list only the top-level categories, for example on a homepage:

1const parents = await board.taxonomy.categories.list({
2  topLevel: true,
3  sort: 'jobCount',
4  limit: 12,
5});
6
7for (const category of parents.data) {
8  console.log(category.displayName, category.jobCount);
9}

To group child categories under their parents, list every category and match each child’s parentId to a parent’s id. A top-level category appears only when it has published jobs of its own, like every other term in these lists.

`board.taxonomy.skills.list`

List the board’s active job skills with localized names and canonical slugs. Category and skill lists accept the same query fields:

Field	Type	Behavior
`q`	`string`	Case- and accent-insensitive substring match against the display name, source slug, or canonical slug. The match can start mid-word, so `script` matches `TypeScript`. An empty value returns no terms.
`cursor`	`string`	Opaque cursor from `nextCursor`. It is bound to the original `q`, `limit`, and `sort`.
`limit`	`number`	Page size from 1 to 100; defaults to 20.
`sort`	`'name' \| 'jobCount'`	`name` (default) is locale-aware display-name order. `jobCount` is live published-job count, highest first, with `name` as the tie-break.

1let page = await board.taxonomy.skills.list({ q: 'script', limit: 20 });
2
3while (page.hasMore && page.nextCursor) {
4  page = await board.taxonomy.skills.list({
5    q: 'script',
6    limit: 20,
7    cursor: page.nextCursor,
8  });
9}

Each PublicTaxonomyTerm contains object, id, type, parentId, sourceSlug, canonicalSlug, displayName, and jobCount. jobCount is the board-wide published-job total for that term (the same maintained counter that decides whether the term is active) — not a tally of the current list page. Only terms backed by published jobs are returned. parentId is the parent category’s id, or null for a top-level category and for every skill. Canonical-slug collisions are de-duplicated. A missing or private board returns 404.

`board.taxonomy.places.resolve`

Resolve a board-language or English place slug and return its geo metadata.

1board.taxonomy.places.resolve(
2  slug: string,
3  options?: FetchOptions,
4): Promise<TaxonomyResolution>

1const place = await board.taxonomy.places.resolve('london');
2
3if (place.redirectTo) {
4  console.log('Redirect permanently to:', place.redirectTo);
5}
6
7console.log(place.displayName, place.geo?.countryCode);
8
9const jobs = await board.jobs.list({
10  location: place.sourceSlug,
11  radius: 25,
12});

radius is in kilometres and only widens a place whose geo.placeType is city or locality and that has geo.lat and geo.lng. Use geo.countryCode with distanceUnitForCountry from @cavuno/board/format to choose miles or kilometres for a distance menu.

An unknown place or unavailable board returns places_not_found with status 404. Do not fabricate coordinates when geo or individual geo fields are null.

Related methods: board.taxonomy.places.list and board.jobs.list.

`board.taxonomy.places.list`

Without q, return every place used by a published job, with live job counts. With q, return location-autocomplete matches.

1board.taxonomy.places.list(
2  query?: PlacesListQuery,
3  options?: FetchOptions,
4): Promise<ListEnvelope<PublicPlace>>

Field	Type	Behavior
`q`	`string`	At least two characters returns ranked matches. Fewer than two returns an empty list. Omit it for directory mode.
`limit`	`number`	Autocomplete result cap from 1 to 50; defaults to 10. Ignored in directory mode.

1const controller = new AbortController();
2const matches = await board.taxonomy.places.list(
3  { q: 'lon', limit: 5 },
4  { signal: controller.signal },
5);
6
7for (const place of matches.data) {
8  console.log(place.name, place.slug, place.jobCount);
9}

Autocomplete matching is case- and accent-insensitive. A place matches when q appears anywhere in its name, including mid-word (ndon matches London), or when its slug starts with q. Places whose name or slug starts with q rank first, then places with more published jobs.

Each PublicPlace contains id, parentId, slug, name, placeType, countryCode, regionCode, and jobCount. In directory mode, use id and parentId to rebuild the place hierarchy. slug can be null, so do not create a public link for an unslugged row.

The directory is bounded and unpaginated; hasMore is false and nextCursor is null for the complete result. A short autocomplete query returning an empty data array is successful. A missing/private board returns 404.

Related methods: board.taxonomy.places.resolve and board.jobs.list.

`board.taxonomy.remotePermits.list`

List the canonical remote-permit option set — the {type, value, label} entries the API accepts wherever a job states where remote candidates must hold work authorization (remotePermits on v1 job writes, remoteWorkingPermits on public job postings).

1board.taxonomy.remotePermits.list(
2  options?: FetchOptions,
3): Promise<ListEnvelope<RemotePermitTaxonomyEntry>>

1const permits = await board.taxonomy.remotePermits.list();
2
3const countries = permits.data.filter((entry) => entry.type === 'country');
4const blocs = permits.data.filter((entry) => entry.type === 'custom');

Each entry's type is one of worldwide, world_region, continent, region, subregion, custom (blocs such as EU), country (ISO 3166-1 alpha-2), or subdivision (ISO 3166-2). The data is platform reference — identical for every board — and served board-scoped so this client can reach it; responses are cacheable for six hours on public boards. The list is complete and unpaginated (hasMore is always false).

Submitting a {type, value} pair outside this set is rejected (jobs_invalid_permit), so build permit pickers from this list rather than a hardcoded one. For a countries-only picker with localized display names, COUNTRY_CODES and countryOptions from @cavuno/board/format mirror the country slice of this taxonomy without a network call.

Canonical route pattern

Resolve the inbound slug before loading the programmatic page. This keeps localized and English aliases on one URL:

1const taxonomy = await board.taxonomy.categories.resolve(inboundSlug);
2
3if (taxonomy.redirectTo) {
4  return new Response(null, {
5    status: 308,
6    headers: { location: `/jobs/${taxonomy.redirectTo}` },
7  });
8}
9
10const jobs = await board.jobs.list({ category: taxonomy.sourceSlug });

Resolve and redirect before emitting canonical metadata. A taxonomy 404 should produce the route’s real not-found response.