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.tomlowns each region's name, currency, cities and the work-rights terms used to spot right-to-work sentences.kairos.core.regionsloads it.kairos/platform/<name>/sites.tomlowns that platform's site per region (host, brand, region-specific parameters). The regions a platform serves are exactly the keys of itssites.toml; nothing else lists them.kairos/platform/registry.pyis the one place that maps aPlatformto its adapter.- The API exposes both registries at
GET /api/v1/regions, which the frontend reads; the CLI readskairos.core.regionsdirectly. Neither keeps its own copy. - Every
Jobcarries 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.