zipcloud (Japan Post) API

Free Japanese postal code API with no key: turn a 7-digit yubin bango into prefecture, city and town, with kana readings for form auto-fill. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the zipcloud (Japan Post) API?

Zipcloud is a free, key-free API that resolves a seven-digit Japanese postal code into its prefecture, city and town, returning each in kanji and in half-width katakana. It wraps the Japan Post KEN_ALL dataset, which it refreshes as Japan Post publishes updates.

Japanese address forms conventionally ask for a reading as well as the address itself, because kanji place names have multiple valid pronunciations and sorting or phone-based lookup depends on the reading. Zipcloud is one of the few free services that returns both, which is why it turns up in so many Japanese e-commerce front ends.

The kana comes back as half-width katakana — ｺｳﾁｹﾝ rather than コウチケン — which is what legacy Japanese business systems expect and what many payment gateways still require. If your interface wants full-width, convert it, but do not assume the API got it wrong. Note too that the HTTP status and the `status` field in the body are separate: a code that does not exist still returns HTTP 200, with `results` set to null and an explanatory `message`.

Quick facts

Base URL: https://zipcloud.ibsnet.co.jp/api
Authentication: No key or registration. Free for commercial use; the operator asks that you cache rather than re-query the same code repeatedly.
Rate limit: No published numeric limit, but the service is small and asks for restraint. Cache results — postal codes change only when Japan Post revises them.
Pricing: Free.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the zipcloud (Japan Post) API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Resolve a Japanese postal code to prefecture, city and town

GET https://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060

curl

curl 'https://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060'

JavaScript (fetch)

const res = await fetch("https://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200

{
  "message": null,
  "results": [
    {
      "address1": "高知県",
      "address2": "南国市",
      "address3": "蛍が丘",
      "kana1": "ｺｳﾁｹﾝ",
      "kana2": "ﾅﾝｺｸｼ",
      "kana3": "ﾎﾀﾙｶﾞｵｶ",
      "prefcode": "39",
      "zipcode": "7830060"
    }
  ],
  "status": 200
}

Parameters

Parameter	Type	Required	Description
`zipcode`	query	Required	Seven-digit postal code, with or without the hyphen. `7830060`
`callback`	query	Optional	Function name for a JSONP response, for pages that cannot use CORS. `handler`
`limit`	query	Optional	Maximum results, 1 to 20. Defaults to 20. Some codes cover several towns. `5`

Response fields

statusinteger: Application-level status inside the body. 200 means the lookup ran; it does not mean a match was found.
messagestring: Null on success, or an explanation in Japanese when the lookup failed.
resultsarray: Matches, or null when the code does not exist. A single code can map to several towns.
results[].zipcodestring: The postal code, digits only, no hyphen.
results[].address1string: Prefecture in kanji, for example 高知県.
results[].address2string: City, ward, town or village in kanji.
results[].address3string: Town or district level in kanji.
results[].kana1 / kana2 / kana3string: Half-width katakana readings of the three address levels, for form auto-fill and sorting.
results[].prefcodestring: Prefecture code, 1 to 47, as used by JIS X 0401.

What you can build with the zipcloud (Japan Post) API

Auto-fill a Japanese address form from a postal code
Populate the furigana fields most Japanese checkouts require
Validate that a postal code and prefecture entered by a customer agree
Group orders or customers by prefecture code for shipping bands
Normalise inconsistent address strings in an existing customer database

Common errors and how to fix them

`results` is null with status 200

The postal code is well formed but not in the register.

Fix: Test `results` for null rather than checking the HTTP status. The `message` field carries the reason in Japanese.

status 400 in the body

The zipcode parameter is missing or is not seven digits.

Fix: Strip hyphens and any full-width digits before sending. Full-width numerals are common in Japanese input and are not accepted.

Several results for one code

Not an error — some codes cover multiple towns.

Fix: Present the list for the user to choose from, or use `limit` to bound it. Silently taking the first entry produces wrong addresses.

Kana looks corrupted

It is half-width katakana, which some fonts and encodings render badly.

Fix: Read the response as UTF-8 and convert to full-width if your interface needs it. The data itself is correct.

zipcloud (Japan Post) API — frequently asked questions

Is the zipcloud API free?

Yes, free with no key or registration, and usable commercially. It is a small volunteer-operated service, so cache results rather than re-querying the same codes.

Why is the kana in half-width katakana?

Because that is how Japan Post publishes the source data, and it is what legacy Japanese business systems and many payment gateways expect. Convert to full-width in your interface if you prefer, but the API is faithful to the source.

Can one postal code return several addresses?

Yes. Some codes cover more than one town, so `results` is always an array. Show the options rather than assuming the first is correct.

How current is the data?

It tracks Japan Post's KEN_ALL file, which is republished monthly. Postal code changes in Japan are infrequent, so caching for weeks at a time is safe.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

CSV to JSON Converter

Convert CSV to a JSON array of objects online. Header-row detection, comma/semicolon/tab delimiters and pretty-printed output — 100% in your browser.

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

zipcloud (Japan Post) is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.