Skip to content

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 page parameter, 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 bundles hk.jobsdb.com only; 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-automation attributes
  • 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

  1. Create module under kairos/platform/<name>/ with a sites.toml (one table per region)
  2. Subclass SiteBackedService and read the region's Site with site_for_criteria()
  3. Add variant to Platform enum in kairos.core
  4. 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.