Japan Address Normalizer, Geocoder & Romanizer

Turn messy Japanese addresses into clean, structured, geocoded data — and into the English mailing format your systems can actually use.

東京都渋谷区神宮前１丁目１−１ 原宿ビル３Ｆ

becomes

{
    "prefecture": "東京都",
    "city": "渋谷区",
    "town": "神宮前",
    "chome": 1,
    "banchi": "1",
    "go": "1",
    "building": "原宿ビル3F",
    "postalCode": "1500001",
    "municipalityCode": "13113",
    "latitude": 35.671552,
    "longitude": 139.705302,
    "englishAddress": "原宿ビル3F, 1-1-1 Jingumae, Shibuya-ku, Tokyo 150-0001, Japan",
    "matchLevel": "chome",
    "confidence": 0.95
}

No scraping. No API keys. No rate limits. Nothing to get blocked by. Every answer comes from a registry compiled from Japanese government open data and shipped inside the Actor.

---

Why this exists

Japanese addresses are hostile to software written outside Japan:

The problem	Example
Full-width digits	１丁目１−１ vs 1-1-1
Kanji numerals	三丁目 = 3-chome
Three different counters for the same thing	1丁目2番3号, 1-2-3, 1丁目2-3
The prefecture is usually omitted	福岡市博多区博多駅前2-1-1
Variant kanji from hand entry	宮﨑 vs 宮崎, 霞ヶ関 vs 霞ケ関
Ordinance-designated cities have a ward inside the city	大阪市北区, 札幌市中央区
Rural addresses carry a 大字/字 prefix	大字霊仙, 字若松町
Municipality names repeat across prefectures	府中市 exists in both Tokyo and Hiroshima
Building name is glued to the end with no separator	…1-1-1原宿ビル3F

Regex will get you about half of these. This Actor handles all of them, and tells you how confident it is about each answer.

Measured accuracy: 99.33% exact match across 18,000 round-trip cases — 3,000 randomly sampled towns from the national registry, each written in 6 different real-world styles (registry form, kanji numerals with 番/号, full-width digits, prefecture omitted, spaces between parts, trailing building name). Municipality-level accuracy is 100.00%. Reproduce it yourself: npx tsx test/accuracy.ts 3000.

---

What it does

1. Normalize + geocode a Japanese address

Input any free-form address. You get back the parsed components, the JIS municipality code, the postal code, coordinates, and the official romanisation.

2. Look up a postal code

Give it 150-0001 and get every town the postal registry files under that code, with coordinates and romanisation.

3. Reverse geocode

Give it a latitude/longitude inside Japan and get the nearest 町丁目, plus the distance in metres to its centroid.

All three can run in a single call, and all three produce the same record shape, so the output drops straight into one table.

---

Input

{
    "addresses": [
        "東京都渋谷区神宮前１丁目１−１ 原宿ビル３Ｆ",
        "〒530-0001 大阪府大阪市北区梅田三丁目1番3号",
        "福岡市博多区博多駅前2-1-1"
    ],
    "postalCodes": ["150-0001"],
    "coordinates": [{ "latitude": 35.6595, "longitude": 139.7005 }],
    "includeUnmatched": true,
    "maxResults": 10000
}

Field	Type	Meaning
addresses	string[]	Free-form Japanese addresses. A leading 〒postal code is used as a hint.
postalCodes	string[]	7-digit codes, with or without the hyphen.
coordinates	object[]	{latitude, longitude} pairs inside Japan.
includeUnmatched	boolean	Keep a row for inputs that could not be matched, so the output lines up 1:1 with the input. Default true.
maxResults	integer	Hard cap on rows written — this is what determines the cost of the run.

Output

One row per query (postal-code lookups can produce several).

Field	Description
input, normalized	What you sent, and the cleaned-up single-line form
matchLevel	chome › town › city › prefecture › none — how far down the hierarchy the match got
confidence	0–1, derived from matchLevel
prefecture, city, town, chome, banchi, go, building	The parsed components
postalCode	7 digits, no hyphen
municipalityCode	全国地方公共団体コード (JIS X 0402 + check digit) — the join key for every Japanese government statistic
latitude, longitude	WGS84, 町丁目 centroid
prefectureRomaji, cityRomaji, townRomaji, townKana	Official romanisation and katakana reading
englishAddress	Ready-to-print international mailing format
distanceMeters	Reverse geocoding only — distance to the matched centroid
ambiguousWith	Set when the municipality name exists in more than one prefecture
warnings	Anything you should know about this row, in plain English
datasetBuiltAt	Build date of the bundled registry

---

Use cases

• Deduplicate a Japanese customer or supplier list. Two rows written 東京都渋谷区神宮前1丁目1-1 and 渋谷区神宮前１−１−１ normalise to the same record with the same coordinates.
• Ship to Japan. englishAddress is the mailing format carriers and marketplaces expect.
• Join Japanese data to government statistics. municipalityCode is the key used by every 政府統計 dataset (population, income, business counts).
• Clean the output of any other Japanese scraper. Marketplace, real-estate and restaurant scrapers all emit raw address strings — feed them through this to get coordinates and structure.
• Give an AI agent a Japan address tool. The Actor runs as an MCP tool: an agent can ask "where is this address, and what is it in English?" and get a typed answer with a confidence score.

---

Pricing

Pay per event: a small charge to start the run, plus a charge per row returned. A 10,000-address batch is a single run. There are no proxy costs, because there is nothing to proxy.

---

Data sources

Everything is public, free and downloaded from the publisher — there is no scraping anywhere in this Actor, at build time or at run time.

Source	Publisher	Licence	Used for
位置参照情報 大字・町丁目レベル	国土交通省 (Ministry of Land, Infrastructure, Transport and Tourism)	公共データ利用規約 第1.0版 (PDL1.0) — commercial use and redistribution permitted with attribution	Town names and coordinates — 191,106 towns in 1,892 municipalities
郵便番号データ	日本郵便 (Japan Post)	Japan Post does not assert copyright over the postal code data and permits free redistribution	Postal codes and katakana readings — 124,513 records
郵便番号データ ローマ字版	日本郵便 (Japan Post)	as above	Official romanisation

Required attribution, reproduced here and in every run's RUN_SUMMARY:

「位置参照情報ダウンロードサービス」（国土交通省）（https://nlftp.mlit.go.jp/isj/）をもとに jp-data-engine が加工して作成

郵便番号データ（日本郵便株式会社）をもとに jp-data-engine が加工して作成

The registry is recompiled from the publishers' current releases every time the Actor is rebuilt, and each output row carries the datasetBuiltAt date it was answered from.

---

Known limits

Stated up front rather than discovered later:

• Coordinates are 町丁目 centroids, not rooftop-level. banchi and go are parsed and returned but not separately geocoded. For most joins, dedupe and shipping work this is the right granularity; if you need building-level coordinates, this is not that.
• Kyoto's street-name addresses (烏丸通御池下ル) resolve to the ward, with a warning. They are not 町丁目 addresses, so the registry has nothing finer to match.
• Ambiguous municipality names without a prefecture or postal code return the match plus an ambiguousWith list rather than silently guessing.
• Around 16% of towns have no published romanisation in the postal dataset — those rows carry a warning and an empty townRomaji.
• Addresses outside Japan return matchLevel: "none" with confidence: 0.

---

Local development

npm install
npm run build:data   # downloads the government data and compiles the registry into data/
npm test             # 31 unit tests
npx tsx test/accuracy.ts 3000   # the accuracy measurement quoted above
npx apify run        # run with the default input

Built by jp-data-engine — Japanese data, structured for everyone else.