"""Adzuna: an aggregator with a documented API for most of Europe, the UK and the US, but not Denmark (adzuna.dk does not exist). Needs a free key from developer.adzuna.com, as `sources.search.adzuna: {app_id, app_key}` or `ADZUNA_APP_ID` and `ADZUNA_APP_KEY`; the runner resolves it and passes it as `ask.params["key"]`. Built against Adzuna's documented response and not yet run live. One request is `/v1/api/jobs//search/` with `what`, `where`, `sort_by=date` and 50 results a page; the answer is `{"count", "results": [...]}` and the search is complete when as many distinct results were read as `count` states. Titles and snippets carry `` highlights. The description is a snippet of the ad, so it is the `teaser`. A salary Adzuna estimated (`salary_is_predicted`) is not the posting's, so it is dropped. """ from __future__ import annotations import html import json from collections.abc import Callable from typing import Any from urllib.parse import urlencode from desk.sources import strip_html from ._contract import Ask, Fields, Filters, Key, Place, Reads from ._words import remote_word from ._shared import Get, Page, Row, is_web_url, only, parse_dt NAME = "adzuna" LABEL = "Adzuna" RANK = 20 READS = Reads( scope="search", listing="paged", page_size=50, text="excerpt", complete="stated", filters=Filters(query="one", country="one", place="one"), places="one", fields=Fields(pay="figures", posted="trusted", country="stated"), key=Key(name="adzuna", fields=("app_id", "app_key"), env=("ADZUNA_APP_ID", "ADZUNA_APP_KEY")), robots="robots.txt disallows / for every agent (checked 2026-09-30); the documented " "API is read with the account's key, decision of the owner pending") #: Saved param -> the filter dimension it fills. PARAMS = {"q": "query", "country": "country", "where": "place"} SEARCH = "https://api.adzuna.com/v1/api/jobs/{country}/search/{page}" #: Adzuna's countries in Europe, and the currency its salaries are in. COUNTRIES = {"gb": "GBP", "de": "EUR", "nl": "EUR", "fr": "EUR", "at": "EUR", "be": "EUR", "es": "EUR", "it": "EUR", "pl": "PLN", "ch": "CHF"} def allowed(slug: str) -> Callable[[str], bool]: return only("api.adzuna.com") def clean_params(params: dict[str, Any]) -> dict[str, Any]: """The saved params of a search: `q`, `country` (one of `COUNTRIES`) and `where` when given.""" country = str(params.get("country") or "").strip().lower() if country not in COUNTRIES: raise ValueError(f"country is one of {', '.join(sorted(COUNTRIES))}") out: dict[str, Any] = {"q": params["q"], "country": country} if str(params.get("where") or "").strip(): out["where"] = str(params["where"]).strip() return out def _text(fragment: str) -> str: return html.unescape(strip_html(fragment)).strip() def _country(ask: Ask) -> str: country = (ask.countries[0] if ask.countries else str(ask.params.get("country") or "")) country = country.lower() if country and country not in COUNTRIES: raise ValueError(f"adzuna country {country!r} is not one of " f"{', '.join(sorted(COUNTRIES))}") return country def page(get: Get, slug: str, cursor: Any, ask: Ask) -> Page: """One page of a search, newest first; the cursor is the page number. The next page follows a full page. A missing key or country is not refused here: the runner resolves the key (`READS.key`) and refuses a search without one, `clean_params` refuses a search without a country, and Adzuna answers 401 or 404 to a request that lacks either.""" key = ask.params.get("key") or {} country = _country(ask) number = int(cursor or 1) query: dict[str, Any] = {"app_id": key.get("app_id", ""), "app_key": key.get("app_key", ""), "results_per_page": READS.page_size, "sort_by": "date", "what": ask.query or str(ask.params.get("q") or "")} where = ask.places[0] if ask.places else ask.params.get("where") if where: query["where"] = where url = SEARCH.format(country=country, page=number) + "?" + urlencode(query) data = json.loads(get(url)) results = [job for job in data.get("results") or [] if isinstance(job, dict)] count = data.get("count") decoded = {"country": country, "results": results} more = len(results) >= (READS.page_size or 50) return (decoded, [{"id": str(job.get("id") or "")} for job in results], count if isinstance(count, int) else None, number + 1 if more else None) def rows(decoded: Any, slug: str) -> list[Row]: country = decoded["country"] out: list[Row] = [] for job in decoded["results"]: title = _text(job.get("title") or "") url = (job.get("redirect_url") or "").strip() if not title or not is_web_url(url): continue predicted = str(job.get("salary_is_predicted") or "0") == "1" town = ((job.get("location") or {}).get("display_name") or "").strip() places: list[Place] = [{"text": town, "remote": None}] if town else [] out.append({ "source_id": str(job.get("id") or ""), "title": title, "company": ((job.get("company") or {}).get("display_name") or "").strip(), "url": url, "places": places, "location": town, "country": country.upper(), "remote": remote_word(title), "posted": parse_dt(job.get("created")), "teaser": _text(job.get("description") or ""), "salary_min": None if predicted else job.get("salary_min"), "salary_max": None if predicted else job.get("salary_max"), "currency": None if predicted else COUNTRIES.get(country), }) return out