Resolve places, occupations and skills

Resolve the person's words once, then save the returned ids and slugs with the query. These lookups use bundled GeoNames and curated taxonomy data; requests never call an LLM or Google Maps.

Places and ambiguous names

resolveLocation searches names and aliases by prefix. Each candidate has:

• id: GeoNames id, or a negative synthetic id for a region or metro.
• name, country (ISO country code), and kind (city, metro, admin1, country, region).
• context: readable disambiguation, such as Ontario, Canada.
• adminArea: the parent first-level administrative area's id, name and country-local GeoNames code, or null when unavailable.
• population: the bundled GeoNames population, or null when unavailable. This is not a current estimate; synthetic regions and metros generally have none.

London, UK (2643743) and London, Ontario (6058560) are distinct candidates. Do not silently pick the most populous place when the request is ambiguous: ask the person and save the chosen id in JobQuery.places. These are candidate lookups, not a free-form address geocoder. For an input such as “near London in Ontario”, search the place name and use the returned country/admin area to choose.

Roles and occupation codes

findRoles (MCP find_occupation) returns:

• items: search-facing role candidates with family slugs and live openJobs counts. Put their slugs in JobQuery.roles.
• occupations: classification candidates with socCode (O*NET-SOC 2019), iscoCode (ISCO-08), a family, and a match value: exact, phrase, or prefix.

Title resolution shares the deterministic ingestion matchers. Seniority and common title variations are normalized; prefixes remain available for browsing. The result is a candidate list, not a natural-language search plan. Occupational codes can be shared by multiple curated occupations, so a code need not yield exactly one item.

findOccupations, at /v1/occupations, returns just the classification candidates in items, without live counts or database access. It accepts titles, names, slugs and SOC/ISCO code prefixes. Use a candidate's family.slug for JobQuery.families when a broad field is intended. Occupation slugs and codes are not role filters, even where their spelling happens to match a role slug.

Skills and fixed filter values

listSkills (MCP list_skills) matches leading prefixes of canonical names, slugs and aliases. Exact matches come first: golang resolves to go, c++ to cpp, and c# to csharp. Results contain slug, name and kind; duplicate aliases never duplicate a skill. Use canonical slugs in skills (match any) or skillsAll (match all). For example, { "skillsAll": ["react", "typescript"] } finds postings mentioning both technologies, including preferred skills. Jobs without detected skills do not match. Unknown or unseeded ALL terms match nothing.

getSearchOptions (MCP get_search_options) returns bundled families and filters. The latter exposes the actual allowed values for seniority, employment, workplace, posted, sort, pay, reposts, agencies and salary currency. Enum names match JobQuery except that currency belongs at salary.currency. Posting languages accept ISO 639-1 codes rather than a fixed enum.

For families alone, MCP list_job_families returns static names, slugs and descriptions, optionally filtered by text. Existing list_families and GET /v1/families include live counts instead.

Limits, empty results and caching

• Place, role, occupation and skill searches return at most 20 items; default 8. Text inputs are trimmed and limited to 1–100 characters. Family browsing returns the small full family list.
• Unknown terms return empty arrays. Empty/overlong inputs and invalid limits return an actionable HTTP 400 or MCP tool error.
• Places, occupations, skills and /v1/taxonomy have a one-day CDN cache TTL (browser max-age five minutes). They change when the bundled data is updated. They require no database access.
• Role/family responses with live counts keep their shorter existing cache policy. Do not treat counts as immutable taxonomy metadata.
• The existing public rate limits apply. MCP uses the same data functions and response schemas as the HTTP API.