aggregate_jobs
ClaudeAggregate counts for a filtered slice of the corpus — the tool for market/trend questions ("what kinds of roles are hiring in Pune?"), instead of issuing many limit-1 searches. Takes the same filters as search_jobs (keyword matching included, see its `query note) and returns the slice's total plus breakdowns, each a {value: count} dict, biggest first: by_category (job function — the role-type axis), by_seniority, by_employment_type (contract basis and hours in one axis; full_time is inflated because a posting silent about its hours is recorded as full-time), top_companies, top_skills, by_source, benefits, company_size, lang, and salary` — per-currency posting counts with salary_max quartiles (currencies deliberately not blended). Every count collapses duplicate postings, so numbers are comparable to search totals.
find_similar_jobs
ClaudeFind jobs semantically similar to a given job (excludes its duplicates). At most `max_per_company results per company (0 = uncapped), so one employer's near-identical postings don't fill the list; exclude_same_company` drops the anchor's own company entirely ("roles like this elsewhere").
get_job
ClaudeFetch a single job's full details, including its description and any duplicate postings of the same role on other sources.
get_stats
ClaudeReturn corpus-wide coverage: total jobs, counts by source, and top companies. For the same numbers on a filtered slice (a location, a company, a query), use aggregate_jobs.
job_trends
ClaudeHow a slice of the market has changed OVER TIME — use this for "is X growing/shrinking", "hiring trend", "more or fewer than last year". aggregate_jobs describes a slice as it stands today; this one shows its history. Takes the same filters as aggregate_jobs, plus `bucket ("day"/"week"/"month"), since_days (at most 730), and measure. Returns a series, oldest first, each period carrying postings (roles dated to it, duplicates collapsed) and still_open (how many are live now — the rest have since closed). measure="posted" (default) uses the employer's stated date: the market signal, but nullable, so check without_date — it counts roles the clock cannot place, and when it rivals the series totals the trend describes a minority of the slice. measure="first_seen" uses when we first crawled the row. Complete, but it measures OUR coverage: a backfill or a newly onboarded board appears as a spike of hundreds of thousands that is not a hiring event. Use it to audit ingestion, not to infer demand. Either way, periods before earliest are empty because we hold no data that far back, not because hiring stopped — never report that as a decline. CRITICAL for "posted": only compare periods at or after crawl_started. Earlier ones are left-censored — the first crawl could only capture roles still live when it ran, so anything posted before that and already closed was never seen. Those buckets undercount severely (their still_open` sits near 100%, the giveaway), and reading across the boundary turns the crawler's start date into a fake hiring boom.
recommend_jobs
ClaudeRank jobs by how well they match a résumé or free-text description of what the candidate wants. Returns the best-matching jobs first. `country (ISO-2, e.g. GB) or location (a city or region) is REQUIRED — ask the seeker where they can work rather than guessing. Semantic ranking over every country returns the nearest postings on earth, most of which the person cannot take. Ranking is purely semantic; the filters are hard. seniority` (intern, junior, senior, staff, principal, manager, director) filters to exactly that tag — many postings carry none, so only pass it when the seeker insists.
search_jobs
ClaudeSearch live job postings: use when the user asks what jobs are open for a role, a place, a salary or a skill. Each job carries `url (its page on Nectar Jobs) and apply_url. Args: query: keyword or natural-language query. Words that name an occupation ("manager", "software engineer") are matched against the TITLE; other words match the whole document (title, company, description), so a generic word's total overcounts — to compare role-type volumes, use aggregate_jobs instead. location: city or country substring over the posting's location text (matches broadly: "New York" includes the whole state). For a whole country, prefer country. remote: filter to remote (true) or on-site (false) roles. salary_min: only roles whose salary range reaches this amount (raw number — currencies are not converted, so only meaningful combined with a single-currency market). company: company name substring. source: restrict to one source/board; get_stats lists the live sources and their sizes. seniority: one of intern, junior, senior, staff, principal, manager, director. category: job function from the site taxonomy (Engineering, "Data & ML", Product, Design, Sales, Marketing, "Customer Support", Operations, "Finance & Accounting", "People & HR", Legal, "IT & Security", …) — aggregate_jobs reports the live values. country: 2-letter ISO code ("US", "IN") — matches the derived country, more precise than a location substring. employment_type: contract or hours — permanent, fixed_term, contract, freelance, temporary, casual, seasonal, internship, apprenticeship, graduate, working_student, volunteer, self_employed, full_time, part_time, job_share, shift, term_time. Contract basis and schedule are one filter; a posting carries one of each. Note that a posting which says nothing about its hours is recorded as full_time, so that value is the least informative of the set. posted_since_days: only jobs posted within this many days. mode: "hybrid" (default, best), "semantic" (meaning-based), or "keyword" (exact). sort: "relevance" (default), "date" (newest first), or "salary" (highest first). page: 1-based page number, for paging past limit results. limit: max results per page (1-100). Returns a dict with total, a jobs list (duplicates collapsed) and attribution; when nothing matched, a hint` names the filter most worth loosening.