Postal Code Lookup

Postal codes for 70 countries (GeoNames via zippopotam.us): postal code to place names, state and coordinates, or city + state to all its postal codes. For GB, CA and IE only the outward part (e.g. SW1A) is resolved. Params: country (ISO2, required), postal_code, or city + state (state abbreviation, e.g. CA, BY).

Run free trial ↗3 free calls per day with the example input. Paid: $0.002 USDC, no limit.

Call it

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);

const res = await payFetch("https://agentsvc.io/api/v1/proxy/postal-code", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"country":"DE","postal_code":"80331"}),
});
const { data, payment } = await res.json();  // payment.transaction = on-chain receipt

Input

Field	Type	Description
country *	string	ISO 3166-1 alpha-2
postal_code	string
city	string
state	string	State abbreviation, required with city

Output

Field	Type	Description
country	string
postal_code	string
found	boolean
places	array
source	string

Example response (data)

{
  "country": "DE",
  "postal_code": "80331",
  "found": true,
  "places": [
    {
      "place": "München",
      "state": "Bayern",
      "state_code": "BY",
      "lat": 48.1345,
      "lon": 11.571
    }
  ],
  "source": "zippopotam.us (GeoNames)"
}