# Japan Postal Ambiguity & Address Checker (`chappy.works/japan-postal-ambiguity-checker`) Actor Check 1-500 Japanese postal codes for ambiguity and town-level address mismatches with Japan Post 2026-10-30 reference data. Not a delivery-address verifier. - **URL**: https://apify.com/chappy.works/japan-postal-ambiguity-checker.md - **Developed by:** [chappy.works](https://apify.com/chappy.works) (community) - **Categories:** Developer tools, Automation, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $2.00 / 1,000 postal code checks 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 ## Japan Postal Ambiguity Checker 🇯🇵 > Updated and verified: Japan Post 2026-10-30 reference. **Catch ambiguous Japanese postal codes before automations guess the wrong town.** Supply a Japanese 7-digit postcode and optionally an address. Get structured town-level candidates and a review flag based on Japan Post's published UTF-8 reference data. For AI agents, checkout data cleanup, and import/CRM pipelines. #### What the Actor does - Normalizes full-width digits, whitespace, and hyphens in postcodes. - Detects one-to-many postcode-to-town mappings and official multi-town flags. - Compares an optional address against municipality/town names, without claiming street-level certainty. - Flags cases for human review instead of silently picking a guessed address. - Processes **1–500 records per run** and returns structured JSON. #### Try a small batch Open the Apify Store page and select **Try for free**. Apify currently lists a Free plan with **$5/month of prepaid Store/platform usage**; actual access, limits, and credits depend on your own account. Start with 2–3 test records and review the event estimate before scaling. Input: ```json { "records": [ {"postalCode":"100-0001","address":"東京都千代田区千代田1-1"}, {"postalCode":"100-0002"}, {"postalCode":"9999999"} ] } ``` A response can contain: ```json { "postal_code":"1000001", "status":"AREA_MATCH", "needs_review":false, "candidate_count":1, "ambiguous_postal_code":false, "candidates":[{"prefecture":"東京都","city":"千代田区","town":"千代田"}], "data_version":"2026-10-30", "reason":"Input matches one town candidate; address precision still unverified", "input_index":0 } ``` #### Read the results correctly Possible decisions are `SINGLE_TOWN`, `AMBIGUOUS`, `AREA_MATCH`, `NEEDS_REVIEW`, `NOT_FOUND`, and `INVALID_ZIP`. A non-review result means no known postcode/town ambiguity was found under the Actor's rules, **not** that a street address, building, resident, or successful delivery is verified. Incomplete and special-purpose addresses can need extra checks. #### Pricing This Actor currently uses **Apify Pay Per Event**. The `postal-check` event costs **USD $0.002 per charged postcode result**, or **USD $2.00 per 1,000 charged events**. One run accepts 1–500 records. Invalid input format results (`INVALID_ZIP` or `INVALID_INPUT`) are returned without the Actor's `postal-check` charge. A syntactically valid but unknown postcode is still processed as a charged result. Review your Apify run cost estimate and spending limit before larger runs. No promise is made about actual free-plan eligibility or total future cost. #### Data freshness and maintenance - **Reference source:** Japan Post nationwide one-record-per-line UTF-8 postal-code CSV. - **Bundled data date:** 2026-10-30. - **Last official publication-date check:** 2026-11-02 (JST). Japan Post listed 2026-10-30 as the source publication date in the verified staging receipt. - **Current runtime behavior:** after starting, the Actor checks against bundled data; it does **not** download or automatically deploy new postal datasets during a run. - **Maintenance policy:** new data is verified before a separately approved release. Last check date and data release date are different. The `data_version` field identifies the bundled reference data's declared version, not the current wall-clock date. - **Published source integrity:** Japan Post 2026-10-30 CSV SHA-256 `33a3a1e14a69778282cfb22c17ba0b5f888669d091ada93e1ba960f259f6b2d5`, 124,527 records. The updated source was verified in a successful Apify cloud run on 2026-11-02. Official source: https://www.post.japanpost.jp/service/search/zipcode/download/utf-zip.html #### Limits and scope - Maximum 500 records per run, 30 candidate towns shown per result; `candidates_truncated` reports omitted candidates. - No personal names or sensitive personal information should be submitted. - This is a reference-data plausibility check, not address deliverability verification. - Independently developed; not affiliated with or endorsed by Japan Post. No authenticated Digital Address API access. #### Working with AI agents Call through Apify API or compatible MCP integration. Send postcode(s), inspect `status`, `needs_review` and `ambiguous_postal_code`, and ask for human confirmation when uncertain. Never infer a street-level address from a town-level match. # Actor input Schema ## `records` (type: `array`): 1 to 500 items. Each has postalCode (seven digits, hyphen optional) and optional address. Do not include resident names. ## Actor input object example ```json { "records": [ { "postalCode": "100-0001", "address": "東京都千代田区千代田" }, { "postalCode": "100-0002" } ] } ``` # Actor output Schema ## `results` (type: `string`): Machine-readable town-level ambiguity decisions # 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 = { "records": [ { "postalCode": "100-0001", "address": "東京都千代田区千代田" }, { "postalCode": "100-0002" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("chappy.works/japan-postal-ambiguity-checker").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 = { "records": [ { "postalCode": "100-0001", "address": "東京都千代田区千代田", }, { "postalCode": "100-0002" }, ] } # Run the Actor and wait for it to finish run = client.actor("chappy.works/japan-postal-ambiguity-checker").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": [ { "postalCode": "100-0001", "address": "東京都千代田区千代田" }, { "postalCode": "100-0002" } ] }' | apify call chappy.works/japan-postal-ambiguity-checker --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,chappy.works/japan-postal-ambiguity-checker" } } } ``` 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/eucAa1KFhHhu5BzGk/builds/ldwaOXzFun2kUXz69/openapi.json