Usage

Simplest example

import { createLocalGovClient } from "@b4moss/jp-local-gov-id";
import dataset from "@b4moss/jp-local-gov-id-data";

const client = await createLocalGovClient({ data: dataset });

client.listPrefectures();
client.getPrefectureByCode("27"); // Osaka
client.getPrefectureCodeByName("大阪府"); // "27"
client.getMunicipalityCountByPrefecture("01"); // sync; no municipality load
await client.listMunicipalitiesByPrefecture("13");
await client.getMunicipalityByCode("131016"); // Chiyoda
await client.searchByText("中央", { prefecture: "01", target: "cities" });
await client.getLocalGovCodeByName("千代田区"); // "131016"

Designated-city filter

Applies to listMunicipalitiesByPrefecture / searchByText / getLocalGovCodeByName / getMunicipalityCountByPrefecture. Tokyo special wards are unaffected.

Is the data huge? — Split + Brotli + index

This is not the old multi-hundred-KB JSON dump.

• npm ships .bin.br (Brotli) only, split by prefecture plus search-index shards
• Init loads index.json + prefectures only (~1 KB Brotli for prefectures)
• Nationwide search uses a hybrid JLIX index, then loads only candidate prefectures
• Avoid bundling dataset.js into SPAs — prefer url + static copy

Vite

import { defineConfig } from "vite";
import { viteStaticCopy } from "vite-plugin-static-copy";
export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: [
            "node_modules/@b4moss/jp-local-gov-id-data/index.json",
            "node_modules/@b4moss/jp-local-gov-id-data/prefectures.bin.br",
            "node_modules/@b4moss/jp-local-gov-id-data/prefectures",
            "node_modules/@b4moss/jp-local-gov-id-data/search-ngrams",
          ],
          dest: "jp-local-gov-id-data",
        },
      ],
    }),
  ],
  optimizeDeps: { exclude: ["@b4moss/jp-local-gov-id-data"] },
});

const client = await createLocalGovClient({
  url: "/jp-local-gov-id-data/index.json",
});

CDN / self-host

const client = await createLocalGovClient({
  url: "https://cdn.jsdelivr.net/npm/@b4moss/jp-local-gov-id-data@1.0.0/index.json",
});

Use a versioned URL (cache keys are URLs).

• url mode caches decoded objects in localStorage via @b4moss/cachian (minified JSON) — separate from on-wire .bin.br
• Clear with await client.purgeCache({ all: true }) (or { keys }, etc.)
• Nationwide search municipality loads and JLIX stay memory-only
• After normalize: length < 2 → empty; length 2 → hot 2-gram only; length ≥ 3 → merge 2-gram + 3-gram
• As of 1.2.0, search and cachian stay behind dynamic import (initial minify ≈ 24339 bytes)

Data layout

See API and Playground for more.