Nectar Jobs

Search 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 postin

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

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

Find 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").

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

Fetch a single job's full details, including its description and any duplicate postings of the same role on other sources.

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

Takes no parameters.