# Japan Postal Code & Phone Number Validator (`ohs999/jp-contact-cleaner`) Actor

Validate and clean Japanese customer lists: check that postal codes exist and fill in prefecture / city / town, find the postal code for an address, flag postal code and address mismatches, and format phone numbers with their type (mobile, landline, 050, toll free). No data leaves the run.

- **URL**: https://apify.com/ohs999/jp-contact-cleaner.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 record cleaneds

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 Contact Data Cleaner (郵便番号・電話番号)

Clean the postal codes, addresses and phone numbers in a Japanese customer list in one pass.

- **Postal code lookup and check**: normalizes `１００－０００５` / `1000005` to `100-0005`, says whether the code exists, and returns prefecture / city / town with kana readings (including large-office codes)
- **Address → postal code**: finds the postal code for an address, handling spelling variants such as `霞ヶ関 / 霞が関`, `丸ノ内 / 丸の内`, `1丁目 / 一丁目`, a missing prefecture, or a `字` prefix
- **Mismatch detection**: flags rows where the postal code and the address point to different places (`postalCodeMatchesAddress: false`), a common sign of typos
- **Phone numbers**: formats to `03-1234-5678` and `+81312345678`, and tells landline, mobile, IP phone (050), toll free (0120/0800) and navi dial (0570) apart
- Runs entirely on bundled data, so your records never leave the run and there are no third-party API limits

Typical uses: cleaning CRM or EC customer lists before a mailing, checking form submissions, preparing data for deduplication (名寄せ). Pair it with the Japanese Address Normalizer for full address cleaning.

### Input

```json
{
  "records": [
    { "id": 1, "postalCode": "１００－０００５", "address": "東京都千代田区丸ノ内1丁目1-1", "phone": "03(1234)5678" },
    { "id": 2, "postalCode": "5300001", "address": "千代田区霞が関1-2", "phone": "０９０１２３４５６７８" }
  ]
}
```

Field names can be changed with `postalCodeField`, `addressField` and `phoneField`. Any field can be missing.

### Output (one row per record)

| field | example | meaning |
|---|---|---|
| `input` | `{ "id": 1, ... }` | the record as given |
| `postalCode` / `postalCodeValid` | 100-0005 / true | normalized code and whether it exists |
| `prefecture` / `city` / `town` (+ `…Kana`) | 東京都 / 千代田区 / 丸の内 | place of the postal code |
| `officeName` | null | business name for large-office postal codes |
| `addressPostalCode` | 100-0013 | postal code found for the address (null when several codes are possible) |
| `addressPostalCodeCandidates` | \["100-0013"] | every possible code for the address |
| `addressMatchLevel` | town | `town`, `city`, `prefecture`, `ambiguous` or `none` |
| `postalCodeMatchesAddress` | false | whether the given postal code fits the address (null when it can't be checked) |
| `phoneNational` / `phoneE164` | 090-1234-5678 / +819012345678 | formatted phone number |
| `phoneType` | mobile | `fixed`, `mobile`, `ip`, `toll_free`, `navi_dial`, … |
| `phoneValid` | true | whether the number is a valid phone number |
| `error` | null | set when the record had nothing to clean |

### Pricing

You pay per record that had a postal code, address or phone number to clean, about **$0.50 per 1,000 records**. Records with none of them are free. The run stops automatically at your spending limit, so a test with a few records costs a fraction of a cent.

### FAQ

**Are my records sent anywhere?** No. Postal code data and phone rules are 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 fresh is the postal code data?** Japan Post updates postal codes monthly; this Actor picks up each update automatically after it passes tests.

**Does a valid phone number mean it is in service?** No. The check confirms the number follows Japan's numbering plan and tells you its type; it does not call the number.

**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. Pair it with the Japanese Address Normalizer & Geocoder for full address cleaning.

### Data sources and credits

- 郵便番号データ（日本郵便株式会社）. Japan Post states that it does not claim copyright on the postal code data and that it may be freely redistributed.
- Repackaged by [jpostcode-data](https://github.com/kufu/jpostcode-data) (SmartHR, MIT) and [jpostcode](https://github.com/matzlika/jpostcode-js) (MIT); the bundled data is refreshed monthly.
- Phone number rules from [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js) (MIT), based on Google's libphonenumber.

This Actor is not affiliated with or endorsed by Japan Post, SmartHR or Google. Results are best-effort: a valid phone number format does not mean the number is in service.

***

### 日本語の説明

顧客名簿などの郵便番号・住所・電話番号をまとめて整えます。郵便番号の実在確認と住所の補完、住所からの郵便番号検索、郵便番号と住所の食い違いの検出、電話番号の表記統一と種別（固定・携帯・050・フリーダイヤル・ナビダイヤル）の判定ができます。データは Actor 内に同梱しているため、入力したデータが外部に送信されることはありません。郵便番号データは毎月更新します。

# Actor input Schema

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

List of objects, for example rows of a customer list. Each object can have a postal code, an address and a phone number; any other fields are returned unchanged under "input".

## `postalCodeField` (type: `string`):

Name of the field that holds the postal code (郵便番号).

## `addressField` (type: `string`):

Name of the field that holds the address (住所).

## `phoneField` (type: `string`):

Name of the field that holds the phone number (電話番号).

## Actor input object example

```json
{
  "records": [
    {
      "id": 1,
      "postalCode": "１００－０００５",
      "address": "東京都千代田区丸ノ内1丁目1-1",
      "phone": "03(1234)5678"
    },
    {
      "id": 2,
      "postalCode": "5300001",
      "address": "大阪市北区梅田3-1-3",
      "phone": "０９０１２３４５６７８"
    },
    {
      "id": 3,
      "postalCode": "530-0001",
      "address": "千代田区霞が関1-2",
      "phone": "0120123456"
    }
  ],
  "postalCodeField": "postalCode",
  "addressField": "address",
  "phoneField": "phone"
}
```

# 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 = {
    "records": [
        {
            "id": 1,
            "postalCode": "１００－０００５",
            "address": "東京都千代田区丸ノ内1丁目1-1",
            "phone": "03(1234)5678"
        },
        {
            "id": 2,
            "postalCode": "5300001",
            "address": "大阪市北区梅田3-1-3",
            "phone": "０９０１２３４５６７８"
        },
        {
            "id": 3,
            "postalCode": "530-0001",
            "address": "千代田区霞が関1-2",
            "phone": "0120123456"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ohs999/jp-contact-cleaner").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,
            "postalCode": "１００－０００５",
            "address": "東京都千代田区丸ノ内1丁目1-1",
            "phone": "03(1234)5678",
        },
        {
            "id": 2,
            "postalCode": "5300001",
            "address": "大阪市北区梅田3-1-3",
            "phone": "０９０１２３４５６７８",
        },
        {
            "id": 3,
            "postalCode": "530-0001",
            "address": "千代田区霞が関1-2",
            "phone": "0120123456",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("ohs999/jp-contact-cleaner").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,
      "postalCode": "１００－０００５",
      "address": "東京都千代田区丸ノ内1丁目1-1",
      "phone": "03(1234)5678"
    },
    {
      "id": 2,
      "postalCode": "5300001",
      "address": "大阪市北区梅田3-1-3",
      "phone": "０９０１２３４５６７８"
    },
    {
      "id": 3,
      "postalCode": "530-0001",
      "address": "千代田区霞が関1-2",
      "phone": "0120123456"
    }
  ]
}' |
apify call ohs999/jp-contact-cleaner --silent --output-dataset

```

## MCP server setup

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

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/knr0YIwMT5vdAvz00/builds/p0RFGCUVnFDC92h3y/openapi.json