# Japanese Address Normalizer & Geocoder (`ohs999/jp-address-normalizer`) Actor

Clean messy Japanese addresses in bulk. Unifies notation (丸ノ内→丸の内, 1丁目→一丁目), fills in missing prefectures, splits into prefecture / city / town, and adds latitude/longitude and municipality codes. Runs on bundled official open data, so your addresses never leave the run.

- **URL**: https://apify.com/ohs999/jp-address-normalizer.md
- **Developed by:** [OHS Data](https://apify.com/ohs999) (community)
- **Categories:** Developer tools, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / 1,000 address normalizeds

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

## Japanese Address Normalizer (住所正規化)

Turn messy Japanese addresses into clean, structured data with coordinates.

- Unifies notation variants: `丸ノ内` → `丸の内`, `1丁目` → `一丁目`, full-width digits, `ヶ/が`, old/new kanji
- Fills in a missing prefecture or county (`千代田区…` → `東京都千代田区…`)
- Splits each address into **prefecture / city / town (町字・丁目)** plus the remaining block number
- Adds **latitude / longitude** of the town and official codes (local government code, ABR 町字ID)
- Runs entirely on bundled open data, so your addresses never leave the run and there are no third-party API limits

Typical uses: deduplicating customer lists (名寄せ), cleaning CRM/EC data, joining address lists with statistics, plotting customers on a map.

### Input

```json
{ "addresses": ["東京都千代田区丸ノ内1丁目1-1", "千代田区霞ヶ関１－２", "大阪市北区梅田3-1-3"] }
```

### Output (one row per address)

| field | example | meaning |
|---|---|---|
| `input` | 千代田区霞ヶ関１－２ | the address as given |
| `normalized` | 東京都千代田区霞が関一丁目2 | full normalized string |
| `prefecture` / `city` / `town` | 東京都 / 千代田区 / 霞が関一丁目 | structured parts |
| `rest` | 2 | block / building part after the town |
| `level` | 3 | 0 = not recognized, 1 = prefecture, 2 = city, 3 = town |
| `lat` / `lng` | 35.6753 / 139.7524 | representative point of the town |
| `cityCode` / `machiazaId` | 131016 / 0002001 | local government code and ABR town ID |
| `error` | null | reason when an address could not be processed |

### Pricing

You pay per successfully processed address, about **$0.50 per 1,000 addresses**. Empty or failed rows are free. The run stops automatically at your spending limit, so a test with a few addresses costs a fraction of a cent.

### FAQ

**Are my addresses sent anywhere?** No. The address data is bundled inside the Actor, so nothing is sent to a third-party API and nothing is stored after the run except your own dataset.

**How do I call it from code or an AI agent?** Use the Apify API or the Apify MCP server with the input shown above; results come back as JSON or CSV from the run's dataset.

**What if an address can't be matched to a town?** You get the deepest level that matched (`level` 1 = prefecture, 2 = city), so you can filter those rows. Rows where not even the prefecture or city could be recognized get an `error` and are free.

### Data sources and credits

- 「アドレス・ベース・レジストリ」（デジタル庁）
- 「位置参照情報」（国土交通省）
- Processed with [Geolonia 住所データ](https://github.com/geolonia/japanese-addresses-v2) (CC BY 4.0) and [normalize-japanese-addresses](https://github.com/geolonia/normalize-japanese-addresses) (MIT) by [Geolonia](https://geolonia.com/).

This Actor is not affiliated with or endorsed by the Digital Agency, MLIT or Geolonia. Results are best-effort and not guaranteed by any of them. The bundled data snapshot is refreshed when a newer release is published.

***

### 日本語の説明

表記ゆれのある日本の住所を、都道府県・市区町村・町字（丁目）に分けて正規化し、緯度経度と自治体コードを付けて返します。顧客名簿の名寄せや住所データの整理に使えます。住所データは Actor 内に同梱しているため、入力した住所が外部に送信されることはありません。

# Actor input Schema

## `addresses` (type: `array`):

Japanese addresses to normalize, one per item. Notation variants (丸ノ内/丸の内, 1丁目/一丁目, full-width digits, missing prefecture) are handled.

## Actor input object example

```json
{
  "addresses": [
    "東京都千代田区丸ノ内1丁目1-1",
    "千代田区霞ヶ関１－２",
    "大阪市北区梅田3-1-3"
  ]
}
```

# Actor output Schema

## `results` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addresses": [
        "東京都千代田区丸ノ内1丁目1-1",
        "千代田区霞ヶ関１－２",
        "大阪市北区梅田3-1-3"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ohs999/jp-address-normalizer").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 = { "addresses": [
        "東京都千代田区丸ノ内1丁目1-1",
        "千代田区霞ヶ関１－２",
        "大阪市北区梅田3-1-3",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("ohs999/jp-address-normalizer").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": [
    "東京都千代田区丸ノ内1丁目1-1",
    "千代田区霞ヶ関１－２",
    "大阪市北区梅田3-1-3"
  ]
}' |
apify call ohs999/jp-address-normalizer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ohs999/jp-address-normalizer"
        }
    }
}
```

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/Rm9jaKDMluQbxehsb/builds/Ut0mP8hyW18AzyV6B/openapi.json