Postal Code Reverse Lookup
postalCodeReverseLook up locality, county, and street information for any Romanian postal code to validate addresses for shipping.
Instructions
Get locality, county and street information for a given postal code. Parameters: country_code (required), postal_code (required)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country_code | Yes | The country code - must be 'RO' (Romania) | |
| postal_code | Yes | The postal code to look up (e.g., '010123') |
Implementation Reference
- The main handler function that executes the postalCodeReverse tool logic. It validates inputs (country_code, postal_code), calls the API client, formats results grouped by locality, and returns a text response.
async (args: any) => { // Get API key from async context const apiKey = apiKeyStorage.getStore(); if (!apiKey) { return { content: [ { type: "text", text: "Error: X-API-KEY header is required", }, ], }; } // Create API client with customer's API key const client = new EuroparcelApiClient(apiKey); try { // Validate required parameters if (!args.country_code) { return { content: [ { type: "text", text: "Error: country_code parameter is required", }, ], }; } if (!args.postal_code || typeof args.postal_code !== "string") { return { content: [ { type: "text", text: "Error: postal_code parameter is required", }, ], }; } logger.info("Reverse lookup postal code", { country_code: args.country_code, postal_code: args.postal_code, }); const results = await client.postalCodeReverse( args.country_code.toUpperCase(), args.postal_code, ); logger.info(`Found ${results.length} results for postal code`); let formattedResponse = `Results for postal code ${args.postal_code} in ${args.country_code.toUpperCase()}:\n\n`; if (results.length === 0) { formattedResponse += "No results found for this postal code."; } else { // Group by locality const groupedByLocality = results.reduce( (acc: Record<number, typeof results>, result) => { if (!acc[result.locality_id]) { acc[result.locality_id] = []; } acc[result.locality_id].push(result); return acc; }, {}, ); Object.entries(groupedByLocality).forEach(([_, localityResults]) => { const first = localityResults[0]; formattedResponse += `📍 ${first.name_and_county}\n`; formattedResponse += ` Locality ID: ${first.locality_id}\n`; formattedResponse += ` County: ${first.county_name} (${first.county_code})\n`; formattedResponse += ` Streets:\n`; localityResults.forEach((result) => { formattedResponse += ` • ${result.street_name}\n`; }); formattedResponse += "\n"; }); } return { content: [ { type: "text", text: formattedResponse, }, ], }; } catch (error: any) { logger.error("Failed to reverse lookup postal code", error); return { content: [ { type: "text", text: `Error looking up postal code: ${error.message || "Unknown error"}`, }, ], }; } }, ); - Input schema definition for the postalCodeReverse tool using Zod. Defines country_code as enum ['RO'] and postal_code as a string (4-50 chars) with descriptions.
{ title: "Postal Code Reverse Lookup", description: "Get locality, county and street information for a given postal code. Parameters: country_code (required), postal_code (required)", inputSchema: { country_code: z .enum(["RO"]) .describe("The country code - must be 'RO' (Romania)"), postal_code: z .string() .min(4) .max(50) .describe("The postal code to look up (e.g., '010123')"), }, - src/tools/search/postalCodeReverse.ts:7-138 (registration)The registration function registerPostalCodeReverseTool that registers the 'postalCodeReverse' tool with the MCP server using server.registerTool().
export function registerPostalCodeReverseTool(server: McpServer): void { // Create API client instance // Register postalCodeReverse tool server.registerTool( "postalCodeReverse", { title: "Postal Code Reverse Lookup", description: "Get locality, county and street information for a given postal code. Parameters: country_code (required), postal_code (required)", inputSchema: { country_code: z .enum(["RO"]) .describe("The country code - must be 'RO' (Romania)"), postal_code: z .string() .min(4) .max(50) .describe("The postal code to look up (e.g., '010123')"), }, }, async (args: any) => { // Get API key from async context const apiKey = apiKeyStorage.getStore(); if (!apiKey) { return { content: [ { type: "text", text: "Error: X-API-KEY header is required", }, ], }; } // Create API client with customer's API key const client = new EuroparcelApiClient(apiKey); try { // Validate required parameters if (!args.country_code) { return { content: [ { type: "text", text: "Error: country_code parameter is required", }, ], }; } if (!args.postal_code || typeof args.postal_code !== "string") { return { content: [ { type: "text", text: "Error: postal_code parameter is required", }, ], }; } logger.info("Reverse lookup postal code", { country_code: args.country_code, postal_code: args.postal_code, }); const results = await client.postalCodeReverse( args.country_code.toUpperCase(), args.postal_code, ); logger.info(`Found ${results.length} results for postal code`); let formattedResponse = `Results for postal code ${args.postal_code} in ${args.country_code.toUpperCase()}:\n\n`; if (results.length === 0) { formattedResponse += "No results found for this postal code."; } else { // Group by locality const groupedByLocality = results.reduce( (acc: Record<number, typeof results>, result) => { if (!acc[result.locality_id]) { acc[result.locality_id] = []; } acc[result.locality_id].push(result); return acc; }, {}, ); Object.entries(groupedByLocality).forEach(([_, localityResults]) => { const first = localityResults[0]; formattedResponse += `📍 ${first.name_and_county}\n`; formattedResponse += ` Locality ID: ${first.locality_id}\n`; formattedResponse += ` County: ${first.county_name} (${first.county_code})\n`; formattedResponse += ` Streets:\n`; localityResults.forEach((result) => { formattedResponse += ` • ${result.street_name}\n`; }); formattedResponse += "\n"; }); } return { content: [ { type: "text", text: formattedResponse, }, ], }; } catch (error: any) { logger.error("Failed to reverse lookup postal code", error); return { content: [ { type: "text", text: `Error looking up postal code: ${error.message || "Unknown error"}`, }, ], }; } }, ); logger.info("postalCodeReverse tool registered successfully"); } - src/api/client.ts:317-325 (helper)API client method postalCodeReverse that makes the GET request to /search/postal-code-reverse/{countryCode}/{postalCode} endpoint and returns PostalCodeResult[].
async postalCodeReverse( countryCode: string, postalCode: string, ): Promise<PostalCodeResult[]> { const response = await this.client.get<PostalCodeResult[]>( `/search/postal-code-reverse/${countryCode}/${postalCode}`, ); return response.data; } - src/types/index.ts:230-237 (schema)TypeScript interface PostalCodeResult defining the response shape: locality_id, locality_name, name_and_county, county_name, county_code, street_name.
export interface PostalCodeResult { locality_id: number; locality_name: string; name_and_county: string; county_name: string; county_code: string; street_name: string; }