Connect Geography

2. PxWeb dimension naming

Fetch a table listing and a sample table's metadata from the API:

• What is the geography dimension called? ("Region", "Område", "Area"?)
• What do region codes look like? (2-digit, 4-digit, ISO-style?)
• Do codes match geometry properties directly or need mapping?

# Example: fetch Estonia PxWeb table metadata
curl -s "https://andmed.stat.ee/api/v1/en/stat/RV/RV04/RV042/RV0422.px" | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).variables?.map(v=>({code:v.code,text:v.text,values:v.values?.slice(0,5)}))))"

3. Code mapping

Determine the join strategy:

• direct_code: source codes match geometry property exactly (e.g., FIPS codes)
• alias_crosswalk: source codes map to geometry names via lookup table
• label_match: source labels match geometry names (fragile, last resort)

Learned patterns (from Iceland, Estonia, Slovenia builds)

These patterns were discovered empirically. Use them to skip research for common cases.

Geometry property patterns

PxWeb dimension naming

Code format patterns

Key insight: admin2 almost never has numeric codes

Municipality/admin2 geometry files typically only have name. This means:

• Municipality-level join ALWAYS needs alias_crosswalk via dimension labels
• The PxWeb table's label (not code) must match the geometry feature name
• A label cleanup normalizer is usually needed (strip parenthetical suffixes, bilingual labels)

Plugin structure

Follow the Norway SSB plugin pattern exactly. Each plugin exports:

export const {country}Plugin: GeographyPlugin = {
  id: "pxweb-{iso2}-{agency}",
  name: "{Country} {Agency} (PxWeb)",
  family: "pxweb_country",
  priority: 10,

  appliesTo(source) { /* match by sourceId or countryHints */ },
  matchCodes(codes, dimension) { /* recognize code patterns */ },
  knownDimensions() { /* return dimension ID → level mappings */ },
  joinKeyFamilies() { /* return source→target code family mappings */ },
  aliasNormalizers() { /* return code transformation functions */ },
  knownTables() { /* optional: hardcoded table IDs for common topics */ },
};

Registration

After creating the plugin, add it to the ALL_PLUGINS array at the bottom of geography-plugins.ts:

export const ALL_PLUGINS: GeographyPlugin[] = [
  swedenScbPlugin,
  norwaySsbPlugin,
  denmarkDstPlugin,
  // ... existing plugins
  {country}Plugin,  // ← add here
];

Verification

1. pnpm typecheck — must pass
2. pnpm test — must pass (especially geography-plugins.test.ts)
3. Manual: fetch one regional table from the API, check that codes match geometry properties

Batch mode

When adding plugins for multiple countries, use /subagent-tasks:

• One agent per country
• Each agent reads: this skill + Norway plugin (template) + the country's geometry file + one API response
• Agents work independently — no inter-country dependencies

Key files

Rules

• NEVER bypass the generic detector — plugins only ENRICH detection
• ALWAYS include matchCodes — this is how the detector recognizes the country's codes
• ALWAYS include aliasNormalizers if codes don't directly match geometry properties
• Prefer direct_code join strategy over alias_crosswalk over label_match
• Include knownTables only if the country's PxWeb search is known to be unreliable