# Japan Postal Code (KEN\_ALL) Lookup API (`jpopendata/japan-postal-codes`) Actor

Unofficial Japan Post postal code (KEN\_ALL) lookup API. by\_zipcode: a 7-digit code -> address (prefecture/city/town, kanji + kana + English prefecture). by\_address: a prefecture/city -> its postal codes. Downloads the official KEN\_ALL once and searches it in memory. Free of copyright per Japan Post.

- **URL**: https://apify.com/jpopendata/japan-postal-codes.md
- **Developed by:** [JP Open Data](https://apify.com/jpopendata) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 record scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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):

```json
{
  "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](https://www.post.japanpost.jp/zipcode/dl/readme.html)):

> 「郵便番号データに限っては日本郵便株式会社は著作権を主張しません。自由に配布していただいて結構です。」
> *(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"`)

```json
{
  "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

# Actor input Schema

## `mode` (type: `string`):

`by_zipcode` (default) looks up one 7-digit postal code and returns its address(es) — set `zipcode`. `by_address` returns every postal code in a prefecture and/or city — set `prefecture` and/or `city`. Example: "by\_zipcode".

## `zipcode` (type: `string`):

by\_zipcode mode (REQUIRED there): the 7-digit Japanese postal code, e.g. "1000001" or "100-0001" (hyphen, spaces, 〒 and full-width digits are tolerated). Ignored in by\_address mode.

## `prefecture` (type: `string`):

by\_address mode: prefecture to list — pick one of the 47 prefectures by English name, e.g. "Tokyo" (via the API the Japanese name "東京都" or JIS code "13" also work). At least one of prefecture / city is required in by\_address mode. Ignored in by\_zipcode mode.

## `city` (type: `string`):

by\_address mode: city / ward / county name in kanji, matched as a substring of the KEN\_ALL city field, e.g. "千代田区", "横浜市", "札幌市中央区". Combine with prefecture to disambiguate. Ignored in by\_zipcode mode.

## `edition` (type: `string`):

Which official KEN\_ALL file to download. `utf8` (default) = the one-record-per-line UTF-8 file (clean, recommended). `shiftjis` = the classic small-kana Shift\_JIS KEN\_ALL (decoded to UTF-8, with split-town rows merged). Aliases like "UTF-8" / "Shift\_JIS" are accepted.

## `maxItems` (type: `integer`):

Maximum number of records to output (1-100000). by\_zipcode returns 1 (occasionally a few) records; by\_address may return thousands for a whole prefecture. Example: 1000.

## `maxApiRequests` (type: `integer`):

Hard safety cap on upstream requests per run (1-8; only one KEN\_ALL download is needed, the rest is retry headroom). Example: 5.

## `proxyConfiguration` (type: `object`):

Apify proxy settings. Default is NO proxy (direct connection) — the public KEN\_ALL download rarely needs one. The Actor backs off exponentially on 429/5xx and fails visibly on a persistent block; it never attempts rate-limit evasion.

## Actor input object example

```json
{
  "mode": "by_zipcode",
  "zipcode": "1000001",
  "city": "千代田区",
  "edition": "utf8",
  "maxItems": 1000,
  "maxApiRequests": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `records` (type: `string`):

Address records (by\_zipcode) or postal-code records for an area (by\_address), each with source attribution (source, sourceUrl, license, retrievedAt).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "by_zipcode",
    "zipcode": "1000001",
    "edition": "utf8",
    "maxItems": 1000,
    "maxApiRequests": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpopendata/japan-postal-codes").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "by_zipcode",
    "zipcode": "1000001",
    "edition": "utf8",
    "maxItems": 1000,
    "maxApiRequests": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("jpopendata/japan-postal-codes").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "by_zipcode",
  "zipcode": "1000001",
  "edition": "utf8",
  "maxItems": 1000,
  "maxApiRequests": 5
}' |
apify call jpopendata/japan-postal-codes --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpopendata/japan-postal-codes"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/UuU3tjqkRu9o5LYPC/builds/irp1DecNb40Y8quEI/openapi.json