Japan Postal Code Lookup: Zipcode → Address API for AI Agents

Japanese addresses start with a 7-digit postal code. E-commerce checkout flows, EOR systems, and shipping integrations all rely on instant code → prefecture/city/town auto-fill. Torify provides this with a single API call backed by zipcloud.

Endpoint

GET https://torify.dev/v1/postal/lookup

Parameters

Name	Type	Required	Description	Example
`zipcode`	string	Yes	7-digit Japanese postal code (with or without hyphen)	`1000001`
`all`	boolean	No	When true, returns all addresses if the postal code maps to multiple towns	`true`

Response example

{
  "ok": true,
  "data": {
    "zipcode": "1000001",
    "prefecture": "東京都",
    "city": "千代田区",
    "town": "千代田"
  }
}

Code examples

curl

curl "https://torify.dev/v1/postal/lookup?zipcode=1000001"

TypeScript (x402-fetch)

import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

const res = await fetchWithPayment(
  'https://torify.dev/v1/postal/lookup?zipcode=1000001'
);
const data = await res.json();
console.log(data); // { ok: true, data: { ... } }

Python (requests)

import requests

# Free MCP tier (no auth) or API key (X-API-Key header)
res = requests.get(
    "https://torify.dev/v1/postal/lookup?zipcode=1000001",
    headers={"X-API-Key": "your_torify_pro_key"}
)
print(res.json())

Use cases

E-commerce checkout postal code auto-fill

Shopify, Klaviyo, and EC platforms serving Japanese customers need instant address lookup when a 7-digit postal code is entered. Reduces checkout abandonment.

EOR / Global payroll address validation

Deel, Remote.com, Rippling validate Japanese employee residential addresses against postal codes before processing tax withholding.

LangChain agent normalizing scraped Japanese addresses

Agents extracting addresses from web pages can resolve postal codes to canonical prefecture/city/town names for downstream geocoding or deduplication.

Edge cases & gotchas

Some postal codes map to multiple addresses. Use `all=true` to retrieve the full list.
Backed by zipcloud — no SLA guarantee. Torify returns 502 on upstream failures (no built-in fallback).
Always pass 7 digits without hyphen for canonical lookups. Hyphenated forms ("100-0001") are normalized internally.

Related endpoints

/v1/address/normalize — Japanese Address Normalization API
/v1/region/lookup — Japan Region Code Lookup: JIS X 0402 API
/v1/coordinate/convert — Japan Coordinate Conversion API: WGS84 ↔ JGD2011

← All 36 endpoints

Pricing

$0.02 per call via x402 (USDC on Base). Or use a Pro API key ($49/mo, 10,000 calls/month).

View pricing Code examples ↗