Files
jobboard/plugins/readers/smartrecruiters.py
T

167 lines
7.0 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 "")
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)}