Platform Adapters¶
Each job data source is implemented as an adapter behind the JobSearchService ABC.
Where an adapter can search is data, not code: every adapter ships a sites.toml
naming its site in each region (see Regions), and SiteBackedService
turns that file into regions() and the per-search Site.
Interface Definition¶
from abc import ABC, abstractmethod
class JobSearchService(ABC):
@abstractmethod
def platform(self) -> Platform: ...
@abstractmethod
def regions(self) -> frozenset[str]: ... # region codes it can search
@abstractmethod
async def search(self, criteria: SearchCriteria) -> list[Job]: ...
@abstractmethod
async def fetch_details(self, job: Job) -> Job: ...
Adapter Architecture¶
graph LR
subgraph kairos.core
Trait[JobSearchService ABC]
end
subgraph kairos.platform
Adzuna[AdzunaClient]
Seek[SeekClient]
LinkedIn[LinkedInClient]
RL[RateLimiter]
HC[PlatformHttpClient]
end
Adzuna --> Trait
Seek --> Trait
LinkedIn --> Trait
Seek --> HC
LinkedIn --> HC
HC --> RL
Adzuna API (Primary)¶
Method: HTTP API calls to api.adzuna.com — structured JSON, no scraping.
flowchart LR
Search[SearchCriteria] --> API["GET api.adzuna.com/v1/api/jobs/{country}/search/{page}"]
API --> JSON[JSON Response]
JSON --> Parse[Parse results array]
Parse --> Map[Map to Job entity]
- Free API key from developer.adzuna.com
- Structured JSON: title, company, location, salary, description
- Kairos uses all 19 of its country endpoints (
platform/adzuna/sites.toml); no HK or CN endpoint exists - ~250 requests/day free tier
- Pagination via
pageparameter, 20 results per page - Credentials injected from Settings (not read from config at runtime)
Seek platform: JobsDB HK (Fallback Scraper)¶
Method: httpx + beautifulsoup4 (HTTP + HTML parsing)
flowchart LR
Search[Search URL] --> HTTP[httpx GET]
HTTP --> HTML[HTML Response]
HTML --> Parse["Parse SEEK_APOLLO_DATA JSON"]
Parse --> Map[Map to Job entity]
- One adapter for the sites in
platform/seek/sites.toml, which bundleshk.jobsdb.comonly; host, location-slug prefix, page size and salary period come from there. Seek AU (seek.com.au) and NZ (seek.co.nz) are not bundled: they answer every scripted request with Cloudflare's bot challenge (see decision 0010), so Australia is covered by Adzuna and LinkedIn. A user can still add a site under[platforms.seek.sites.<CODE>] - Server-side rendered with Apollo GraphQL data embedded in
<script>tags - Pagination: ~22 results per page
- DOM fallback parsing via
data-automationattributes - Rate limit: 2-5s randomized delay
- No login required
LinkedIn (Fallback Scraper)¶
Method: httpx + beautifulsoup4 (public job listings)
- Guest API endpoint for paginated HTML fragments (25 per page)
- Searches are scoped to the region's LinkedIn location ("Hong Kong SAR", "China");
a city becomes "
, ", and "Remote" sets the remote filter - Detail pages: JSON-LD structured data on the region's host (
au.linkedin.com,hk.linkedin.com) - Rate limit: 2-6s randomized delay
- No login required
- Fallback: if the regional host fails, tries
www.linkedin.com
JobTech (Sweden)¶
src/kairos/platform/jobtech/ reads GET jobsearch.api.jobtechdev.se/search, the open
API behind Platsbanken. It takes q, limit (≤100), offset (≤2000), municipality
(a taxonomy concept id from sites.toml city_codes), remote=true and
published-after (minutes). Hits hold the full ad text and any application email.
GET /ad/{id} answers 404 or removed: true once an ad closes.
The Hub (Nordic startups)¶
src/kairos/platform/thehub/ reads GET thehub.io/api/v2/jobs, the JSON API behind
thehub.io's own job pages. It is not a documented public API, so the adapter is opt-in
and its shapes can change without notice. It takes countryCode (DK, SE, NO, FI),
search, limit (≤100), page and positionTypes (an id from sites.toml
work_types). It has no date or city filter: the city and remote (isRemote) filters
run in the adapter and posted_within_days is not applied. Hits hold only title,
company and city, so fetch_details reads GET /api/jobs/{id} for the description.
That record's status (ACTIVE) and expirationDate give availability; an unknown id
answers 404.
Company career sites (Tencent, ByteDance, Alibaba)¶
Mainland China has no official job-board API, and the big aggregators (BOSS直聘, 猎聘, 智联, 前程无忧) need a login or a slider challenge. Large employers publish their own career APIs instead:
| Adapter | Endpoint | Session | Regions |
|---|---|---|---|
| Tencent | GET careers.tencent.com/tencentcareer/api/post/Query |
none | CN, HK |
| ByteDance | POST jobs.bytedance.com/api/v1/search/job/posts |
CSRF cookie + x-csrf-token |
CN |
| Alibaba | POST talent.alibaba.com/position/search |
session + XSRF-TOKEN as _csrf |
CN |
These APIs filter by keyword only, so listing_filter.py keeps postings in the site's
region (include/exclude params), the requested city (English or local name from
regions.toml) and the posted-within window.
Company career boards (Greenhouse, Lever, Ashby)¶
src/kairos/platform/ats/ reads the documented, unauthenticated job-board APIs that these applicant
tracking systems publish for each customer company:
| ATS | Endpoint |
|---|---|
| Greenhouse | boards-api.greenhouse.io/v1/boards/<slug>/jobs?content=true |
| Lever | api.lever.co/v0/postings/<slug>?mode=json |
| Ashby | api.ashbyhq.com/posting-api/job-board/<slug> |
They list one company's open roles, not a search, so they do not implement JobSearchService; a board
is named "<ats>:<slug>" (Board.parse) and read with fetch_board. The harvest loop reads them
from [jobs] ats_boards (api/services/ats_harvest.py). Keyword search (SearchCriteria.platforms) accepts only Adzuna, Seek and LinkedIn.
~~Indeed~~ (Deferred)¶
Indeed adapter is deferred due to Cloudflare protection requiring headless browser (Playwright) and high ban risk. Adzuna API covers the same job listings more reliably.
Shared Infrastructure¶
RateLimiter¶
Enforces randomized delays between requests: - Seek: 2-5s - LinkedIn: 2-6s
PlatformHttpClient¶
Wraps httpx.AsyncClient with:
- Rate limiting
- User-Agent rotation (pool of realistic browser UAs)
- Retry with exponential backoff (3 attempts)
Adding a New Platform¶
- Create module under
kairos/platform/<name>/with asites.toml(one table per region) - Subclass
SiteBackedServiceand read the region'sSitewithsite_for_criteria() - Add variant to
Platformenum inkairos.core - Register its factory in
kairos/platform/registry.py
Adding a region¶
Add a table to kairos/core/regions/regions.toml (or [regions.<CODE>] in
config.toml), then a site for it in each platform's sites.toml (or
[platforms.<name>.sites.<CODE>]). The API, CLI and frontend pick it up unchanged.