Quick-start guide

Using the Japan postal code API.

A tutorial that takes you from API key to working integration in about 5 minutes: first request, your language of choice, reverse lookup, and messy real-world input. Full reference in the docs.

Get an API key (14 days free) Try the live console — no sign-up

Step 1

Get an API key

Enter your email, check out with Stripe, and your key appears on the spot. No review process, no paperwork.

Sign up with your email (optionally register allowed origins for browser-side use)
Check out by credit card — 14 days free, then ¥1,980/month (≈ $13, billed in JPY)
Your key is shown once, right there. Store it somewhere safe

Not ready to sign up? The search demo and the live console work without an account. Note: the sign-up and account pages are currently in Japanese — the API, docs, and support are available in English.

Step 2

Send your first request

To find a postal code from an address, call GET /api/v1/search, authenticated with the x-api-key header. Replace YOUR_KEY with your key. Romaji input works.

curl --get "https://api.example.jp/api/v1/search" \
  --data-urlencode "address=Marunouchi, Chiyoda-ku, Tokyo" \
  -H "x-api-key: YOUR_KEY"

The response is JSON (UTF-8), with candidates in results — both the original Japanese and romanized fields.

{
  "query": "Marunouchi, Chiyoda-ku, Tokyo",
  "count": 1,
  "results": [
    { "zipcode": "100-0005",
      "prefecture": "東京都", "city": "千代田区", "town": "丸の内",
      "prefecture_romaji": "Tokyo", "city_romaji": "Chiyoda-ku",
      "town_romaji": "Marunochi", "romaji": "Marunochi, Chiyoda-ku, Tokyo" }
  ]
}

Why “Marunochi”? Romanized output follows Japan Post's official romanization, which sometimes differs from common spellings (Marunouchi). Your input can use either — the search matches both.

Step 3

Integrate in your language

The docs have copy-paste examples for JavaScript, Python, PHP, Ruby, and Go — the pattern is always the same: GET request, address query parameter, x-api-key header.

const url = new URL("https://api.example.jp/api/v1/search");
url.searchParams.set("address", "Marunouchi, Chiyoda-ku, Tokyo");

const res = await fetch(url, {
  headers: { "x-api-key": "YOUR_KEY" },
});
const data = await res.json();
console.log(data.results[0].zipcode);   // "100-0005"
console.log(data.results[0].romaji);    // "Marunochi, Chiyoda-ku, Tokyo"

Step 4

Reverse lookup: postal code to address

Call GET /api/v1/lookup with a zipcode parameter. Both 100-0005 and 1000005 are accepted.

curl "https://api.example.jp/api/v1/lookup?zipcode=100-0005" \
  -H "x-api-key: YOUR_KEY"

Tips

Real-world addresses and spelling variants

Input like “Marunouchi 1-2-3, Chiyoda-ku, Tokyo” or 「東京都千代田区丸の内1丁目2-3 ○○ビル3F」 works — block numbers and building names are stripped down to the town level automatically
Romaji variants are folded together: Shimbashi/Shinbashi, Ōsaka/Osaka/Oosaka, Tokyo/Tokyo-to, with or without commas, in any order
Kana input works too (ちよだく / チヨダク)
Zero hits? Retry with just the town and city — the town level is what postal codes map to

Errors & limits

Errors and rate limits, in short

Errors come back as JSON with a stable error code and a human message. Add lang=en for English messages
On 429, wait until the x-ratelimit-reset timestamp and retry — the current limit is always in the response headers
No monthly request cap. Full error table in the docs

API reference — endpoints, romanization details, CORS, rate limits
MCP setup — call the API as a tool from Claude, Cursor and other AI agents
OpenAPI spec — generate clients or import into your tooling

Start 14-day free trial