Files
jobboard/plugins/README.md
T

445 lines
37 KiB
Markdown

# Where roles come from
This file lists every source roledesk reads roles from, how each is read and what it cannot deliver. The contract for writing a reader (a host module or a search provider) is `documentation/ADR Plugins.md`, the owner's draft, and in code the docstring of `plugins/readers/__init__.py`, with its types and the declaration check in `plugins/readers/_contract.py` and the conformance test in `tests/test_readers_contract.py`, not this file.
The code has two plugins: `ats` (`plugins/ats.py`) reads the board of a company someone listed, with one module per host in `plugins/readers/`; `search` (`plugins/search.py`) runs saved queries on sites that list roles across companies. Below, a module of `ats` is a "host" and a module of `search` is a "provider". A company's list of roles on a host is its "board"; a board is attached as a target `host:slug`, e.g. `workday:lego.wd103/LEGO_External`.
What a reader does is declared in its `READS` (`plugins/readers/_contract.py`) and listed per reader on the Sources page. The sections below keep what a declaration cannot say: endpoints, quirks, examples and limits. The shared limits are constants in `plugins/readers/_runner.py` (`MAX_BYTES`, `TIMEOUTS`, `DEADLINE`, `MAX_PAGES`, `PAGE_DELAY`, `DETAIL_CAP`, `SUSPECT_SHARE`, `MAX_SERIES`), `app/jobs/pull.py` (`BATCH_SIZE`, `STALE_DAYS`), `app/jobs/reach.py` (`SMALL`) and the `fetch_text:` block of the config; the ADRs state the ones that bear on a reader.
No reader logs in, runs a page's script or uses a key taken from a site's script. A company that needs one is on the Watchlist tab (`app companies by-hand` lists them), and the readers planned for the rest are in `docs/plan-hosts-wave-2.md`.
## Hosts read as a whole board
### Greenhouse
| | |
|---|---|
| Target | the board token, e.g. `greenhouse:trustpilot` |
| List | `boards-api.greenhouse.io/v1/boards/<token>/jobs` with `content=true` and `pay_transparency=true`, the whole board in one answer; no total |
| Description | in the list, full text (`content`) |
| Date | `first_published`, else `updated_at`, which the host moves on an edit; trusted as the posting date |
| Place and country | every `offices` entry; `location.name` when the role has no office or the name says more, with placeholder names such as "Hybrid" dropped. The host states no country; it is resolved from the places |
| Remote | none from the host; prep reads remote, hybrid or onsite from the place words |
| Pay | figures from `pay_input_ranges` when there is exactly one range; a range whose title says hour or day is a line only; any other range is taken as yearly. Several ranges give one line per range and no figures |
| Found by discovery | yes, from a link to `boards.greenhouse.io`, `job-boards.greenhouse.io` or the embed script; a guessed name is probed first of all hosts |
| Limitations | Over 96 MiB the board is read again without `content=true`: titles land, text and pay of the whole board are lost. It is the only host with a `fallback_url`. An `eu.greenhouse.io` link is read from the main API. The pay flag must be sent, or no range comes back. |
### Lever
| | |
|---|---|
| Target | the site name, or `eu/<site>` on Lever's EU instance, e.g. `lever:spotify`, `lever:eu/tomtom` |
| List | `api.lever.co/v0/postings/<site>?mode=json` (`api.eu.lever.co` for `eu/`), the whole board in one answer; no total, no paging parameter sent |
| Description | in the list, `description` (else `descriptionPlain`); the module reads no `lists` or `additional` sections, so it is the opening text |
| Date | `createdAt`; trusted |
| Place and country | `categories.location` and every `allLocations` entry; the host's `country` is handed on when the role has one place, otherwise the country is resolved from the places |
| Remote | `workplaceType`, the host's own word |
| Employment | `categories.commitment`, the host's own word |
| Pay | figures from `salaryRange` for `per-year-salary` and `per-month-salary` (x12); other intervals a line only |
| Found by discovery | yes, from a `jobs.lever.co` or `api.lever.co` link on either instance; a guessed name is probed on the US instance, then on the EU one |
| Limitations | The same site name on the two instances is two companies. Only the opening text of an ad is read (`docs/open.md`). |
### Ashby
| | |
|---|---|
| Target | the board name, which may carry a dot or be a uuid, e.g. `ashby:pleo`, `ashby:jimdo.com` |
| List | `api.ashbyhq.com/posting-api/job-board/<name>?includeCompensation=true`, the whole board in one answer; no total |
| Description | in the list, full text (`descriptionHtml`) |
| Date | `publishedAt`; trusted |
| Place and country | the primary `location` and every `secondaryLocations` entry; country resolved from the places |
| Remote | `workplaceType` (Remote, Hybrid, OnSite) as the host words, else `isRemote`, which is true for hybrid roles too |
| Employment | `employmentType`, the host's own word |
| Pay | figures from the first `Salary` component with interval `1 YEAR` or `1 MONTH` (x12); an hourly one a line only; bonus and equity appear in the line only; when no component states a bound the line falls back to `compensationTierSummary` or `scrapeableCompensationSalarySummary` |
| Found by discovery | yes, from a `jobs.ashbyhq.com` link; a guessed name is probed |
| Limitations | The pay flag must be sent, or no compensation comes back. An unknown board name answers an empty board, so a board with no open roles looks like no board to discovery. `READS.empty="suspect"` keeps a known board from closing its roles on such an answer; a mistyped name attached as a new board still reads as an empty, complete board (`docs/open.md`). |
### Recruitee
| | |
|---|---|
| Target | the subdomain, e.g. `recruitee:bunq` |
| List | `https://<sub>.recruitee.com/api/offers/`, the whole board in one answer; no total |
| Description | in the list, `description` only (`requirements` is not read) |
| Date | `published_at`, else `created_at`; trusted |
| Place and country | every `locations` entry as "city, state, country"; `location` or `city` when there are none; a remote offer with no place gets the place "Remote" |
| Remote | `remote`, true or false |
| Seniority, employment | `experience_code` and `employment_type_code`, the host's own words |
| Pay | figures from `salary` for period `year` and `month` (x12); other periods a line only |
| Found by discovery | yes, from a `<sub>.recruitee.com` link; a guessed name is probed |
| Limitations | A board with no offers answers an empty list and looks like no board to discovery. A board on the company's own domain is not read (planned in wave 2, Quantum Systems). |
### Personio
| | |
|---|---|
| Target | the subdomain, e.g. `personio:penneo` |
| List | the XML feed `https://<sub>.jobs.personio.de/xml`, the whole board in one answer; no total |
| Description | in the list, every `jobDescription` value joined |
| Date | `createdAt`; trusted |
| Place and country | `office` and every `additionalOffices` office; the feed has no country field, so it is resolved from the places |
| Remote | none for the role; a place whose text contains "remote" is a remote place, and prep makes the role remote if any place is |
| Seniority, employment | the host's `seniority` and its contract (or `schedule`) words |
| Pay | figures from `salaryInformation` for `yearly` and `monthly` (x12); hourly, daily, weekly a line only; rare |
| Found by discovery | yes, from a `jobs.personio.de` or `jobs.personio.com` link; a guessed name is probed |
| Limitations | The feed has no role link; it is built as `/job/<id>`. Only the feed's default language is read. The company Personio itself is on the Watchlist as `blocked`. |
### Pinpoint
| | |
|---|---|
| Target | the subdomain, e.g. `pinpoint:xeneta` |
| List | `https://<sub>.pinpointhq.com/postings.json`, the whole board in one answer; no total, no paging keys |
| Description | in the list, full text: description, responsibilities, skills and benefits sections |
| Date | none: the list states none and the role page is not read for it; the role counts as posted when first seen |
| Place and country | `location.name` (else `city`) plus `province`, one place; country resolved from that line |
| Remote | `workplace_type`: onsite, hybrid, remote |
| Employment | `employment_type`, the host's own word |
| Pay | figures when `compensation_visible`, for annual and monthly (x12) frequencies; others a line only. The frequency spellings are guessed, since no board read so far shows pay |
| Found by discovery | yes, from a `<sub>.pinpointhq.com` link; not probed |
| Limitations | Written from Xeneta's board, two roles. Whether a large board pages `/postings.json` is unverified. A board shared by several brands (inMusic with Native Instruments) is read whole, with no filter on division. |
### Deel
| | |
|---|---|
| Target | the board slug on `jobs.deel.com`, with case, e.g. `deel:klarna` |
| List | the HTML page `https://jobs.deel.com/<slug>`, from which the Next.js server payload is read; the whole board in one answer; no total |
| Description | in the list, full text (`richtextDescription`) |
| Date | the publication's `createdAt`, else the posting's; not trusted, so the role counts as posted when first seen |
| Place and country | every `jobLocations` name as a place, repeated names dropped, each carrying the role's remote flag; country resolved from the places |
| Remote | `workArrangementEnum`: ON_SITE, HYBRID, REMOTE |
| Employment | the first `jobEmploymentTypes` name |
| Pay | line only, when visible: currency and two amounts with no period, so no yearly figure can be told from a monthly one |
| Found by discovery | yes, from a `jobs.deel.com` link, case kept; not probed |
| Limitations | Deel's `/api/` is disallowed by robots.txt, so the board is read out of the page's React payload, which a Next.js release can change. Written from Klarna's board only. A wrongly cased slug answers `Job Board Not Found` and fails the board. |
### HiBob
| | |
|---|---|
| Target | the subdomain of `careers.hibob.com`, e.g. `hibob:dixa` |
| List | `https://<sub>.careers.hibob.com/api/job-ad` with the header `companyIdentifier: <sub>`, the whole board in one answer; no total. Declared as paged with `complete="end"` because `page` may send headers; it reads one page |
| Description | in the list, full text: description, responsibilities, requirements, benefits |
| Date | `publishedAt`; not trusted, so the role counts as posted when first seen |
| Place and country | `site` plus `country`. A company that hires at two sites posts one ad per site with its own id (`places="copies"`); `app/dupes.py` folds them into one role |
| Remote | `workspaceTypeId`: remote, hybrid, onsite |
| Employment | `employmentType`, the host's own word |
| Pay | figures from the `payTransparency*` fields for year and month (x12); hour, day and week a line only. No board seen had them filled, so the period spellings are guessed |
| Found by discovery | yes, from a `<sub>.careers.hibob.com` link; not probed |
| Limitations | Written from two boards (Dixa, Liquidia). The header is the public subdomain, not a key; without it the API answers 401. |
## Hosts read in pages
### Teamtailor
| | |
|---|---|
| Target | the subdomain of `teamtailor.com`, or the whole host of a career site on the company's domain, e.g. `teamtailor:lunar`, `teamtailor:careers.trackunit.com` |
| List | the RSS feed `https://<site>/jobs.rss`, 50 per request by offset; no total, so the read goes on to an empty page |
| Description | in the list, full text |
| Date | `pubDate`; trusted |
| Place and country | every `tt:location` as a place "city, country", each remote when `remoteStatus` says so; country resolved from the places |
| Remote | `remoteStatus`, handed on as the host's word: fully is remote, hybrid, onsite; `none` and `temporary` stay unknown |
| Pay | none: the feed states no pay |
| Found by discovery | yes, from a `<sub>.teamtailor.com` link; a page that loads Teamtailor's CDN names the page's own host as the board; a guessed name is probed |
| Limitations | A board of more than 100 pages is swept across pulls and completes on the empty page. A page with nothing new ends the read incomplete. Nine seed companies have no board because their careers link is a marketing site, not the career host. A company has one board, so DFDS, which has a Teamtailor site per country, is read from its Danish one only. |
### Jibe
| | |
|---|---|
| Target | the career site's host, e.g. `jibe:jobs.booking.com` |
| List | `https://<host>/api/jobs?limit=100&page=<n>`, 100 per request, the most the host serves; states `totalCount` |
| Description | in the list, full text: description and qualifications |
| Date | `posted_date`; not trusted, so the role counts as posted when first seen |
| Place and country | `full_location` split at ";" into places; the host's `country_code` is handed on when the role has one place |
| Remote | none (`location_type` is a kind of coordinates) |
| Employment | `employment_type`, the host's own word |
| Pay | none: the `salary_*` fields were 0 on every role and carry no currency |
| Found by discovery | no slug: a link to Jibe's CDN names the host only; the target is set by hand |
| Limitations | Only Booking.com's site was read. No brand filter: the Booking Holdings roles are read with the Booking.com ones. The site's robots.txt asks for `Crawl-delay: 5`, which is not honoured. |
### HR Manager
| | |
|---|---|
| Target | the portal's customer name, e.g. `hrmanager:teknologisk` |
| List | the RSS feed `api.hr-manager.net/JobPortal.svc/<customer>/PositionList/rss/?incads=true`, 100 per request by `skip`; no total, so the read goes on to an empty page |
| Description | in the list, the whole advertisement |
| Date | `pubDate`; not trusted |
| Place and country | none: the feed names no place |
| Remote | none |
| Pay | none |
| Found by discovery | yes, from a portal or API link; not probed |
| Limitations | The portal's robots.txt on `candidate.hr-manager.net` disallows everything but the application form; the feed's API host has no robots.txt. `READS.robots` says "owner to decide", and the board of the Danish Technological Institute is attached all the same (`docs/open.md`). Without `take` the host answers 25 roles. |
## Hosts read as list, then each role
For every host below the pull reads the list only; the description arrives when fetch text reads the role's page (`documentation/ADR Plugins.md`, 2.2). "Places" are a list of the places the host states; only the `location` line joins them.
### SmartRecruiters
| | |
|---|---|
| Target | the company identifier, e.g. `smartrecruiters:BoschGroup` |
| List | `api.smartrecruiters.com/v1/companies/<id>/postings`, 100 per request by offset; states `totalFound` |
| Description | per role, `GET /v1/companies/<id>/postings/<id>`: the `jobAd.sections` `jobDescription`, `qualifications` and `additionalInformation`, joined; `companyDescription` is the same blurb on every role and is left out. Read by fetch text for the roles in the cut only |
| Date | `releasedDate`; trusted |
| Place and country | `fullLocation`, else city and country, with empty parts removed; the host's `country` is handed on |
| Remote | `location.remote`, true or false, as the host's word |
| Seniority, employment | `experienceLevel` and `typeOfEmployment`, the host's ids |
| Pay | none: the list states no pay |
| Found by discovery | yes, from a `jobs.`, `careers.` or `api.smartrecruiters.com` link; a guessed name is probed |
| Filter at the source | `?country=dk`, one country a request; remote is ignored by the API, so it cannot be asked for. Fetch terms as `?q=engineer`, one a request, AND with the country; it matches title and text |
| Limitations | 100 pages a pull; a larger board is swept across pulls. The identifier is stored with the case it was attached with; whether the host is case-sensitive is unsettled (`docs/open.md`). An unknown identifier answers an empty list, not an error: `READS.empty="suspect"` keeps a known board from closing its roles on it, but a mistyped slug attached as a new board reads as an empty, complete board. |
The reader's Fetch button reads one posting page on demand (see "The search providers"); whether it reads a SmartRecruiters page cleanly was not checked.
### Workable
| | |
|---|---|
| Target | the account name, e.g. `workable:huggingface` |
| List | a POST to `apply.workable.com/api/v3/accounts/<account>/jobs`, 10 per request with a `nextPage` token; states `total` |
| Description | per role, `GET /api/v2/accounts/<account>/jobs/<shortcode>`: `description`, `requirements` and `benefits`, joined. The row keeps the `shortcode`, since `source_id` is the numeric id. Read by fetch text for the roles in the cut only |
| Date | `published`; trusted |
| Place and country | every `locations` entry as "city, region, country", each remote when the role is; `location` when there are none |
| Remote | `workplace` (remote, hybrid, on_site) as the host's word, else the `remote` flag |
| Employment | `type`, the host's own word |
| Pay | none: the list states no pay |
| Found by discovery | yes, from an `apply.workable.com` or `<account>.workable.com` link; not probed, since a run of guesses trips Workable's rate limit |
| Limitations | 100 pages of 10 a pull; a larger board is swept across pulls. Workable answers bursts with 429, which is why pages and role reads are 0.5 s apart; a 429 after the first page ends the read incomplete. The role link is built from the shortcode. |
### SuccessFactors
| | |
|---|---|
| Target | the career site's host, or host plus a brand path, e.g. `successfactors:careers.vestas.com`, `successfactors:jobs.teradyne.com/MiR` |
| List | the site's HTML search page `/search/?startrow=<n>`, parsed in its two known layouts; page size is the site's own (10, 15, 25 or 100) and cannot be set; a total where the pagination label states one |
| Description | per role, the `itemprop="description"` block of the role page |
| Date | the list's date column where it parses; the role page's `datePosted` replaces it when earlier; trusted |
| Place and country | the list's location, with a two-letter country code turned into the name; the role page's microdata replaces it |
| Remote | none from the host |
| Pay | none |
| Found by discovery | yes, from a link to a role, `/go/` page or search on the site's own host; a link to the SAP back end names the host only; not probed. A site on the company's own domain whose pages link only the back end is set by hand |
| Filter at the source | `optionsFacetsDD_country=DK`, one country a request; no remote facet. Fetch terms as the form's `q=engineer`, one a request, AND with the country; whether it matches title or text is not determined (`docs/filter-survey.md`) |
| Limitations | Only the default locale's roles are listed: a role that exists only in another locale (Carlsberg's French brand, 37 of 105) is not read. Only `/search/` and `/job/` are read, never `/services/` or the `successfactors.eu` back end, so a company with only the back end (Bang & Olufsen) cannot be read. 100 pages a pull; a larger site is swept across pulls. A third layout or a bot wall that answers 200 fails the board with "not a SuccessFactors search page". Read from this machine only; not yet from the deployed server. |
### Workday
| | |
|---|---|
| Target | `<tenant>.<wdN>/<Site>`, site with case, e.g. `workday:lego.wd103/LEGO_External` |
| List | a POST to `/wday/cxs/<tenant>/<Site>/jobs`, 20 per request by offset (21 or more answers 400); the first page states the total |
| Description | per role, `jobDescription` from the role's JSON |
| Date | the list's "Posted N Days Ago" as a day, possibly one day off; "Posted 30+ Days Ago" and other languages give none; the role's `startDate` replaces it; trusted |
| Place and country | the list has `locationsText` ("Copenhagen" or "2 Locations"); the per-role read adds every location and the country, so the country arrives with the role page |
| Remote | `remoteType`, where the tenant sends it, as the tenant's own word ("Remote", "Hybrid", "Full Remote", "No"); prep maps it |
| Employment | `timeType`, the host's own word |
| Pay | none: no pay field; pay appears only inside the text |
| Found by discovery | yes, from a `myworkdayjobs.com` link with a site; not probed |
| Filter at the source | the tenant's own facets in `appliedFacets`, ids read by `facets` once a day: the facet whose values are countries, and any value that reads as remote. Two facets intersect, so remote is a series of its own. A tenant with no country facet is read whole. Fetch terms as `searchText` in the body, one a request, AND with the facets; whether it matches title or text is not determined (`docs/filter-survey.md`) |
| Limitations | 2,000 roles per board (100 pages of 20), the `ceiling`. A tenant has several sites and each is its own board. Every tenant is behind Cloudflare and was read from this machine only. The slug's case is kept (`KEEP_CASE`). |
### Oracle Recruiting Cloud
| | |
|---|---|
| Target | `<pod host>/<siteNumber>`, e.g. `oracle:fa-evmr-saasfaprod1.fa.ocs.oraclecloud.com/CX_1` |
| List | the REST resource `recruitingCEJobRequisitions`, 200 per request by offset, with secondary places expanded; states `TotalJobsCount` |
| Description | per role: external description, responsibilities and qualifications joined. The list's one-paragraph `ShortDescriptionStr` is stored as the teaser (`READS.teaser=True`), which is shown and embedded until the description arrives |
| Date | `PostedDate`; the role's `ExternalPostedStartDate` replaces it when earlier; trusted |
| Place and country | the primary place plus every secondary one, each a place of the role |
| Remote | `WorkplaceTypeCode` as the host's word (e.g. `ORA_HYBRID`); prep maps it |
| Pay | none: the resource states no pay |
| Found by discovery | yes, from a candidate site or role link on the pod, or a REST call naming `siteNumber`; not probed |
| Filter at the source | `selectedLocationsFacet` with the pod's geography ids, and `selectedWorkplaceTypesFacet=ORA_REMOTE` as a series of its own. `locationsFacet` lists the ten biggest countries only, so a country missing from a full list is read unfiltered. Fetch terms as `keyword=` in the finder, one a request; it matches the text |
| Limitations | The host is the tenant's Fusion pod, not the company's domain (`jobs.nokia.com` redirects to it). Links are built for locale `en`. The department fields were empty on every role of the first four boards; Pioneer's were not checked. |
### Phenom
| | |
|---|---|
| Target | the career site's host plus its locale root, e.g. `phenom:www.careers.philips.com/global/en` |
| List | a POST to `https://<host>/widgets`, 100 per request by offset; states `totalHits` |
| Description | per role, the JSON-LD `JobPosting` description of the role page. The list's `descriptionTeaser` is stored as the teaser (`READS.teaser=True`) |
| Date | the list's `dateCreated`, else `postedDate`, which the site moves on a refresh; the role page's `datePosted` replaces it when earlier; trusted |
| Place and country | every place of `multi_location`, each a place of the role |
| Remote | per role only, from the page's `checkRemote` |
| Pay | none |
| Found by discovery | yes, from a `/<country>/<lang>/search-results` link; a link to Phenom itself names the host only; not probed |
| Filter at the source | `selected_fields.country`, a list of English names in one request; no remote. Fetch terms as `keywords` in the body, one a request, AND with the countries; it matches the text, not the title |
| Limitations | The locale is built as `<lang>_<country>`, the spelling of the three sites first read; another site may spell it differently. 100 pages a pull; a larger board is swept across pulls. A role page without a description fails the read and is retried on a later run. |
### Eightfold
| | |
|---|---|
| Target | `<tenant host>/<company domain>`, e.g. `eightfold:jobs.ericsson.com/ericsson.com` |
| List | `https://<host>/api/pcsx/search?domain=<domain>&sort_by=timestamp`, newest first, 10 per request whatever `num` asks; states `count` |
| Description | per role, `jobDescription` from `position_details` |
| Date | `creationTs`, else `postedTs`, which the host refreshes in bulk; not trusted, so the role counts as posted when first seen |
| Place and country | every location, repeated names dropped, each a place of the role |
| Remote | `workLocationOption`: onsite, hybrid, remote |
| Pay | none |
| Found by discovery | yes, from an `eightfold.ai` link that carries `domain=`; a bare `eightfold.ai` link names the host only; not probed |
| Filter at the source | `location=<country name>`, one country a request; no remote. Fetch terms as `query=`, one a request, AND with the location; it matches title, text and skills |
| Limitations | With 10 per request and 100 pages a pull, a board over 1,000 roles is swept across pulls; what the host answers past offset 1,000 was not checked. The country filter brings big boards under the cap. Verified on three tenants only. |
### Gem
| | |
|---|---|
| Target | the board name on `jobs.gem.com`, with case, e.g. `gem:productboard` |
| List | a GraphQL POST to `jobs.gem.com/api/public/graphql`, the whole board in one answer; no total. Declared as paged with `complete="end"`; it reads one page |
| Description | per role, `descriptionHtml`, one GraphQL POST per role |
| Date | per role only, `firstPublishedTsSec`; not trusted, so the role counts as posted when first seen |
| Place and country | every location as a place (the city, else the location name); `isoCountry` is fetched and not used |
| Remote | `locationType`: onsite, hybrid, remote |
| Employment | `employmentType`, the host's own word |
| Pay | none; `compensationHtml` is fetched but was null on every role read |
| Found by discovery | yes, from a `jobs.gem.com` link, case kept; not probed |
| Limitations | The GraphQL queries were read out of the page's script bundle and are undocumented; a new bundle from Gem can rename a field and fail the board. An unknown board answers an empty list, not an error: `READS.empty="suspect"` protects a known board, a mistyped name attached as a new board reads as an empty, complete board. |
### Jobylon
| | |
|---|---|
| Target | the numeric company id, e.g. `jobylon:3143` |
| List | the careers widget's embed page `cdn.jobylon.com/jobs/companies/<id>/embed/v2/`, whose script literal holds the whole board; no total. The list carries a `summary`, stored as the teaser |
| Description | per role, the JSON-LD description of the role page on `emp.jobylon.com` |
| Date | the list's day ("Sept. 25, 2026"); the role page's `datePosted` replaces it when earlier; trusted |
| Place and country | the list's place names, which can be cut short ("Houston +3 more"); the per-role read fills every place |
| Remote | `workspace`: remote, hybrid, onsite |
| Seniority, employment | `experience` and `employment_type`, the host's own words |
| Pay | none; JSON-LD pay is not read |
| Found by discovery | yes, from an `emp.` or `cdn.jobylon.com` link or a `jbl_company_id` on the company's own site; not probed |
| Limitations | Jobylon's own feeds are addressed by a uuid the company holds, so the widget is scraped; a change to its script literal breaks the board. An unknown id answers 404 and fails the board. |
### Rippling
| | |
|---|---|
| Target | the board slug on `ats.rippling.com`, with case, e.g. `rippling:prisma-careers` |
| List | `api.rippling.com/platform/api/ats/v1/board/<slug>/jobs`, the whole board in one array, one entry per role and place, merged by role; no total |
| Description | per role, `description.role`, one role record per role |
| Date | per role only, `createdOn`; trusted |
| Place and country | the list's place labels as places; the per-role read replaces them with every work location |
| Remote | the reader sets no role-level remote; a place whose label starts with "remote" is a remote place, and prep makes the role remote if any place is |
| Employment | `employmentType.label`, the host's own word |
| Pay | figures, per role only, when the record has exactly one pay range with YEAR or MONTH (x12) frequency; no pay line |
| Found by discovery | yes, from an `ats.rippling.com` or API link, case kept; not probed |
| Limitations | Text, date and pay each wait for the role page. Several pay zones give no figures. A wrongly cased slug answers `Job Board not found` and fails the board. |
### BambooHR
| | |
|---|---|
| Target | the subdomain, e.g. `bamboohr:configit` |
| List | `https://<sub>.bamboohr.com/careers/list`, the whole board in one answer; a list shorter than its `totalCount` fails the board rather than being read as whole |
| Description | per role, `/careers/<id>/detail` |
| Date | per role only, `datePosted`; trusted |
| Place and country | the list's city and state as one place; the country arrives with the role page |
| Remote | `isRemote`, else `locationType` 0 onsite, 1 remote, 2 hybrid; the codes are assumed from Configit's board |
| Employment | `employmentStatusLabel`, the host's own word |
| Pay | none; the per-role `compensation` was null |
| Found by discovery | yes, from a `<sub>.bamboohr.com` link; not probed |
| Limitations | Written from one board of two roles. Whether a large board pages `/careers/list` is unverified. |
## The search providers
A saved search is a query with its parameters, stored as a `search` subscription `provider:name`. It reads 5 pages by default and at most 10 (`DEFAULT_PAGES` and `MAX_PAGES` in `plugins/search.py`). A search that finds nothing is not saved. A provider that sends only an excerpt (Jobindex, Adzuna) stores it as the role's `teaser`, and a provider that sends the text (Platsbanken, freehire, Jobnet) stores it as the description; Jobbank states the text only on a role's own page, which fetch text reads. The reader's Fetch button shows for a role with a link, no `article_text` and a description under 500 characters. It reads the posting page once, on demand, into `article_text`, which the reader and `summarise` use and `embed` and `extract` do not (`app/jobs/posting.py`). For a Jobindex role the fetch follows the "Se jobbet" link of Jobindex's page to the posting itself, keeps the link as `roles.posting_url` and falls back to Jobindex's own text; for a Jobbank role it calls the reader's `detail`. A search that fails is recorded as `search:failing:<target>` and skipped for the pull (`plugins/search.py`). No provider reads robots.txt at run time; the decisions for Jobindex (which is read although its robots.txt disallows `sort=`, `page=` and `geoareaid=`) and Adzuna (whose API host disallows `/` for every agent) are in `READS.robots` and `docs/decisions.md`.
### Jobindex
| | |
|---|---|
| Saved search | `q` in Jobindex's syntax (words are OR, `"a b"` a phrase, `+word` required) and optionally `area`, Jobindex's region id (1 Region Hovedstaden, 8 Aarhus, ...) |
| List | the RSS twin of the search page, `jobindex.dk/jobsoegning.rss`, newest first, 20 per page; no total. `READS.complete="never"`: a search is never complete, so its roles close by the 21 days only |
| Pages read | 5 by default (100 results), 10 at most (200) |
| Text | an excerpt of a couple of hundred characters from the feed, stored as the teaser. The full text only through "Fetch the posting", on demand, since every fetch of Jobindex's link counts as a click in its statistics |
| Date | `pubDate`; trusted |
| Place | the item's area, else the search's area; country always Denmark |
| Remote | the reader states none; prep reads place and title words |
| Pay | none |
| Key | none |
| Limitations | The company is the logo's alt text or what follows the title's last comma. Items are not followed to the employer's site during a search; the on-demand fetch follows the "Se jobbet" link. |
### Platsbanken
| | |
|---|---|
| Saved search | `q` and optionally `region`, a län id from JobTech's taxonomy (Skåne is `CaRE_1nn_cSU`); empty for all of Sweden |
| List | `jobsearch.api.jobtechdev.se/search`, newest first, 100 per page; states `total` |
| Pages read | 5 by default (500 results), 10 at most (1,000); the API refuses an offset above 2,000, which the page limit never reaches |
| Text | `description.text` of the ad, the whole ad |
| Date | `publication_date`; trusted |
| Place | every entry of `workplace_addresses` (municipality, else region, else country) as a place of the role; country always Sweden |
| Remote | `workplace_model.label` where present, which is mostly empty; prep also reads headline words |
| Pay | none |
| Key | none |
| Limitations | A region is a län; there is no municipality or city filter. Free text ranks by all words rather than requiring them; a quoted phrase narrows it. |
### Adzuna
| | |
|---|---|
| Saved search | `q`, `country` (gb, de, nl, fr, at, be, es, it, pl, ch; not Denmark) and optionally `where`, a free place text |
| List | `api.adzuna.com/v1/api/jobs/<country>/search/<page>`, newest first, 50 per page; states `count` |
| Pages read | 5 by default (250 results), 10 at most (500) |
| Text | Adzuna's `description` snippet, stored as the teaser; its length is not stated in the code |
| Date | `created`; trusted |
| Place | `location.display_name`; country from the search |
| Remote | prep reads the place line, then title words |
| Pay | figures from `salary_min` and `salary_max` in the country's currency, dropped when Adzuna marks them as predicted |
| Key | a free key from developer.adzuna.com, as `sources.search.adzuna` in the config or `ADZUNA_APP_ID` and `ADZUNA_APP_KEY`; without one the search fails |
| Limitations | Built against Adzuna's documented response and never run live; no Adzuna role is in the database. |
### freehire
| | |
|---|---|
| Saved search | `q`, optionally `country` (lower-case ISO codes, comma-separated; empty for all) and `remote` (a work mode of freehire's: `MODES` in the module) |
| List | `freehire.me/api/v1/agent/jobs/search`, newest first, 100 per page; states `meta.total`. A public API with no key, 300 requests a minute; robots.txt allows `/` and invites API use with a descriptive user agent |
| Pages read | 5 by default (500 results), 10 at most (1,000); the API ends at `offset + limit = 10000` |
| Text | the whole text, as HTML in the answer |
| Date | `posted_at`; trusted |
| Place | `cities` and `location`; the country only when the row names exactly one |
| Remote | `work_mode` |
| Pay | figures from `enrichment`, only where `salary_period` is a year |
| Key | none |
| Limitations | freehire aggregates about 50 hosts, and keeps the one a row came from in `raw` (`source`: `greenhouse`, `jobnet`, ...). A row whose employer is a board roledesk reads is a copy of that board's role and is hidden behind it by the dupes rule. Unquoted words in `q` are OR over title, company, text and place, so a query is noisy: narrow it by country. |
### Jobnet
| | |
|---|---|
| Saved search | `q` and optionally `region`, one of Jobnet's five region ids (`REGIONS` in the module); empty for all of Denmark |
| List | `jobnet.dk/bff/FindJob/Search`, newest first, 100 per page; states `totalJobAdCount`. The site's own backend answers 401 without the header `x-csrf: 1` and 200 with it, with no login |
| Pages read | 5 by default (500 results), 10 at most (1,000); page 101 at 100 a page answers empty |
| Text | the whole text, as HTML in the answer |
| Date | `publicationDate`; trusted |
| Place | `postalDistrictName`, else `municipality`; country Denmark unless the ad names another |
| Remote | none |
| Pay | none |
| Key | none |
| Limitations | The state's portal: mostly the public sector and small companies, and about a fifth of its ads link to an employer's own ATS. Every word must appear and quotes find nothing, so a search is one term. There is no robots.txt (`/robots.txt` redirects to a login). The ad's deadline is kept in `raw` only. |
### Akademikernes Jobbank
| | |
|---|---|
| Saved search | `q` and optionally `region` (an `amt` id from the site's own search form: `REGIONS` in the module, 2 is Storkøbenhavn) and `remote` (`helt` fully remote, `delvist` partly) |
| List | the RSS feed `jobbank.dk/job/rss/`, 100 items a page; an empty page ends it. It states no total and is not sorted by date |
| Pages read | at most the module's `ceiling`, which keeps a run under about 20 pages |
| Text | one request a role: the JSON-LD `JobPosting` on `/job/<id>/...`, read by fetch text for the roles in the cut. The listing carries none |
| Date | `datePosted` from the role's page; trusted |
| Place | the region in the item's description line, and `jobLocation.addressLocality` from the page; country Denmark |
| Remote | not stated by a row; the search's `remote` filter narrows the list |
| Pay | none |
| Key | none |
| Limitations | Academic and research roles, plus some corporate ads. robots.txt allows `/job/` and disallows `/fwd/webjob/`, which is never followed. Cloudflare may answer a challenge instead of the page, which is an error for that role and not an empty text. |
Jooble was left out: it gives a key only on a manual application and answered a Cloudflare challenge. Jobdanmark was left out too: about a quarter of its newest ads are on Jobnet, freehire carries the rest as source `jobdanmark`, and its list has no text. LinkedIn's guest pages are out because its robots.txt disallows `/` and its terms forbid automated access; LinkedIn enters only as alert mail. Indeed has no public search API.