Get communes by postal code
ign_get_communes_by_postal_codeFind all French municipalities associated with a specific postal code. This tool queries IGN geographic data to return communes sharing the same postal code.
Instructions
Retrieve French communes (municipalities) associated with a postal code.
This tool queries the IGN API Carto codes-postaux module to find all communes that share a given postal code. In France, a postal code can cover multiple communes, and this tool returns all of them.
Args:
code_postal (string): French postal code (5 digits, e.g. "75001", "69000")
response_format ('markdown' | 'json'): Output format (default: 'markdown')
Returns: For JSON format: [ { "codePostal": "75001", "codeCommune": "75101", "nomCommune": "Paris 1er Arrondissement", "libelleAcheminement": "PARIS" } ]
Examples:
"What communes are in postal code 75001?" -> code_postal="75001"
"Find cities for zip 69000" -> code_postal="69000"
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code_postal | Yes | French postal code (5 digits) | |
| response_format | No | Output format: 'markdown' for human-readable or 'json' for machine-readable | markdown |
Implementation Reference
- src/index.ts:59-113 (registration)Registration of the 'ign_get_communes_by_postal_code' tool with title, description, inputSchema, annotations, and handler function.
server.registerTool( "ign_get_communes_by_postal_code", { title: "Get communes by postal code", description: `Retrieve French communes (municipalities) associated with a postal code. This tool queries the IGN API Carto codes-postaux module to find all communes that share a given postal code. In France, a postal code can cover multiple communes, and this tool returns all of them. Args: - code_postal (string): French postal code (5 digits, e.g. "75001", "69000") - response_format ('markdown' | 'json'): Output format (default: 'markdown') Returns: For JSON format: [ { "codePostal": "75001", "codeCommune": "75101", "nomCommune": "Paris 1er Arrondissement", "libelleAcheminement": "PARIS" } ] Examples: - "What communes are in postal code 75001?" -> code_postal="75001" - "Find cities for zip 69000" -> code_postal="69000"`, inputSchema: z.object({ code_postal: z .string() .regex(/^\d{5}$/, "Postal code must be 5 digits") .describe("French postal code (5 digits)"), response_format: ResponseFormatSchema, }).strict(), annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, }, }, async ({ code_postal, response_format }) => { const communes = await getCommunesByPostalCode(code_postal); if (response_format === ResponseFormat.JSON) { return { content: [{ type: "text", text: JSON.stringify(communes, null, 2) }], }; } const markdown = formatCommunesToMarkdown(communes, code_postal); return { content: [{ type: "text", text: truncateResponse(markdown, CHARACTER_LIMIT) }], }; } ); - src/index.ts:100-112 (handler)Handler implementation: fetches communes via getCommunesByPostalCode, returns JSON or formatted markdown response.
const communes = await getCommunesByPostalCode(code_postal); if (response_format === ResponseFormat.JSON) { return { content: [{ type: "text", text: JSON.stringify(communes, null, 2) }], }; } const markdown = formatCommunesToMarkdown(communes, code_postal); return { content: [{ type: "text", text: truncateResponse(markdown, CHARACTER_LIMIT) }], }; } - src/index.ts:85-91 (schema)Zod inputSchema: validates code_postal (5-digit string) and response_format.
inputSchema: z.object({ code_postal: z .string() .regex(/^\d{5}$/, "Postal code must be 5 digits") .describe("French postal code (5 digits)"), response_format: ResponseFormatSchema, }).strict(), - src/api-client.ts:85-87 (helper)getCommunesByPostalCode: core API client function querying IGN endpoint `/codes-postaux/communes/${code_postal}`.
export async function getCommunesByPostalCode(codePostal: string): Promise<CommuneResponse[]> { return apiRequest<CommuneResponse[]>(`/codes-postaux/communes/${codePostal}`); } - src/types.ts:31-36 (schema)CommuneResponse TypeScript interface defining the structure of commune data returned by the API.
export interface CommuneResponse { codePostal: string; codeCommune: string; nomCommune: string; libelleAcheminement: string; }