Japan Postal Code (KEN_ALL) Lookup API

Look up any Japanese 7-digit postal code and get the full address — prefecture, city/ward and town in kanji, kana and English prefecture — or go the other way and list every postal code in a prefecture or city. Powered by Japan Post's official KEN_ALL data.

This Actor is a search / conversion API over the official 日本郵便 郵便番号データ (KEN_ALL). On each run it downloads the official KEN_ALL archive once, unzips and parses it in memory, and answers your lookup. Every output record carries a legal envelope (source / sourceUrl / license / retrievedAt).

Unofficial tool. Independently built and maintained. Not affiliated with, endorsed by, or connected to Japan Post Co., Ltd. (日本郵便株式会社). The underlying postal code data is published by Japan Post, which asserts no copyright on it and permits free distribution (see below).

---

Quick start — verified input

Copy, paste, run. This exact input is verified on the platform (SUCCEEDED, items > 0):

{
  "mode": "by_zipcode",
  "zipcode": "1000001"
}

Running with no input at all also works (same defaults). To go the other way — every postal code in an area — use {"mode": "by_address", "prefecture": "Tokyo", "city": "千代田区"}. prefecture is a dropdown of the 47 English prefecture names; via the API you may also pass the Japanese name ("東京都"), the JIS code ("13"), or common romanisations ("osaka-fu", "Ōsaka").

No API key required

The KEN_ALL download is public and unauthenticated. Just pick a mode and run. The Actor keeps a single connection, spaces requests ≥ 1.2 s apart, backs off exponentially on HTTP 429/5xx, and fails visibly on a persistent block — it never attempts rate-limit evasion. Only one file is downloaded per run.

License & attribution

Japan Post's own terms for the postal code data (原文, readme):

「郵便番号データに限っては日本郵便株式会社は著作権を主張しません。自由に配布していただいて結構です。」 (For the postal code data specifically, Japan Post Co., Ltd. does not assert copyright. You are free to distribute it.)

Use, redistribution, porting and modification are all explicitly permitted. As a courtesy the source credit 「出典：日本郵便株式会社 郵便番号データ」 is embedded verbatim in the license field of every record — keep it visible if you republish.

Two modes

1. by_zipcode — code → address

Give a 7-digit zipcode (hyphen/spaces tolerated, e.g. 1000001 or 100-0001) and get the matching address record(s): prefecture / city / town in kanji and katakana, plus the English prefecture name and the JIS municipality code. Most codes map to one address; some map to several (returned as multiple records).

2. by_address — area → codes

Give a prefecture (kanji 東京都, English Tokyo, or JIS code 13) and/or a city substring (千代田区) and get every postal code in that area. At least one filter is required (a bounded lookup, not a full-table dump).

Sample output (by_zipcode, zipcode: "1000001")

{
  "zipcode": "1000001",
  "municipalityCode": "13101",
  "prefecture": "東京都",
  "prefectureKana": "トウキョウト",
  "prefectureEn": "Tokyo",
  "city": "千代田区",
  "cityKana": "チヨダク",
  "town": "千代田",
  "townKana": "チヨダ",
  "source": "日本郵便 郵便番号データ（KEN_ALL）/ Japan Post postal code data",
  "sourceUrl": "https://www.post.japanpost.jp/zipcode/download.html",
  "license": "出典：日本郵便株式会社 郵便番号データ … 著作権を主張しません。自由に配布していただいて結構です。 … Unofficial …",
  "retrievedAt": "2026-08-26T12:00:00.000Z"
}

Input reference

Field	Mode	Description
mode	both	by_zipcode (default) or by_address. Case-insensitive.
zipcode	by_zipcode	7-digit code; hyphen/spaces/〒/全角 tolerated (1000001, 100-0001). Required in by_zipcode mode.
prefecture	by_address	One of the 47 prefectures — English (Tokyo), kanji (東京都) or JIS code (13).
city	by_address	City/ward substring in kanji, e.g. 千代田区, 横浜市. At least one of prefecture / city is required in by_address mode.
edition	both	utf8 (default, one record per line) or shiftjis (classic KEN_ALL, decoded to UTF-8 with split-town rows merged).
maxItems	both	Max records to output, 1–100000 (default 1000).
maxApiRequests	both	Hard per-run upstream request cap, 1–8 (default 5; only one download is needed).
proxyConfiguration	both	Optional Apify proxy; default is a direct connection.

Values are validated before the download; an invalid value fails the run immediately with a message that lists the valid values.

Common input mistakes

Mistake	Correct
"zipcode": "100" or "10000011" (not 7 digits)	"zipcode": "1000001" — exactly 7 digits (100-0001 is fine too)
"prefecture": "Tokyo" while mode is by_zipcode	set "mode": "by_address" (the default mode expects a zipcode)
"prefecture": "Osaka-shi" / "Yokohama" (a city)	"prefecture": "Osaka" + "city": "大阪市" / "prefecture": "Kanagawa" + "city": "横浜市"
"city": "Chiyoda" (romaji)	"city": "千代田区" — KEN_ALL cities are kanji only
"edition": "euc-jp"	"utf8" or "shiftjis"
"maxItems": "all"	a number, e.g. 1000

Empty results?

The run completes with 0 items (and a warning in the log, not a failure) when the lookup matches nothing: a postal code that Japan Post has retired or never assigned, a kanji city string that is not a substring of the KEN_ALL city field (e.g. "千代田" works, "千代田区役所" does not), or a prefecture + city pair that do not belong together. Check the spelling on https://www.post.japanpost.jp/zipcode/ and retry.

Notes & limits

• Character encoding is handled for you. The utf8 edition is the modern one-record-per-line file; shiftjis reads the classic KEN_ALL (half-width kana), decoded Shift_JIS → UTF-8, with the long parenthesised 町域 rows that KEN_ALL splits across lines automatically re-joined.
• This Actor covers the address postal codes (KEN_ALL, ~124,000 entries). It does not include the separate 事業所個別番号 (business-specific codes).
• town values such as 以下に掲載がない場合 are passed through exactly as Japan Post publishes them.
• English is provided at the prefecture level (Hepburn). City/town romaji are not part of KEN_ALL and are left out.

Disclaimer

1. Unofficial — not affiliated with, endorsed by, or connected to Japan Post Co., Ltd.
2. Public data, your responsibility — the postal code data is provided by Japan Post free of copyright; the source credit is embedded in every record. Verify anything important against the source before relying on it.
3. Polite by design — one connection, ≥ 1.2 s spacing, exponential backoff, a hard request budget, and a visible failure on a persistent block. No rate-limit evasion.
4. No warranty — provided "as is"; the data reflects the most recent KEN_ALL publication at download time.

Search terms

japan postal code api, japan zipcode lookup, japan address data english, ken_all, japanese postal code to address, japan zip code database, 郵便番号 api, japan prefecture city lookup, postal code japan csv, japan address autocomplete data