# GET /postcode/lookup: $0.001 per call

Postal code to place name, region and latitude/longitude in about 60 countries (US ZIP codes, UK postcodes, Canada, Germany, France, India, Japan, Australia...). Pass ?country=US&postcode=10001. Use the coordinates with /weather. UK from the ONS postcode directory, others from GeoNames.

- **Price:** $0.001 in USDC, the same on Base, Solana, Polygon, Arbitrum. Failed calls are never charged.
- **Free trial:** yes, 20 free calls a day from Claude, Cursor or any MCP client ([set-up](/mcp/setup)).
- **Answers cached for:** 7 day(s)
- **Data sources:** postcodes.io (free, OGL); Zippopotam.us (free, GeoNames CC BY 4.0)
- **Lane:** Time, holidays & weather ([OpenAPI](/openapi/world.json))
- **Live health:** [status page](/status)

## Free sample

See an answer for the demo input first, free (no payment, 10 a minute): [https://aayatai.com/sample/postcode-lookup](/sample/postcode-lookup). It is a stored real answer when we have one, otherwise an example marked `"kind": "illustrative"`.

```bash
curl "https://aayatai.com/sample/postcode-lookup"
```

## 1. See the price (free)

Call it without paying: you get `402 Payment Required` and a `PAYMENT-REQUIRED` header with the exact price and where to pay.

```bash
curl -i "https://aayatai.com/postcode/lookup?country=US&postcode=10001"
```

## 2. Pay and call (TypeScript)

```bash
npm install @x402/fetch @x402/evm viem
```

```ts
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

// A wallet used only by your agent, holding a little USDC on Base.
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await pay("https://aayatai.com/postcode/lookup?country=US&postcode=10001");
console.log(await res.json());
```

## 3. Or as an MCP tool

```ts
// MCP server: https://aayatai.com/mcp (Streamable HTTP). With the x402 MCP client (see /start):
const result = await client.callTool("postcode-lookup", {"country":"US","postcode":"10001"});
```

## Inputs

- `country` **(required)** (string): ISO 2-letter country code, e.g. US, GB, DE, FR, CA, IN, JP, AU.
- `postcode` **(required)** (string): The postal code, e.g. 10001, SW1A 1AA, 75001, M5V.

Bad inputs are rejected with HTTP 400 before any payment is asked for.

## Example answer

Example only: the shape of an answer, with placeholder addresses and made-up figures. It is not data about any real token or wallet; call the service (or its free sample) for real results.

```json
{
  "country": "US",
  "postcode": "10001",
  "places": [
    {
      "name": "New York City",
      "region": "New York",
      "regionCode": "NY",
      "latitude": 40.7484,
      "longitude": -73.9967
    }
  ],
  "precision": "postcode",
  "note": "Coordinates are the centre of the postal area, not an address.",
  "source": "Zippopotam.us (GeoNames data, CC BY 4.0)"
}
```

## Related

- [GET /time/convert](/services/time-convert) ($0.001): Convert a date and time between time zones, daylight saving handled.
- [GET /holidays](/services/holidays) ($0.002): Public holidays for 38 countries (most of Europe, UK by nation, US federal, Brazil, Mexico, South Africa) with regional holidays (e.g.
- [GET /weather](/services/weather) ($0.002): Weather now and forecast for any latitude/longitude on Earth: temperature, feels-like, wind, humidity, cloud, pressure, rain next hour, the next 12 hours, and d
- [GET /airport/status](/services/airport-status) ($0.002): Live US airport delays from the FAA: ground delay programs (average and maximum delay), ground stops, arrival and departure delays with trend, and closures, wit
- [GET /earthquakes](/services/earthquakes) ($0.002): Recent earthquakes near any point on Earth from the US Geological Survey: magnitude, place, time, depth, felt reports, tsunami flag and a link, newest first.
- [GET /business-hours](/services/business-hours) ($0.001): Is a business open now (or at a given time), and when does it next open or close?

New here? [Getting started in 60 seconds](/start). All services: [Aayat AI](/).