Skip to content

Regions and Platform Sites

Kairos searches more than one job market (Australia, Hong Kong, mainland China, …). A region is one job market; a site is one platform's presence in one region (Seek in Hong Kong is hk.jobsdb.com).

Decision (2026-11-08)

Problem. Countries were a hardcoded Country enum, each adapter hardcoded its own host (seek.com.au, au.linkedin.com), and the frontend kept a second copy of the city lists. Adding Hong Kong and mainland China meant editing all of them.

Options considered.

Option Verdict
Extend the Country enum and add if country == … branches per adapter Rejected: every new market touches every adapter, CLI and frontend
One central table of every platform × region Rejected: a site's URL is a fact about that adapter and belongs beside its code
Region registry in core + one sites.toml per adapter, both overridable from config.toml Chosen

Choice.

  • kairos/core/regions/regions.toml owns each region's name, currency, cities and the work-rights terms used to spot right-to-work sentences. kairos.core.regions loads it.
  • kairos/platform/<name>/sites.toml owns that platform's site per region (host, brand, region-specific parameters). The regions a platform serves are exactly the keys of its sites.toml; nothing else lists them.
  • kairos/platform/registry.py is the one place that maps a Platform to its adapter.
  • The API exposes both registries at GET /api/v1/regions, which the frontend reads; the CLI reads kairos.core.regions directly. Neither keeps its own copy.
  • Every Job carries the region code it was found in (jobs.country).

Configuring

Both registries merge user tables from ~/.config/kairos/config.toml over the bundled defaults, so a new city, a new region or a different host needs no code:

[regions.SG]
name = "Singapore"
currency = "SGD"
cities = [{ name = "Singapore" }]

[platforms.seek.sites.SG]
base_url = "https://sg.jobstreet.com"
brand = "Jobstreet"

A region only becomes searchable on a platform once that platform has a site for it.

Preferred cities

[profile] preferred_cities lists the cities wanted in each region, e.g. { AU = ["Sydney", "Melbourne"], CN = ["Shanghai"] }; a region left out means anywhere. kairos.core.preferred_cities owns it and checks every name against regions.toml. It is set in the web app's Settings (or PUT /api/v1/config/preferred-cities/{region}); the Search view starts each region in its first preferred city, and a watch feed in a region searches every preferred city there unless [watch.regions.<CODE>] locations overrides them.

Searching Chinese-language career sites

Mainland career APIs match keywords against mostly Chinese titles, so an English query alone finds almost nothing there. Three pieces of data close that gap:

Data Where What it does
query_terms regions.toml ([CN.query_terms], [HK.query_terms]) A query containing "backend" also searches 后端, 后台开发, 服务端; results are deduplicated
city_codes a site in sites.toml Maps a city to the API's own code (Tencent cityId, ByteDance location_code_list) so the server filters by city
dates = "opened" a site's params The site's date is when a role first opened (ByteDance), so it never rules a posting out

Add a phrase or a city code in config.toml ([regions.CN.query_terms], [platforms.tencent.sites.CN.city_codes]) when a search misses roles you can see on the site.

Data sources by region

Every Adzuna market is listed (checked against its API on 2026-11-09; it has no endpoint for IE, JP, SE, DK, NO or AR). A city search that finds nothing on Adzuna is tried once more under the city's local_name, since some country sites only know the local spelling (Bruxelles, Sevilla, Port Elizabeth). A market Adzuna lacks can still be added with LinkedIn alone: a [regions.<CODE>] table plus [platforms.linkedin.sites.<CODE>].

The Nordics have no Adzuna site. Sweden adds JobTech, the public employment service's open API. Norway's NAV feed and Finland's Työmarkkinatori API both need a registered key, and Denmark has no public API, so those three run on LinkedIn for now. The Hub (Nordic startups, opt-in) serves all four.

Region Platforms
AU, NZ Adzuna, LinkedIn
US, UK, CA Adzuna, LinkedIn
AT, BE, BR, CH, DE, ES, FR, IN, IT, MX, NL, PL, SG, ZA Adzuna, LinkedIn
SE JobTech (Platsbanken), The Hub, LinkedIn
NO, DK, FI The Hub, LinkedIn
HK JobsDB (Seek platform), LinkedIn, Tencent
CN LinkedIn (mostly foreign companies), Tencent, ByteDance, Alibaba careers

Mainland aggregators (BOSS直聘, 猎聘, 智联, 前程无忧) are deliberately not supported: they require a login or a slider challenge, and scraping them carries legal risk in China.