DOCS · spec v1.0

jpzip プロトコル

CDN とクライアント (SDK) 間の契約。この仕様を実装すれば任意の言語/環境で SDK を作れます。

配信元 · https://jpzip.nadai.dev · 形式 · JSON (UTF-8, gzip/brotli 透過) · 認証 · なし · CORS · *

概要

jpzip は静的 JSON ファイル群を Cloudflare Pages 配下で配信します。クライアント (SDK) は HTTPS GET でファイルを取得し、必要なエントリを抽出します。

項目値
更新頻度月 2 回 (1 日 / 15 日 JST 03:00)
spec_version1.0
Cache-Controlpublic, max-age=86400
データ件数約 12 万件 (毎月変動)

インストール

# npm
npm i jpzip

# Go
go get github.com/jpzip/go

60 秒クイックスタート

SDK 経由なら最小 3 行。エンドポイントを直接叩きたい場合は fetch 1 回で済みます。

import { lookup } from "jpzip";

const e = await lookup("2310831");
console.log(e.prefecture, e.city, e.towns[0].town);
// 神奈川県 横浜市中区 矢口台

エンドポイント

4 種類のレスポンスを返します。zipcode の前方一致でグループ化された辞書なので、必要な粒度を選択できます。

パス内容サイズ目安
/meta.jsonバージョン & 統計~10 KB
/g/{1}.json1 桁プレフィックスの全エントリ3〜4 MB
/p/{3}.json3 桁プレフィックスの全エントリ~10 KB

/meta.json

SDK は起動時に取得してバージョンを確認することが推奨されます。

{
  "version": "2026-05",
  "generated_at": "2026-05-15T17:39:46Z",
  "spec_version": "1.0",
  "total_zipcodes": 120677,
  "prefix_count": 948,
  "by_pref": { "01": 7974, ... },
  "data_source": "https://...",
  "endpoints": { "group": ..., "prefix": ... }
}

/g/{prefix1}.json

1 桁プレフィックスでまとめた辞書。{prefix1} は 0–9 の 1 文字。SDK が全件 preload する際にも使われます。

/p/{prefix3}.json

3 桁プレフィックスでまとめた辞書。/p/{zipcode[:3]}.json を取れば該当 zipcode の辞書が手に入り、転送量も最小です。 実在しない prefix は 404（SDK は「該当なし」として扱う）。 

curl https://jpzip.nadai.dev/p/231.json \
  | jq '."2310831"'

スキーマ

すべての辞書ファイルは zipcode をキーとするフラットな辞書です。値は ZipcodeEntry 型。

ZipcodeEntry

{
  "prefecture":      "神奈川県",
  "prefecture_kana": "カナガワケン",
  "prefecture_roma": "Kanagawa",
  "prefecture_code": "14",
  "city":            "横浜市中区",
  "city_kana":       "ヨコハマシナカク",
  "city_roma":       "Yokohama Shi Naka Ku",
  "city_code":       "14104",
  "towns": [
    { "town": "矢口台", "kana": "ヤグチダイ", "roma": "Yaguchidai" }
  ]
}
フィールド型備考
prefecture_codestring (2桁)JIS X 0401
city_codestring (5桁)総務省地方公共団体コード
townsarray同一 zipcode に複数町域あり (例: 京都の通り名)
towns[].notestring?「以下に掲載がない場合」等の特記

Meta スキーマ

JSON Schema は jpzip/spec 配下にあります。

SDK

各言語の SDK が提供する関数は共通です。

関数説明
lookup(zip)単一 zipcode を引く。不一致は null
lookupGroup(prefix)1〜3 桁 prefix 配下を返す
lookupAll()全件辞書。内部で /g/0..9 を並列 fetch
preload(scope)事前ロードしてオフライン動作
getMeta()バージョン情報の取得

JavaScript / TypeScript

import { JpzipClient } from "jpzip";

const client = new JpzipClient();
const e = await client.lookup("1500001");

// 全件 preload (g/0-9 を並列 fetch)
await client.preload({ scope: "all" });

Go

import "github.com/jpzip/go"

c := jpzip.New()
e, err := c.Lookup(ctx, "1500001")
// → e.Prefecture, e.City, e.Towns[0].Town

キャッシュ戦略

SDK は 3 層キャッシュを区別して管理します。

層目的デフォルト
L1: メモリ LRU同一プロセス内の重複 fetch 抑制常時 ON
L2: 永続キャッシュpreload / 起動高速化OFF (ユーザー有効化)
L3: HTTP / fetchブラウザ・OS レベルCache-Control 準拠

月次のデータ更新は /meta.json の version 変化で検知し、L1/L2 を自動 invalidate します。

ライセンス

  • 仕様書 / SDK / ETL: MIT
  • 配信データ: Public Domain 相当 (元データは日本郵便)

商用利用・再配布・改変、いずれも自由です。