Files
jobboard/plugins/readers/smartrecruiters.py
T
WolfandClaude Opus 5.5 c497fe965d Keep a description's headings, bullets and paragraphs, and draw them in the reader
The readers flattened a posting's HTML into one line with strip_html, so
sections and bullets ran together. _shared.html_text gives a line per
paragraph, '• ' before a list item and '## ' before a heading; every
reader's description goes through it, sections read per role get their
own headings, and the reader pane draws the lines as h3, ul and p.
Excerpts leave the marks out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 21:40:12 +02:00

169 lines
7.1 KiB
Python

"""SmartRecruiters: `smartrecruiters:<company identifier>`, paged by offset
with a stated total. The identifier is case-sensitive (`BoschGroup`).
Written from one real board on 2026-09-23; jobhunt-hq did not read
SmartRecruiters.
A country is filtered on the server, `?country=dk`, one a request
(`Filters(country="one")`): Bosch's DE, SE and DK summed to what the app held
(review, 2026-09-29), and DK answered 2 of 4,830 on 2026-09-30. The API
ignores a remote parameter, so remote is not filtered.
A fetch term goes as `?q=engineer`, one a request (`Filters(query="one")`):
it matches title and text, and with `country=` it is an AND (survey,
2026-09-30: `q=engineer` answered 1,713 of Bosch's 4,830, with `country=dk`
none). How several words in one `q` combine is untested.
The list has no text. The text is read per posting by `detail`, `GET
/v1/companies/{slug}/postings/{id}` (checked 2026-09-30, Delivery Hero's
744000151349134): `jobAd.sections` holds `companyDescription`,
`jobDescription`, `qualifications` and `additionalInformation`, each with a
`title` and its `text` as HTML. The description joins the last three; the
company blurb is the same on every role of the board and is left out.
"""
from __future__ import annotations
import json
import re
from collections.abc import Callable
from typing import Any
from urllib.parse import quote
from ._contract import Ask, Fields, Filters, Place, Reads
from ._shared import Get, HEADING, Page, Row, html_text, only, parse_dt, path_slug_ok
NAME = "smartrecruiters"
LABEL = "SmartRecruiters"
RANK = 50
PATTERNS = (
r"(?:jobs|careers|api)\.smartrecruiters\.com/(?:v1/companies/)?([A-Za-z0-9_-]+)",
)
#: An unknown identifier answers an empty list, which is `empty="suspect"`.
READS = Reads(
scope="board", listing="paged", page_size=100, text="detail", complete="stated",
places="one", empty="suspect", filters=Filters(country="one", query="one"),
fields=Fields(posted="trusted", remote="stated", country="stated", seniority="stated",
employment="stated"),
robots=("read though api.smartrecruiters.com's robots.txt disallows / for every agent "
"but LinkedInBot, which alone is allowed /v1/companies/, the path of the listing "
"and of each posting: owner to decide, checked 2026-09-30"),
)
_API = "api.smartrecruiters.com"
#: The page size asked for, which is also the most the host serves per page.
PAGE_SIZE = 100
def slug_ok(slug: str) -> bool:
return path_slug_ok(slug)
def allowed(slug: str) -> Callable[[str], bool]:
return only(_API)
def careers_url(slug: str) -> str:
return f"https://jobs.smartrecruiters.com/{slug}"
def probe_url(slug: str) -> str:
return f"https://{_API}/v1/companies/{slug}/postings?limit=1"
def probe_ok(body: bytes) -> bool:
"""An unknown identifier answers an empty listing, so a listing without
postings counts as no board."""
return b'"totalFound":' in body and b'"totalFound":0' not in body
def page(get: Get, slug: str, cursor: Any, ask: Ask = Ask()) -> Page:
"""One page, in the one country `ask` names, which the API takes in lower
case, and matching its `query` (`q=`)."""
offset = int(cursor or 0)
country = ask.countries[0].lower() if ask.countries else ""
where = f"&country={country}" if re.fullmatch(r"[a-z]{2}", country) else ""
words = f"&q={quote(ask.query, safe='')}" if ask.query else ""
data = json.loads(get(f"https://{_API}/v1/companies/{slug}/postings"
f"?offset={offset}&limit={PAGE_SIZE}{where}{words}"))
content = data.get("content") or []
return data, content, data.get("totalFound"), offset + len(content) if content else None
def parse(body: bytes, slug: str) -> list[Row]:
return rows(json.loads(body), slug)
def _word(job: dict[str, Any], key: str) -> str | None:
"""The `id` of the object `job[key]`, as given."""
return str((job.get(key) or {}).get("id") or "").strip() or None
def rows(data: dict[str, Any], slug: str) -> list[Row]:
"""One page of https://api.smartrecruiters.com/v1/companies/{slug}/postings
-> `{"offset", "limit", "totalFound", "content": [...]}`. At most 100 a
page, whatever `limit` asks for; the next is `?offset=` further on. The
list omits the job description (only the per-posting endpoint has it,
which `detail` reads for the roles worth it), so `description` stays
empty here. A posting has one location,
its `country` a lower-case ISO code, `experienceLevel` and
`typeOfEmployment` (an `id` and a `label` each)."""
out = []
for j in data.get("content") or []:
title = (j.get("name") or "").strip()
job_id = str(j.get("id") or "")
if not title or not job_id:
continue
location = j.get("location") or {}
loc_text = (location.get("fullLocation")
or ", ".join(p for p in (location.get("city"), location.get("country")) if p))
# `fullLocation` writes an empty region as ", ,": "Hatvan, , Hungary".
loc_text = ", ".join(part.strip() for part in (loc_text or "").split(",")
if part.strip())
place: Place = {"text": loc_text, "remote": location.get("remote")}
out.append({
"source_id": job_id,
"title": title,
"places": [place] if loc_text else [],
"location": loc_text,
"url": f"https://jobs.smartrecruiters.com/{slug}/{job_id}",
"posted": parse_dt(j.get("releasedDate")),
"department": ((j.get("department") or {}).get("label") or "").strip(),
"description": "",
"remote": location.get("remote"),
"salary_text": "", # SmartRecruiters' list endpoint states no pay at all
"country": str(location.get("country") or "").strip() or None,
"seniority": _word(j, "experienceLevel"),
"employment": _word(j, "typeOfEmployment"),
})
return out
#: The sections of a posting's ad that make its description, in reading order.
#: `companyDescription` is the employer's blurb, alike on every role.
_SECTIONS = ("jobDescription", "qualifications", "additionalInformation")
def detail(get: Get, slug: str, row: Row) -> dict[str, Any]:
"""`/v1/companies/{slug}/postings/{id}` -> `jobAd.sections`: the HTML of
`jobDescription`, `qualifications` and `additionalInformation`, one
text. An answer without `jobAd.sections` is
not a posting and raises, so the role is asked again on a later pull."""
posting = quote(str(row["source_id"]), safe="")
data = json.loads(get(f"https://{_API}/v1/companies/{slug}/postings/{posting}"))
sections = ((data.get("jobAd") or {}).get("sections")
if isinstance(data, dict) else None)
if not isinstance(sections, dict):
raise ValueError("not a SmartRecruiters posting: no jobAd.sections")
parts = []
for key in _SECTIONS:
section = sections.get(key) or {}
if text := html_text(section.get("text")):
if title := " ".join(str(section.get("title") or "").split()):
parts.append(HEADING + title)
parts.append(text)
return {"description": "\n".join(parts)}