lookup_postcode
Find Swiss locality details by postal code to get place name, canton, and geographic coordinates using official federal geodata.
Instructions
Look up a Swiss postcode (PLZ) to get locality name, canton, and coordinates. Source: Swiss federal geodata (swisstopo).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| postcode | Yes | Swiss postal code (PLZ), e.g. "8001" or "3000" |
Implementation Reference
- src/modules/post.ts:212-264 (handler)The handler logic for the 'lookup_postcode' tool in `handlePost`. It validates the postcode, fetches the data from the swisstopo API, identifies the canton, and returns the result.
case "lookup_postcode": { const postcode = String(args.postcode ?? "").trim(); if (!/^\d{4}$/.test(postcode)) { throw new Error(`Invalid Swiss postcode: "${postcode}". Must be a 4-digit number.`); } // 1. Fetch PLZ record from the official registry const findUrl = buildUrl(`${BASE}/rest/services/api/MapServer/find`, { layer: PLZ_LAYER, searchText: postcode, searchField: "plz", returnGeometry: false, sr: 4326, }); const findData = await fetchJSON<PlzFindResponse>(findUrl); if (!findData.results.length) { return JSON.stringify({ found: false, postcode, message: "Postcode not found." }); } const record = findData.results[0]; const attr = record.attributes; // 2. Get coordinates + confirm locality from SearchServer (zipcode origin) const searchUrl = buildUrl(`${BASE}/rest/services/api/SearchServer`, { searchText: postcode, type: "locations", origins: "zipcode", sr: 4326, limit: 1, }); const searchData = await fetchJSON<SearchResponse>(searchUrl); const searchEntry = searchData.results.find((r) => r.attrs.origin === "zipcode") ?? null; const lat = searchEntry?.attrs.lat ?? null; const lon = searchEntry?.attrs.lon ?? null; // 3. Identify canton const canton = lat !== null && lon !== null ? await identifyCanton(lat, lon) : null; return JSON.stringify({ found: true, postcode: attr.plz, locality: attr.langtext, canton: canton ? { code: canton.code, name: canton.name } : null, coordinates: lat !== null ? { lat, lon } : null, source: "swisstopo — Amtliches Ortschaftenverzeichnis", }); } - src/modules/post.ts:140-154 (schema)The tool registration definition for 'lookup_postcode', including the name, description, and input schema.
{ name: "lookup_postcode", description: "Look up a Swiss postcode (PLZ) to get locality name, canton, and coordinates. Source: Swiss federal geodata (swisstopo).", inputSchema: { type: "object", required: ["postcode"], properties: { postcode: { type: "string", description: "Swiss postal code (PLZ), e.g. \"8001\" or \"3000\"", }, }, }, },