Taxonomy namespace

Use board.taxonomy to resolve URL-facing category, skill, and place slugs into canonical page metadata. The places namespace also supplies the board’s location directory and autocomplete results. 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:

123456789
type TaxonomyResolution = {
  object: 'taxonomy_resolution';
  type: 'category' | 'skill' | 'place' | 'market';
  sourceSlug: string;
  canonicalSlug: string;
  displayName: string;
  redirectTo: string | null;
  geo: TaxonomyGeo;
};

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.

1234
board.taxonomy.categories.resolve(
  slug: string,
  options?: FetchOptions,
): Promise<TaxonomyResolution>

12345678
const category = await board.taxonomy.categories.resolve('software-engineer');

if (category.redirectTo) {
  console.log('Redirect permanently to:', category.redirectTo);
}

const jobs = await board.jobs.list({ category: category.sourceSlug });
console.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.

1234
board.taxonomy.skills.resolve(
  slug: string,
  options?: FetchOptions,
): Promise<TaxonomyResolution>

12345678
const skill = await board.taxonomy.skills.resolve('typescript');

if (skill.redirectTo) {
  console.log('Redirect permanently to:', skill.redirectTo);
}

const jobs = await board.jobs.list({ skill: skill.sourceSlug });
console.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.places.resolve

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

1234
board.taxonomy.places.resolve(
  slug: string,
  options?: FetchOptions,
): Promise<TaxonomyResolution>

123456789101112
const place = await board.taxonomy.places.resolve('london');

if (place.redirectTo) {
  console.log('Redirect permanently to:', place.redirectTo);
}

console.log(place.displayName, place.geo?.countryCode);

const jobs = await board.jobs.list({
  location: place.sourceSlug,
  radius: 25,
});

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.

1234
board.taxonomy.places.list(
  query?: PlacesListQuery,
  options?: FetchOptions,
): Promise<ListEnvelope<PublicPlace>>

123456789
const controller = new AbortController();
const matches = await board.taxonomy.places.list(
  { q: 'lon', limit: 5 },
  { signal: controller.signal },
);

for (const place of matches.data) {
  console.log(place.name, place.slug, place.jobCount);
}

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.

Canonical route pattern

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

12345678910
const taxonomy = await board.taxonomy.categories.resolve(inboundSlug);

if (taxonomy.redirectTo) {
  return new Response(null, {
    status: 308,
    headers: { location: `/jobs/${taxonomy.redirectTo}` },
  });
}

const 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.