get_population

Instructions

Implementation Reference

• src/modules/statistics.ts:182-295 (handler)

  The handleGetPopulation function processes the 'get_population' tool request by fetching data from the Swiss Federal Statistical Office (BFS) API and formatting it based on the requested canton and year.

  async function handleGetPopulation(args: Record<string, unknown>): Promise<string> {
    const rawCanton = typeof args.canton === "string" ? args.canton.trim() : "";
    const rawYear = args.year;
    const year = rawYear !== undefined ? String(rawYear) : LATEST_YEAR;
  
    if (!AVAILABLE_YEARS.includes(year)) {
      throw new Error(`Year must be between ${AVAILABLE_YEARS[0]} and ${LATEST_YEAR}. Got: ${year}`);
    }
  
    const url = `${PXWEB_BASE}/${POPULATION_TABLE}/${POPULATION_TABLE}.px`;
  
    // Determine which locations to query
    let locationCodes: string[];
    let mode: "switzerland" | "canton" | "all";
  
    if (!rawCanton || rawCanton.toLowerCase() === "switzerland" || rawCanton === "8100") {
      locationCodes = ["8100"];
      mode = "switzerland";
    } else if (rawCanton.toLowerCase() === "all") {
      locationCodes = ["8100", ...ALL_CANTON_CODES];
      mode = "all";
    } else {
      const code = resolveCantonCode(rawCanton);
      if (!code) {
        throw new Error(
          `Unknown canton: "${rawCanton}". Use a 2-letter code (ZH, BE, GE…) or canton name. ` +
          `Or use "all" to list all cantons.`
        );
      }
      locationCodes = [code];
      mode = "canton";
    }
  
    const body = {
      query: [
        { code: "Jahr", selection: { filter: "item", values: [year] } },
        {
          code: "Kanton (-) / Bezirk (>>) / Gemeinde (......)",
          selection: { filter: "item", values: locationCodes },
        },
        { code: "Bevölkerungstyp", selection: { filter: "item", values: ["1"] } },
        { code: "Staatsangehörigkeit (Kategorie)", selection: { filter: "item", values: ["-99999"] } },
        { code: "Geschlecht", selection: { filter: "item", values: ["-99999"] } },
        { code: "Alter", selection: { filter: "item", values: ["-99999"] } },
      ],
      response: { format: "json" },
    };
  
    const data = await fetchJSON<PxWebResponse>(url, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });
  
    if (mode === "switzerland") {
      const row = data.data[0];
      const pop = row ? parseInt(row.values[0], 10) : null;
      return JSON.stringify({
        location: "Switzerland",
        year: parseInt(year, 10),
        population: pop,
        population_type: "Permanent resident population",
        source: "Federal Statistical Office (FSO/BFS) — STATPOP",
        source_url: "https://www.bfs.admin.ch/bfs/en/home/statistics/population.html",
      });
    }
  
    if (mode === "canton") {
      const code = locationCodes[0];
      const row = data.data[0];
      const pop = row ? parseInt(row.values[0], 10) : null;
      return JSON.stringify({
        /* c8 ignore next */
        location: CANTON_NAMES[code] ?? code, // defensive: code always in CANTON_NAMES
        canton_code: code,
        year: parseInt(year, 10),
        population: pop,
        population_type: "Permanent resident population",
        source: "Federal Statistical Office (FSO/BFS) — STATPOP",
        source_url: "https://www.bfs.admin.ch/bfs/en/home/statistics/population.html",
      });
    }
  
    // mode === "all"
    // Build a code→name map from the response keys
    const cantons: Array<{ canton: string; code: string; population: number }> = [];
    let switzerland: number | null = null;
  
    for (const row of data.data) {
      const locCode = row.key[1]; // year, location, poptype, citizenship, sex, age
      const pop = parseInt(row.values[0], 10);
      if (locCode === "8100") {
        switzerland = pop;
      } else {
        cantons.push({
          canton: CANTON_NAMES[locCode] ?? locCode,
          code: locCode,
          population: pop,
        });
      }
    }
  
    // Sort by population descending
    cantons.sort((a, b) => b.population - a.population);
  
    return JSON.stringify({
      year: parseInt(year, 10),
      switzerland_total: switzerland,
      cantons,
      population_type: "Permanent resident population",
      source: "Federal Statistical Office (FSO/BFS) — STATPOP",
      source_url: "https://www.bfs.admin.ch/bfs/en/home/statistics/population.html",
    });
  }

• src/modules/statistics.ts:119-141 (schema)

  The get_population tool definition, which includes the input schema for arguments 'canton' and 'year'.

  export const statisticsTools = [
    {
      name: "get_population",
      description:
        "Get Swiss population data from the Federal Statistical Office (FSO/BFS). " +
        "Returns population figures for Switzerland, a canton, or all cantons. " +
        "Data source: BFS STATPOP (permanent resident population).",
      inputSchema: {
        type: "object",
        properties: {
          canton: {
            type: "string",
            description:
              "Canton name or 2-letter code (e.g. 'ZH', 'Zürich', 'Geneva', 'BE'). " +
              "Omit to get Switzerland total. Use 'all' to list all cantons.",
          },
          year: {
            type: "number",
            description: `Year of data (${AVAILABLE_YEARS[0]}–${LATEST_YEAR}). Defaults to latest (${LATEST_YEAR}).`,
          },
        },
      },
    },

• src/modules/statistics.ts:368-382 (registration)

  The main dispatcher function 'handleStatistics' routes the 'get_population' tool name to the 'handleGetPopulation' handler.

  export async function handleStatistics(
    name: string,
    args: Record<string, unknown>
  ): Promise<string> {
    switch (name) {
      case "get_population":
        return handleGetPopulation(args);
      case "search_statistics":
        return handleSearchStatistics(args);
      case "get_statistic":
        return handleGetStatistic(args);
      default:
        throw new Error(`Unknown statistics tool: ${name}`);
    }
  }