DEV Community: ゲン

Japanese Postal Code to Address Auto-Fill, Built From Japan Post's Free Data (No API Key)

ゲン — Sat, 14 Nov 2026 01:22:35 +0000

In Japan, address forms start with the postal code (郵便番号). Users type 7 digits, and the prefecture, city and town fill in by themselves. When a form doesn't do this, Japanese users notice right away — it's one of the clearest signs that a checkout "wasn't made for Japan".

I'm a native Japanese developer and I built a checkout plugin for Japanese online stores, so I've written this feature more than once. You don't need a paid API or a third-party script on your checkout page. Japan Post publishes the data for free, and a small build step turns it into static JSON files.

This post covers the data, its quirks, a build script and the front-end code. (For the rest of a Japanese checkout form — name order, furigana, tax-included prices — see my earlier post: How to Build a Checkout Form That Works in Japan.)

1. The data: one CSV from Japan Post

Japan Post publishes the postal code data on its download page. Use the newer UTF-8, one-record-per-line file, utf_ken_all.zip (about 2 MB zipped). It has been published since the June 2023 update.

Why the newer file:

It's UTF-8. The classic KEN_ALL.CSV is Shift_JIS.
Each postal code is one line. In the classic file, long town names are split across several records, which you have to stitch back together.
Readings are full-width katakana (the classic file uses half-width).

About using it: Japan Post's readme says it does not claim copyright on the postal code data and that it may be freely distributed. Still, read the readme yourself before you ship.

The data is updated monthly, with add/delete diff files each month. More on updating at the end.

2. The columns you need

Each line has 15 columns. A row looks roughly like this:

13101,"100","1000001","トウキョウト","チヨダク","チヨダ","東京都","千代田区","千代田",0,0,0,0,0,0

For auto-fill you only need four of them:

#	Column	Example
3	Postal code (7 digits)	`1000001`
7	Prefecture	東京都
8	City / ward	千代田区
9	Town	千代田

Columns 4–6 are the readings in katakana (handy if you also want furigana for addresses). Column 13 is a flag that means one postal code covers two or more towns — keep that case in mind, it comes back in section 5.

One more thing: open this file in Excel and the postal codes lose their leading zeros (0600042 becomes 600042). Always treat them as strings.

3. The quirks: town names that aren't town names

The town column isn't always a real town. Japan Post's readme lists a few special values:

以下に掲載がない場合 ("if not listed below") — a catch-all code for the city. It does not identify a town.
○○の次に番地がくる場合 — the block number comes directly after the city name.
○○一円 — the whole municipality, with no town name.

Inserting any of these into a user's address is a bug. Clear them instead.

Town names can also have a note in full-width parentheses, such as 大通西（１～１９丁目） ("Ōdōri-nishi, 1st–19th chōme"). The note describes which block numbers belong to the code; the user types their own block number anyway. Keep the part before （:

const cleanTown = (town) => {
  if (town === '以下に掲載がない場合') return '';
  if (/の次に番地がくる場合$/.test(town)) return '';
  if (/一円$/.test(town)) return '';
  return town.replace(/（.*$/, ''); // "大通西（１～１９丁目）" → "大通西"
};

4. Build step: CSV → small JSON files

More than 100,000 lines is too much to send to every visitor. Split the data by the first three digits of the postal code. The browser then loads only the small file it needs, such as /zip/100.json.

// build-zip.mjs
// Usage: node build-zip.mjs utf_ken_all.csv public/zip
import { readFileSync, mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';

const [, , csvPath, outDir] = process.argv;

const cleanTown = (town) => {
  if (town === '以下に掲載がない場合') return '';
  if (/の次に番地がくる場合$/.test(town)) return '';
  if (/一円$/.test(town)) return '';
  return town.replace(/（.*$/, '');
};

// Fields don't contain ASCII commas, so a plain split is enough here.
// Use a CSV library if you want to be extra safe.
const parseLine = (line) => line.split(',').map((f) => f.replace(/^"|"$/g, ''));

const files = {}; // { "100": { "1000001": [["東京都", "千代田区", "千代田"]] } }

for (const line of readFileSync(csvPath, 'utf8').split(/\r?\n/)) {
  if (!line) continue;
  const c = parseLine(line);
  const zip = c[2];
  const entry = [c[6], c[7], cleanTown(c[8])];
  const bucket = (files[zip.slice(0, 3)] ??= {});
  const list = (bucket[zip] ??= []);
  // After cleaning, two rows can become identical — keep one.
  if (!list.some((e) => e.join() === entry.join())) list.push(entry);
}

mkdirSync(outDir, { recursive: true });
for (const [prefix, data] of Object.entries(files)) {
  writeFileSync(join(outDir, `${prefix}.json`), JSON.stringify(data));
}
console.log(`${Object.keys(files).length} files written to ${outDir}`);

Each postal code maps to a list, because one code can cover several towns. Serve the folder as static files — no server code, no API key.

5. The form: fill in, but don't fight the user

The HTML, with autocomplete attributes so browser autofill still works:

<label>郵便番号 <input name="postal_code" autocomplete="postal-code"
  inputmode="numeric" placeholder="123-4567"></label>

<label>都道府県 <select name="prefecture" autocomplete="address-level1">
  <option value="">選択してください</option>
  <option>北海道</option><option>青森県</option><!-- … all 47 … -->
</select></label>
<label>市区町村 <input name="city" autocomplete="address-level2"></label>
<label>町名 <input name="town"></label>
<label>番地 <input name="address_line1" autocomplete="address-line1"></label>
<label>建物名・部屋番号 <input name="address_line2" autocomplete="address-line2"></label>

(Many Japanese forms put the town at the start of the 番地 field instead of a separate field. Either works — keep it consistent with how you store addresses.)

The script:

const form = document.querySelector('form');

// "〒１００－０００１" → "1000001"  (full-width digits, hyphens, the 〒 mark)
const normalizeZip = (v) => v.normalize('NFKC').replace(/[^0-9]/g, '');

const cache = {};
async function lookup(zip) {
  const key = zip.slice(0, 3);
  cache[key] ??= fetch(`/zip/${key}.json`).then((r) => (r.ok ? r.json() : {}));
  return (await cache[key])[zip] ?? [];
}

// Never overwrite what the user typed themselves.
const edited = new Set();
for (const name of ['prefecture', 'city', 'town']) {
  form.elements[name].addEventListener('input', () => edited.add(name));
}

async function fill() {
  const zip = normalizeZip(form.elements.postal_code.value);
  if (zip.length !== 7) return;

  const hits = await lookup(zip);
  if (hits.length === 0) return; // unknown code: leave the fields alone

  const [prefecture, city, town] = hits[0];
  const set = (name, value) => {
    if (!edited.has(name)) form.elements[name].value = value;
  };
  set('prefecture', prefecture);
  set('city', city);
  // One code, several towns: don't guess.
  set('town', hits.length === 1 ? town : '');

  form.elements.address_line1.focus(); // the user continues with the block number
}

form.elements.postal_code.addEventListener('input', fill);

A few choices worth explaining:

Normalize first. Japanese keyboards often type full-width digits (１２３－４５６７). NFKC turns them into 123-4567, then we drop everything that isn't a digit. Don't show an error for full-width input — fix it.
Don't guess when there are several towns. If one code covers two or more towns, fill the prefecture and city only, and let the user type the town (or show the choices in a small list).
Don't overwrite. If the user has already corrected the city, a late lookup shouldn't put the old value back.
Move the cursor to 番地. After the auto-fill, the next thing the user types is the block number.
Unknown code = no change. Large businesses and PO boxes have their own postal codes in a separate Japan Post file, so a valid code can be missing from this data. Don't block the form; let the user type the address.

6. Keep it up to date

Postal codes change a little every month (city mergers, new developments, corrections). The simplest approach: re-download utf_ken_all.zip once a month and run the build again. A scheduled CI job works well for this. If you'd rather apply only the changes, Japan Post also publishes monthly add/delete files.

Checklist

[ ] Use utf_ken_all.zip (UTF-8, one record per line)
[ ] Treat postal codes as strings (leading zeros)
[ ] Clear 以下に掲載がない場合 / ○○の次に番地がくる場合 / ○○一円
[ ] Cut the （…） note from town names
[ ] One code can mean several towns — store a list, don't guess
[ ] Normalize input with NFKC; accept hyphens, full-width digits and 〒
[ ] Never overwrite fields the user edited; focus 番地 afterwards
[ ] Rebuild monthly

Postal-code auto-fill is a small feature, but it's the moment a Japanese user decides whether your form "gets it". The good news: it's an afternoon of work, with no API key and no runtime dependency.

If you're getting a product ready for Japan, there's a free 31-point checklist (language, names, addresses, checkout, layout and store pages): Free Japan-Ready Checklist. And if you'd like a native Japanese developer to look at your actual screens, I do reviews on Fiverr.

Japanese Text Breaks Your App in 7 Quiet Ways (With Code)

ゲン — Fri, 13 Nov 2026 22:40:08 +0000

Your app passes every test in English. Then a Japanese user types their name, presses Enter, and the form submits half a word.

Japanese text breaks a lot of quiet assumptions: that words have spaces, that length counts characters, that Enter means "send", that sorting by string sorts by sound. None of these show up as errors. They just make the app feel slightly broken to Japanese users.

I'm a native Japanese developer. Here are the seven I see most, with code you can copy. (In part 1 I covered checkout forms: names, furigana, addresses and prices.)

1. Enter during IME input is not "send"

Japanese is typed through an IME (input method). You type kaigi, see かいぎ, press Space to convert it to 会議, then press Enter to confirm the conversion. If your chat box or search field sends on Enter, it sends the half-finished text.

This is the most common bug I see in chat apps, comment boxes and to-do apps built outside Japan.

input.addEventListener('keydown', (e) => {
  if (e.key !== 'Enter') return;
  // Enter while converting Japanese text: let the IME handle it
  if (e.isComposing || e.keyCode === 229) return;
  e.preventDefault();
  send(input.value);
});

isComposing is true while the IME is converting. The keyCode === 229 check covers older Safari, which fires the confirming Enter after composition has already ended.

React users: check e.nativeEvent.isComposing.

2. `length` doesn't count characters

'𠮷野家'.length;        // 4  (𠮷 is outside the BMP: 2 UTF-16 units)
[...'𠮷野家'].length;   // 3  (code points)

Code points still aren't what a user calls "one character". Emoji with joiners are several code points:

const seg = new Intl.Segmenter('ja', { granularity: 'grapheme' });

[...'👨‍👩‍👧家族'].length;               // 7
[...seg.segment('👨‍👩‍👧家族')].length;   // 3  ← what the user sees

So when you cut text to fit ("max 20 characters", previews, notifications), cut by graphemes, or you'll slice a character in half and show a broken symbol:

const truncate = (text, max) => {
  const chars = [...seg.segment(text)].map((s) => s.segment);
  return chars.length > max ? chars.slice(0, max).join('') + '…' : text;
};

truncate('𠮷野家の牛丼👨‍👩‍👧をみんなで', 8); // "𠮷野家の牛丼👨‍👩‍👧を…"

Also: Japanese is dense. 20 Japanese characters say roughly what 40–60 English characters say. A limit that's fine in English can be roomy in Japanese — but each character is about twice as wide, so the pixel width often grows. Don't give buttons a fixed width tuned for English.

3. Line breaks: no spaces, and some characters can't start a line

Japanese has no spaces between words, so browsers may break a line between any two characters — including in the middle of a word.

Two CSS properties help:

:lang(ja) {
  line-break: strict;        /* never start a line with 。、ー or small kana like ゃ */
  word-break: auto-phrase;   /* break between phrases, not inside words (Chrome/Edge 119+) */
}

.title, .button-label {
  text-wrap: balance;        /* evens out short headings */
}

auto-phrase only works when the element is marked lang="ja", and browsers that don't support it simply keep the normal behaviour, so it's safe to add.

For headings, the most reliable fix is still to keep them short enough to fit on one line on a phone.

4. Don't build sentences by joining strings

Word order is different. English puts the verb first; Japanese puts it last:

English	Japanese
Delete 3 files?	3件のファイルを削除しますか？
Sent to Yamada	山田様に送信しました

So this can't be translated:

// ❌ the translator only sees fragments
t('delete') + ' ' + count + ' ' + t('files') + '?'

Give the translator the whole sentence with a placeholder:

// ✅
const messages = {
  en: { confirmDelete: 'Delete {count} files?' },
  ja: { confirmDelete: '{count}件のファイルを削除しますか？' },
};

Plurals are simpler in Japanese — there's only one form:

new Intl.PluralRules('en').select(1); // "one"
new Intl.PluralRules('ja').select(1); // "other"
new Intl.PluralRules('ja').select(2); // "other"

But Japanese uses counters instead: 3*件* (items, results), 3*個* (objects), 3*人* (people), 3*枚* (flat things like tickets). The counter belongs to the noun, so keep it inside the translated string, not in your code.

Lists, too:

new Intl.ListFormat('ja', { type: 'conjunction' })
  .format(['りんご', 'みかん', 'ぶどう']); // "りんご、みかん、ぶどう"

5. Sorting names by string doesn't sort by sound

Intl.Collator('ja') sorts hiragana and katakana together in あいうえお order:

['リンゴ', 'あめ', 'かさ', 'イチゴ', 'ばなな', 'さくら']
  .sort(new Intl.Collator('ja').compare);
// ["あめ", "イチゴ", "かさ", "さくら", "ばなな", "リンゴ"]  ✅

But kanji don't carry their reading. Sorting kanji names gives an order no Japanese person would expect:

['山田', '佐藤', '鈴木', '田中'].sort(new Intl.Collator('ja').compare);
// ["佐藤", "山田", "田中", "鈴木"]
// expected (by reading): 佐藤 (さとう), 鈴木 (すずき), 田中 (たなか), 山田 (やまだ)

This is why Japanese forms ask for the name's reading (furigana). If you list people or customers, sort by the reading field, not the name.

6. Search: make hiragana, katakana and half-width match

The same word can be typed in several ways: やまだ, ヤマダ, ﾔﾏﾀﾞ (half-width). Users expect search to find all of them. Normalize both the query and the data the same way:

const toKatakana = (s) =>
  s.replace(/[ぁ-ゖ]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 0x60));

const fold = (s) => toKatakana(s.normalize('NFKC').toLowerCase());

fold('ﾔﾏﾀﾞ') === fold('やまだ'); // true  (both become "ヤマダ")
fold('ＡＢＣ１２３');             // "abc123"

NFKC turns half-width katakana and full-width letters into their normal forms; the second step folds hiragana into katakana.

For splitting text into words (search indexing, highlighting), Intl.Segmenter works for Japanese too:

const words = new Intl.Segmenter('ja', { granularity: 'word' });
[...words.segment('今日は東京で会議があります')]
  .filter((s) => s.isWordLike)
  .map((s) => s.segment);
// ["今日", "は", "東京", "で", "会議", "が", "あり", "ます"]

It's not as good as a real Japanese tokenizer, but it's built in and much better than splitting on spaces (there are none).

7. The same character can look Chinese

Chinese and Japanese share many characters with the same Unicode code point, but the shapes differ slightly (直, 骨, 角, 写 are classic examples). If the font is chosen for Chinese, Japanese readers notice — it looks like a typo.

The fix is to tell the system the text is Japanese:

<html lang="ja">

:lang(ja) {
  font-family: "Hiragino Sans", "Noto Sans JP", "Yu Gothic UI", "Yu Gothic", sans-serif;
}

On mobile, the same idea: set the app or view's locale to Japanese when showing Japanese, and in games, make sure the font you ship is a Japanese font (Noto Sans JP is free), not a Chinese one.

Mixed content is the tricky case — for example, a Chinese user's comment shown inside a Japanese page. Mark it with its own lang attribute if you know it.

Checklist

[ ] Enter during IME conversion doesn't send (isComposing)
[ ] Character limits and truncation count graphemes (Intl.Segmenter)
[ ] line-break: strict and word-break: auto-phrase on Japanese text; no fixed-width buttons
[ ] Whole sentences with placeholders; counters inside the translation
[ ] People sorted by reading, not by kanji
[ ] Search folds hiragana / katakana / half-width (NFKC)
[ ] lang="ja" and a Japanese font

None of this is translation. Your Japanese text can be perfect and the app can still feel "not made for here" because of these seven. The good news is they're all small fixes.

If you want the full list, there's a free printable Japan-Ready Checklist (31 points across language, names, addresses, checkout, layout and store pages). And if you'd like a native Japanese developer to go through your actual screens, I do Japan-ready reviews on Fiverr.

How to Build a Checkout Form That Works in Japan (With Code)

ゲン — Fri, 13 Nov 2026 11:17:52 +0000

Adding Japanese to your app is mostly a translation job. Making your sign-up and checkout forms work for Japanese users is not — it's a form-design job, and it's where many products quietly lose Japanese customers.

I'm a native Japanese developer. I built and published a checkout plugin for Japanese online stores, so I've spent a lot of time on these fields. Here's what to change, with code you can copy.

1. Name: family name first, in two fields

Japanese names are written family name first: 山田太郎 = Yamada (family) Taro (given). Japanese forms ask for 姓 (family name), then 名 (given name).

<div class="name-row">
  <label>姓 <input name="family_name" autocomplete="family-name" required></label>
  <label>名 <input name="given_name" autocomplete="given-name" required></label>
</div>

Store them separately, and print them family-name-first everywhere: emails, receipts, shipping labels.

2. Furigana: the reading of the name

Kanji names can often be read several ways, so Japanese forms ask for the reading in katakana (フリガナ). Shops use it for phone calls, sorting customers and delivery slips.

<div class="name-row">
  <label>セイ <input name="family_name_kana" pattern="[ァ-ヶー　 ]+" required></label>
  <label>メイ <input name="given_name_kana" pattern="[ァ-ヶー　 ]+" required></label>
</div>

The pattern accepts full-width katakana, the long-vowel mark (ー) and spaces. Many users type hiragana by mistake, so a friendly error helps (see section 6) — or convert hiragana to katakana for them.

3. Address: postal code first, large to small

Japanese addresses go from large to small:
postal code → prefecture → city → town and block number → building and room.

<label>郵便番号 <input name="postal_code" autocomplete="postal-code"
  inputmode="numeric" placeholder="123-4567"></label>
<button type="button" id="fill-address">住所を自動入力</button>

<label>都道府県 <select name="prefecture" autocomplete="address-level1">
  <option value="">選択してください</option>
  <option>北海道</option><option>青森県</option><!-- … all 47, in the standard order … -->
</select></label>
<label>市区町村 <input name="city" autocomplete="address-level2"></label>
<label>番地 <input name="address_line1" autocomplete="address-line1"></label>
<label>建物名・部屋番号 <input name="address_line2" autocomplete="address-line2"></label>

Japanese users expect the address to fill in from the 7-digit postal code. Japan Post publishes the postal code data for free, so you can build the lookup yourself or use a library that wraps it. Keep building and room on its own line — a lot of people live in apartments.

4. Accept full-width input (and fix it quietly)

Japanese keyboards often type full-width characters: １２３－４５６７ instead of 123-4567. Don't reject it — normalize it:

const clean = (value) => value.normalize('NFKC').trim();

clean('１２３－４５６７'); // "123-4567"
clean('ｶﾀｶﾅ');            // "カタカナ" (half-width katakana → full-width)

Do the same for phone numbers, and accept them with or without hyphens (090-1234-5678 / 09012345678).

5. Prices: say that tax is included

Japanese shoppers are used to tax-included prices, marked 税込. Show it, and show the shipping fee before the last step.

const yen = new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' });

`合計（税込）${yen.format(3300)}`; // "合計（税込）￥3,300"

Note that ja-JP formats the yen sign as full-width ￥. That's fine — it's what Japanese sites show.

6. Words: polite, consistent, not literal

Most of the "this was machine-translated" feeling comes from a handful of strings. A few I see again and again:

English	Literal (avoid)	What Japanese sites say
Place order	注文を置く	注文を確定する
Submit	提出する	送信する
Your information	あなたの情報	お客様情報
Invalid input	無効な入力	入力内容をご確認ください。
ZIP code	ZIPコード	郵便番号

Keep the polite form (です／ます) everywhere, and write errors as a polite request rather than a judgement:

const messages = {
  required: '入力してください。',            // "Please fill this in."
  kana: '全角カタカナで入力してください。',    // "Please use full-width katakana."
  postal: '郵便番号は7桁で入力してください。', // "Please enter a 7-digit postal code."
};

7. Dates and fonts

Japanese dates go year → month → day:

new Intl.DateTimeFormat('ja-JP', {
  year: 'numeric', month: 'long', day: 'numeric', weekday: 'short',
}).format(new Date(2026, 10, 20)); // "2026年11月20日(金)"

And tell the browser your Japanese pages are Japanese. Without it, some kanji can be drawn with a Chinese font, and a few characters look subtly wrong to Japanese readers:

<html lang="ja">

:lang(ja) {
  font-family: "Hiragino Sans", "Noto Sans JP", "Yu Gothic UI", "Yu Gothic", sans-serif;
}

Checklist

[ ] 姓 → 名, two fields, printed family-name-first
[ ] フリガナ (セイ／メイ) in katakana
[ ] 郵便番号 first, auto-fill, prefecture drop-down, building/room on its own line
[ ] Full-width input normalized with NFKC; phone with or without hyphens
[ ] 税込 prices, shipping shown before the last step
[ ] Polite, consistent wording; no literal translations
[ ] Japanese date format, lang="ja", Japanese font

None of this is about translation. A product can have perfect Japanese text and still feel "made for somewhere else" because of the form. The good news: these are small changes.

I wrote a less technical version of this for product people on Medium: 7 Mistakes Foreign Developers Make When Launching in Japan.

There's also a free, printable checklist with 31 points (language, names, addresses, checkout, layout and store pages): Free Japan-Ready Checklist. And if you'd like a native Japanese developer to look at your actual screens, I do reviews.

Not legal advice — if you sell to customers in Japan, check the legal requirements for your business with a professional.

DEV Community: ゲン

Japanese Postal Code to Address Auto-Fill, Built From Japan Post's Free Data (No API Key)

1. The data: one CSV from Japan Post

2. The columns you need

3. The quirks: town names that aren't town names

4. Build step: CSV → small JSON files

5. The form: fill in, but don't fight the user

6. Keep it up to date

Checklist

Japanese Text Breaks Your App in 7 Quiet Ways (With Code)

1. Enter during IME input is not "send"

2. length doesn't count characters

3. Line breaks: no spaces, and some characters can't start a line

4. Don't build sentences by joining strings

5. Sorting names by string doesn't sort by sound

6. Search: make hiragana, katakana and half-width match

7. The same character can look Chinese

Checklist

How to Build a Checkout Form That Works in Japan (With Code)

1. Name: family name first, in two fields

2. Furigana: the reading of the name

3. Address: postal code first, large to small

4. Accept full-width input (and fix it quietly)

5. Prices: say that tax is included

6. Words: polite, consistent, not literal

7. Dates and fonts

Checklist

2. `length` doesn't count characters