# Japan Postal Code & Address in English (`japan-open-data/japan-postal-code-english`) Actor

Look up Japanese postal codes (zip codes) and addresses. Returns the address in English/romaji, Japanese kanji and kana, from Japan Post's official data. Works both ways: postal code to address, and address to postal code.

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

## Pricing

from $1.00 / 1,000 address results

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Japan Postal Code & Address in English (Zip Code Lookup, Romaji)

**Look up any Japanese postal code (zip code) and get the address in English/romaji, Japanese kanji and kana — or go the other way, from an English or Japanese address to its 7-digit postal code.** Built on Japan Post's official postal code data, bundled into the Actor, so lookups are fast and never depend on a third-party API.

- Postal code → address: `100-0005` → `Marunochi, Chiyoda-ku, Tokyo 100-0005, Japan` / `〒100-0005 東京都千代田区丸の内`
- Address → postal code: `Shibuya, Tokyo`, `大阪市北区梅田`, `しぶや`, `Tōkyō`
- Real shipping addresses: `Room 1203, Tower A, 3-4-5 Shiba, Minato ku, Tokyo` → `Shiba, Minato-ku, Tokyo 105-0014, Japan`
- No API key, no login, no scraping. Pay only for addresses returned.

### What can it be used for?

1. **Cross-border e-commerce and shipping labels.** Turn a Japanese postal code or a messy customer address into a clean English (romaji) address for international shipping labels, customs forms and carrier APIs — together with the official Japanese address for the local carrier.
2. **Address validation and form autofill.** Check that a postal code exists and matches the city/district the customer typed, fill in prefecture, city and district from a postal code, and normalize addresses in a CRM or order database.
3. **AI agents and data enrichment.** Give an AI agent (via the Apify API or MCP) a reliable tool for "What is the postal code of Shibuya, Tokyo?" or "Translate this Japanese address into English", or enrich a spreadsheet of Japanese addresses with postal codes, prefectures and local government codes.

### How to use it

Put one lookup per line in **Postal codes or addresses** (`queries`). Each line can be:

| You enter | Example | What you get |
|---|---|---|
| A 7-digit postal code | `100-0005`, `1000005`, `〒100-0005` | The address for that code (usually 1 record) |
| A 3-6 digit prefix | `100`, `1000` | Postal codes starting with it, in order |
| An English/romaji address | `Shibuya, Tokyo`, `Kyoto-shi Sakyo-ku Yoshida Honmachi` | Best matching districts, best first |
| A Japanese address | `大阪市北区梅田`, `京都府 京都市 左京区 吉田本町`, `しぶや` | Best matching districts, best first |
| A full shipping address | `Room 1203, Tower A, 3-4-5 Shiba, Minato ku, Tokyo` | The district's postal code; unknown words listed in `ignoredWords` |

**Tips for accurate results**

- **Include the city or ward**, not only the district name. `Ueno, Taito, Tokyo` finds Tokyo's Ueno; `Ueno` alone lists every Ueno in Japan.
- **Want one answer only?** Set **Max results per lookup** (`maxResultsPerQuery`) to `1`. You pay per returned record, so this is also the cheapest setting.
- Block/street numbers (`1-2-3`), building names and room numbers are not part of Japanese postal codes. They are skipped, and words that did not match anything are returned in `ignoredWords` so you can see what was ignored.

#### Input example

```json
{
  "queries": [
    "100-0005",
    "Shibuya, Tokyo",
    "大阪市北区梅田",
    "Room 1203, Tower A, 3-4-5 Shiba, Minato ku, Tokyo"
  ],
  "maxResultsPerQuery": 1
}
```

Limits: up to 1,000 lookups per run; `maxResultsPerQuery` is 1-100 (default 10).

#### Output example

One dataset item per address record:

```json
{
  "query": "100-0005",
  "queryType": "postal_code",
  "status": "ok",
  "postalCode": "100-0005",
  "addressEn": "Marunochi, Chiyoda-ku, Tokyo 100-0005, Japan",
  "addressJa": "〒100-0005 東京都千代田区丸の内",
  "prefecture": "東京都",
  "prefectureKana": "トウキョウト",
  "prefectureEn": "Tokyo",
  "city": "千代田区",
  "cityKana": "チヨダク",
  "cityEn": "Chiyoda-ku",
  "town": "丸の内",
  "townKana": "マルノウチ",
  "townEn": "Marunochi",
  "townNote": "次のビルを除く",
  "townNoteEn": "excluding buildings that have their own postal code",
  "localGovernmentCode": "13101",
  "romajiSource": "japan_post",
  "dataSource": "Japan Post postal code data (KEN_ALL, file dated 2026-08-31; romaji file dated 2026-01-11)"
}
```

A shipping address with building and room words:

```json
{
  "query": "Room 1203, Tower A, 3-4-5 Shiba, Minato ku, Tokyo",
  "queryType": "address",
  "status": "ok",
  "postalCode": "105-0014",
  "addressEn": "Shiba, Minato-ku, Tokyo 105-0014, Japan",
  "ignoredWords": ["Room", "Tower"]
}
```

(Shortened; real items contain all the fields shown above.)

Invalid input and lookups with no match are returned as one free item each, so you always see why:

```json
{"query": "1-2-3", "status": "error", "error": "\"1-2-3\" is not a valid postal code. Japanese postal codes have 7 digits (e.g. \"100-0005\"); 3-6 digits search by prefix. Street/block numbers alone (e.g. \"1-2-3\") cannot be looked up."}
{"query": "xyzzy", "status": "not_found", "error": "No matching Japanese postal code or address. Check the spelling, or try fewer words (e.g. city and district only).", "ignoredWords": ["xyzzy"]}
```

#### Output fields

| Field | Meaning |
|---|---|
| `query`, `queryType` | Your input and how it was read: `postal_code`, `postal_code_prefix` or `address` |
| `status` | `ok`, `not_found` or `error` |
| `postalCode` | 7-digit postal code as `NNN-NNNN` |
| `addressEn` / `addressJa` | Ready-to-use one-line address in English (district, city, prefecture, code, Japan) and in Japanese |
| `prefecture*`, `city*`, `town*` | Each part in kanji, katakana (`*Kana`) and romaji (`*En`) |
| `townNote` / `townNoteEn` | Japan Post's note for the district (e.g. which buildings or blocks are excluded) |
| `localGovernmentCode` | 5-digit Japanese local government code (JIS X 0402) |
| `romajiSource` | `japan_post` = official Japan Post romaji; `generated_from_kana` = romanized by this Actor from the official kana |
| `ignoredWords` | Words from your query that were not used for the match (room numbers, building names, typos) |
| `dataSource` | The Japan Post files and their dates used for this result |
| `error` | Why a lookup failed (only on `error` / `not_found` items) |

### Pricing

This Actor uses **Pay per event** pricing — you pay for results, not for compute time:

| Event | Price | When |
|---|---|---|
| Address result (`address-result`) | **$0.001** per address record ($1 per 1,000) | Each address record returned with `status: "ok"` |
| Actor start (`apify-actor-start`) | **$0.0006** per run | Once at the start of each run (256 MB memory) |

- `not_found` and `error` items are **free**.
- Example: 1,000 postal codes in one run with `maxResultsPerQuery: 1` cost about $1.00 + $0.0006.
- A single postal code lookup (one run, one result) costs about $0.0016.
- To keep costs predictable, set **Max results per lookup** to 1 and use the **maximum cost per run** option when you start the Actor. If that limit is reached, the Actor stops cleanly and tells you in the status message.

### Known limitations

- **Official Japan Post romaji spelling.** English names use Japan Post's own romaji, which does not always match common English spelling. For example, 丸の内 is written **`Marunochi`** (not "Marunouchi") because that is Japan Post's official spelling. Searching for `Marunouchi` still finds it. Where Japan Post has no romaji, the Actor romanizes the official kana (`romajiSource: "generated_from_kana"`); in those names, building names are written without spaces between words.
- **District-level only.** Japanese postal codes stop at the district (town) level. Block numbers are not used to choose between codes, so `3-4-5 Shiba, Minato-ku` returns **both** Shiba postal codes (1-3 chome and 4-5 chome), and both are charged. Set `maxResultsPerQuery` to 1 if you only want the top one.
- **Same district names in many places.** A district name alone (e.g. `Ueno`, `Gion`) matches every district with that name in Japan, and the famous one may not be in the top results. Add the city or ward: `Ueno, Taito-ku, Tokyo`, `Gion, Higashiyama-ku, Kyoto`.
- **Tokyo is ranked first for ambiguous names.** Tokyo's 23 wards are preferred when a name exists in several cities, so `Umeda` returns Umeda in Adachi-ku, Tokyo first and Osaka's Umeda second. Use `Umeda, Osaka` or `大阪市北区梅田` for Osaka.
- **Conflicting words.** If your words point to different places (e.g. `Shinjuku, Osaka`), the Actor keeps the combination that matches and lists the rest in `ignoredWords`. Check `ignoredWords` when a result looks wrong.
- **Very short queries still match.** A 1-character query such as `東` or `区` returns results (and is charged). Use full names.
- **English notes.** 166 district notes (mostly Kyoto street-name notes) have no English translation in `townNoteEn`, and a few notes repeat a word (e.g. 600-8022). The Japanese `townNote` is always complete.
- **Not included:** postal codes assigned to individual large businesses (jigyosho codes), P.O. boxes, street numbers, building-level codes and latitude/longitude.

### Data source, license and updates

- **Source:** Japan Post Co., Ltd. postal code data — "KEN\_ALL" (postal codes with kanji and kana, [download page](https://www.post.japanpost.jp/service/search/zipcode/download/readme.html)) and the romaji edition of the postal code data ([download page](https://www.post.japanpost.jp/service/search/zipcode/download/roman-zip.html)).
- **License:** Japan Post states that it does not claim copyright on the postal code data and that it may be freely redistributed (see the readme pages for [KEN\_ALL](https://www.post.japanpost.jp/service/search/zipcode/download/readme.html) and the [romaji edition](https://www.post.japanpost.jp/zipcode/dl/readme_ro.html)). This Actor adds search, English notes and romaji spelling fixes on top of that data.
- **Not affiliated:** This Actor is an independent project. It is **not affiliated with, endorsed by or sponsored by Japan Post Co., Ltd.** Always double-check critical addresses with the recipient.
- **Updates:** Each build of this Actor downloads the latest files from Japan Post and rebuilds its lookup database, so every build ships the newest data available at that time. Runs never call Japan Post's servers. The file dates used are shown in `dataSource` on every record. Note that Japan Post updates KEN\_ALL monthly but the romaji edition only about once a year, so very new districts may use romaji generated from kana.
- **No personal data:** the data contains only area information (postal codes, prefectures, cities, districts). No names or personal information are collected or returned.

### Use via API, MCP and AI agents

Run it from the Apify API, the Apify client libraries, or as a tool for AI agents through the Apify MCP server. Input is a plain JSON list of strings and every output item has the same flat fields, with `status` and `error` telling the agent exactly what happened. Recommended agent settings: `"maxResultsPerQuery": 1` for "find the postal code of X" questions, a higher value when the user wants to choose between candidates.

### More from Japan Open Data

- [TSA Checkpoint Travel Numbers (Daily, Weekly & YoY)](https://apify.com/japan-open-data/tsa-checkpoint-throughput) — daily U.S. TSA airport checkpoint traveler counts as clean JSON, with Monday-Sunday weekly averages (calculated like Kalshi's TSA market) and year-over-year change.
- [US Hail History by Location (NOAA NEXRAD Radar)](https://apify.com/japan-open-data/us-hail-history) — hail history for any U.S. latitude/longitude from NOAA NEXRAD radar: one row per hail day with the maximum estimated hail size, probability and distance.
- [Mexico Gas Prices API by Station (Official CNE)](https://apify.com/japan-open-data/mexico-fuel-station-prices) — today's regular, premium and diesel prices at every Mexican gas station from the official CNE feed, with coordinates and distance.
- [US Storm Reports API: Hail, Wind & Tornado (NWS)](https://apify.com/japan-open-data/us-storm-reports-live) — U.S. hail, wind, tornado and flood reports from official NWS Local Storm Reports within hours (last 7 days), filterable by state or radius.

### Feedback

Found a wrong result or a missing spelling? Please open an issue on the Actor's **Issues** tab with the query you used and what you expected.

# Actor input Schema

## `queries` (type: `array`):

One lookup per line. Enter a Japanese postal code ("100-0005", "1000005", "〒100-0005"), a 3-6 digit prefix ("100") to list codes that start with it (up to "Max results per lookup"), or an address in English/romaji ("Shibuya, Tokyo", "Tōkyō") or Japanese ("大阪市北区梅田", "しぶや"). Full shipping addresses work too: street/block numbers ("1-2-3"), building and room words that are not in the postal data are ignored and listed in "ignoredWords", because Japanese postal codes stop at the district level.

## `maxResultsPerQuery` (type: `integer`):

Maximum number of address records returned for each lookup (1-100). A postal code usually returns 1 record; city names, district names and prefixes can match many, best matches first. You pay per returned record, so use 1 when you only need the best match.

## Actor input object example

```json
{
  "queries": [
    "100-0005",
    "Shibuya, Tokyo",
    "大阪市北区梅田"
  ],
  "maxResultsPerQuery": 10
}
```

# Actor output Schema

## `results` (type: `string`):

Address records in English/romaji, kanji and kana, with postal codes. Table view: overview.

# 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 = {
    "queries": [
        "100-0005",
        "Shibuya, Tokyo",
        "大阪市北区梅田"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("japan-open-data/japan-postal-code-english").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 = { "queries": [
        "100-0005",
        "Shibuya, Tokyo",
        "大阪市北区梅田",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("japan-open-data/japan-postal-code-english").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 '{
  "queries": [
    "100-0005",
    "Shibuya, Tokyo",
    "大阪市北区梅田"
  ]
}' |
apify call japan-open-data/japan-postal-code-english --silent --output-dataset

```

## MCP server setup

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

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/vW84SedfIQt6ucndl/builds/HVq6nW2FuLXPCU9LF/openapi.json