# Japan Address Normalizer, Geocoder & Romanizer (`jp-data-engine/japan-address-intelligence`) Actor Japanese address geocoding, normalization and romaji conversion. Parses prefecture, city, town, chome and banchi, then returns the JIS municipality code, postal code, latitude/longitude and the English mailing address. 99.33% measured accuracy, from government open data. - **URL**: https://apify.com/jp-data-engine/japan-address-intelligence.md - **Developed by:** [Shota Tatara](https://apify.com/jp-data-engine) (community) - **Categories:** Developer tools, AI, Agents - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 resolved addresses 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/platform/actors/running/actors-in-store#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 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 ```json { "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 ```json { "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 | | --------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | [位置参照情報 大字・町丁目レベル](https://nlftp.mlit.go.jp/isj/) | 国土交通省 (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 | | [郵便番号データ](https://www.post.japanpost.jp/zipcode/download.html) | 日本郵便 (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 ```bash 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](https://apify.com/jp-data-engine) — Japanese data, structured for everyone else. # Actor input Schema ## `addresses` (type: `array`): Free-form Japanese addresses, one per line. Full-width digits, kanji numerals (一丁目), 番地/番/号 counters, missing prefectures and trailing building names are all handled. A leading 〒postal code is used as a hint. ## `postalCodes` (type: `array`): 7-digit Japanese postal codes, with or without the hyphen (`150-0001` or `1500001`). Each one returns every town the registry files under it. ## `coordinates` (type: `array`): Latitude/longitude pairs inside Japan, e.g. `[{"latitude": 35.6595, "longitude": 139.7005}]`. Each one returns the nearest 町丁目 and the distance to its centroid. ## `includeUnmatched` (type: `boolean`): Keep a row for every input, even the ones that could not be matched to the registry, so the output lines up with the input. Turn off to get matched rows only. ## `maxResults` (type: `integer`): Hard cap on the number of rows written. This is what determines the cost of the run. ## Actor input object example ```json { "addresses": [ "東京都渋谷区神宮前１丁目１−１ 原宿ビル３Ｆ", "〒530-0001 大阪府大阪市北区梅田三丁目1番3号" ], "postalCodes": [ "150-0001" ], "coordinates": [ { "latitude": 35.6595, "longitude": 139.7005 } ], "includeUnmatched": true, "maxResults": 10000 } ``` # Actor output Schema ## `results` (type: `string`): No description ## `runSummary` (type: `string`): No description # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "addresses": [ "東京都渋谷区神宮前１丁目１−１ 原宿ビル３Ｆ", "〒530-0001 大阪府大阪市北区梅田三丁目1番3号" ], "postalCodes": [ "150-0001" ], "coordinates": [ { "latitude": 35.6595, "longitude": 139.7005 } ] }; // Run the Actor and wait for it to finish const run = await client.actor("jp-data-engine/japan-address-intelligence").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "addresses": [ "東京都渋谷区神宮前１丁目１−１ 原宿ビル３Ｆ", "〒530-0001 大阪府大阪市北区梅田三丁目1番3号", ], "postalCodes": ["150-0001"], "coordinates": [{ "latitude": 35.6595, "longitude": 139.7005, }], } # Run the Actor and wait for it to finish run = client.actor("jp-data-engine/japan-address-intelligence").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 '{ "addresses": [ "東京都渋谷区神宮前１丁目１−１ 原宿ビル３Ｆ", "〒530-0001 大阪府大阪市北区梅田三丁目1番3号" ], "postalCodes": [ "150-0001" ], "coordinates": [ { "latitude": 35.6595, "longitude": 139.7005 } ] }' | apify call jp-data-engine/japan-address-intelligence --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,jp-data-engine/japan-address-intelligence" } } } ``` 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 ` 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/twGItFs7pmybu8UxO/builds/idOvb075qgSlZZ1uQ/openapi.json