# Japanese Address & Company Name Normalizer (`kimari-terrace/japanese-address-company-normalizer`) Actor

Normalize messy Japanese company names and addresses into joinable fields. Unifies 株式会社 / (株) / ㈱ and 14 other legal forms, and splits addresses into prefecture, city, town, block and building. Pure computation — no scraping, no API keys.

- **URL**: https://apify.com/kimari-terrace/japanese-address-company-normalizer.md
- **Developed by:** [Kimari Terrace](https://apify.com/kimari-terrace) (community)
- **Categories:** Developer tools, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / 1,000 record 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?

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

## Japanese Address & Company Name Normalizer

Turn messy Japanese company names and addresses into clean, joinable fields.

If you have ever tried to match `㈱アイウエオ` against `株式会社アイウエオ`, or to join
`東京都渋谷区上原３丁目６番１２号` against `東京都渋谷区上原3-6-12`, you know the problem:
the same entity is written a dozen different ways, and a plain string comparison finds none of them.

This Actor splits both into structured parts so the join actually works.

**No network requests.** It is pure computation — nothing is scraped, no third-party site is
called, no API key is needed. That means it cannot break when some website changes its HTML,
and your data never leaves the run.

### What it does

#### Company names

| Input | `normalized` | `corp_form` | `corp_position` | `body` |
|---|---|---|---|---|
| `(株)アイウエオ` | `株式会社アイウエオ` | `株式会社` | `prefix` | `アイウエオ` |
| `アイウエオ㈱` | `アイウエオ株式会社` | `株式会社` | `suffix` | `アイウエオ` |
| `カキク(有)` | `カキク有限会社` | `有限会社` | `suffix` | `カキク` |
| `ＮＰＯ法人タチツ` | `特定非営利活動法人タチツ` | `特定非営利活動法人` | `prefix` | `タチツ` |
| `株式会社髙島屋` | `株式会社高島屋` | `株式会社` | `prefix` | `高島屋` |
| `キマリテラス` | `キマリテラス` | `null` | `null` | `キマリテラス` |

- 15 legal forms are recognised, including the parenthesised and single-character variants
  (`株式会社` / `(株)` / `（株）` / `㈱`), `有限会社`, `合同会社`, `合資会社`, `合名会社`,
  `一般社団法人`, `一般財団法人`, `公益社団法人`, `公益財団法人`, `特定非営利活動法人` (`NPO法人`),
  `医療法人`, `学校法人`, `社会福祉法人`, `宗教法人`, `独立行政法人`.
- **Prefix and suffix position is preserved.** `株式会社アイウエオ` and `アイウエオ株式会社`
  can be two different companies, so they are never collapsed into one value.
- Old-form kanji common in company names are folded to their modern forms
  (`髙→高`, `﨑→崎`, `澤→沢`, `邊/邉→辺`, and 7 more — 12 characters in all).
- Full-width alphanumerics become half-width (`ＡＢＣ` → `ABC`); katakana is left full-width.

#### Addresses

| Input | prefecture | city | town | block | building |
|---|---|---|---|---|---|
| `東京都渋谷区上原３丁目６番１２号` | `東京都` | `渋谷区` | `上原` | `3-6-12` | `null` |
| `東京都渋谷区上原3-6-12` | `東京都` | `渋谷区` | `上原` | `3-6-12` | `null` |
| `神奈川県横浜市西区みなとみらい2-3-1` | `神奈川県` | `横浜市西区` | `みなとみらい` | `2-3-1` | `null` |
| `愛知県名古屋市中村区名駅1-1-4 JRゲートタワー` | `愛知県` | `名古屋市中村区` | `名駅` | `1-1-4` | `JRゲートタワー` |
| `渋谷区上原3-6-12` | `null` | `渋谷区` | `上原` | `3-6-12` | `null` |

- `丁目 / 番 / 号` and `1-2-3` collapse to the same `block` form, so the two spellings join.
- Designated cities keep `市` + `区` together as one unit (`横浜市西区`, not `横浜市`).
- Building names, floors and room numbers are kept in `building`. They are **not** discarded —
  an address without them is not a deliverable address.
- Kanji numerals are converted **only** where they mean a chōme/banchi
  (`丸の内一丁目9番1号` → `丸の内` + `1-9-1`). Place names keep their kanji:
  `四谷` stays `四谷`, not `4谷`; `九段北`, `八重洲`, `三条通`, `北一条西` are likewise untouched.

### What it deliberately does NOT do

Read this before you buy — these are design decisions, not missing features.

- **It never guesses.** Given `渋谷区上原3-6-12` with no prefecture, it returns
  `prefecture: null`. Filling in `東京都` looks helpful until you meet a same-named ward in
  another prefecture and silently corrupt the join. Fields that could not be determined are
  `null`, never an empty string, so you can tell "not present" from "was blank".
- **No validation, no geocoding, no postal codes.** It does not check that an address exists,
  does not return latitude/longitude, and does not look up or verify 郵便番号. It reformats
  what you give it.
- **No corporate registry lookup.** It does not fetch 法人番号 or confirm a company exists.
- **Kanji numerals up to 99.** Enough for chōme/banchi; larger kanji numerals are left alone.
- **Old-form kanji folding is a curated list**, not an exhaustive JIS conversion table.

### Input

```json
{
  "records": [
    { "id": "1", "company": "(株)アイウエオ", "address": "東京都渋谷区上原３丁目６番１２号" },
    { "id": "2", "company": "カキク㈲" },
    { "id": "3", "address": "愛知県名古屋市中村区名駅1-1-4 JRゲートタワー" },
    "キマリテラス"
  ]
}
```

- `company` and `address` are both optional; supply either or both.
- `id` is echoed back untouched so you can join the results to your source rows.
- A plain string is treated as a company name.
- Rows with neither `company` nor `address` are skipped — **and not charged**.
- Up to 100,000 records per run.

### Output

One dataset item per input record:

```json
{
  "id": "1",
  "company": {
    "input": "(株)アイウエオ",
    "normalized": "株式会社アイウエオ",
    "corp_form": "株式会社",
    "corp_position": "prefix",
    "body": "アイウエオ"
  },
  "address": {
    "input": "東京都渋谷区上原３丁目６番１２号",
    "prefecture": "東京都",
    "city": "渋谷区",
    "town": "上原",
    "block": "3-6-12",
    "building": null,
    "normalized": "東京都渋谷区上原3-6-12"
  }
}
```

`input` always carries the original string back, so the output is a complete audit trail on its own.

### Pricing

Pay per event: **$0.50 per 1,000 records normalized.**

You are charged only for records that produced a result. Empty input, malformed rows, and rows
with neither `company` nor `address` cost nothing.

### Typical uses

- Deduplicating a CRM or lead list where the same company was entered several ways.
- Joining two Japanese datasets that were typed by different people.
- Cleaning form submissions before they reach a database.
- Preparing an address column for a mail merge without losing the building name.

# Actor input Schema

## `records` (type: `array`):

Each item is an object with "company" and/or "address" (both optional), plus an optional "id" that is echoed back so you can join the result. A plain string is treated as a company name.

## Actor input object example

```json
{
  "records": [
    {
      "id": "1",
      "company": "(株)アイウエオ",
      "address": "東京都渋谷区上原３丁目６番１２号"
    },
    {
      "id": "2",
      "company": "カキク㈲",
      "address": "神奈川県横浜市西区みなとみらい2-3-1"
    },
    {
      "id": "3",
      "company": "ＮＰＯ法人タチツ",
      "address": "愛知県名古屋市中村区名駅1-1-4 JRゲートタワー"
    },
    {
      "id": "4",
      "company": "株式会社髙島屋",
      "address": "東京都新宿区四谷3-2-1"
    }
  ]
}
```

# Actor output Schema

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

The default dataset: normalized company names and addresses, with the original input echoed back and any field that could not be determined left as null.

# 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 = {
    "records": [
        {
            "id": "1",
            "company": "(株)アイウエオ",
            "address": "東京都渋谷区上原３丁目６番１２号"
        },
        {
            "id": "2",
            "company": "カキク㈲",
            "address": "神奈川県横浜市西区みなとみらい2-3-1"
        },
        {
            "id": "3",
            "company": "ＮＰＯ法人タチツ",
            "address": "愛知県名古屋市中村区名駅1-1-4 JRゲートタワー"
        },
        {
            "id": "4",
            "company": "株式会社髙島屋",
            "address": "東京都新宿区四谷3-2-1"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("kimari-terrace/japanese-address-company-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 = { "records": [
        {
            "id": "1",
            "company": "(株)アイウエオ",
            "address": "東京都渋谷区上原３丁目６番１２号",
        },
        {
            "id": "2",
            "company": "カキク㈲",
            "address": "神奈川県横浜市西区みなとみらい2-3-1",
        },
        {
            "id": "3",
            "company": "ＮＰＯ法人タチツ",
            "address": "愛知県名古屋市中村区名駅1-1-4 JRゲートタワー",
        },
        {
            "id": "4",
            "company": "株式会社髙島屋",
            "address": "東京都新宿区四谷3-2-1",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("kimari-terrace/japanese-address-company-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 '{
  "records": [
    {
      "id": "1",
      "company": "(株)アイウエオ",
      "address": "東京都渋谷区上原３丁目６番１２号"
    },
    {
      "id": "2",
      "company": "カキク㈲",
      "address": "神奈川県横浜市西区みなとみらい2-3-1"
    },
    {
      "id": "3",
      "company": "ＮＰＯ法人タチツ",
      "address": "愛知県名古屋市中村区名駅1-1-4 JRゲートタワー"
    },
    {
      "id": "4",
      "company": "株式会社髙島屋",
      "address": "東京都新宿区四谷3-2-1"
    }
  ]
}' |
apify call kimari-terrace/japanese-address-company-normalizer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kimari-terrace/japanese-address-company-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/pNH6sXInHHNaaqji4/builds/qGazSRbNPvfEZIwUT/openapi.json