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:

{
  "records": [
    {"postalCode":"100-0001","address":"東京都千代田区千代田1-1"},
    {"postalCode":"100-0002"},
    {"postalCode":"9999999"}
  ]
}

A response can contain:

{
  "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.