PHPackages                             jpzip/jpzip - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. jpzip/jpzip

ActiveLibrary[Utility & Helpers](/categories/utility)

jpzip/jpzip
===========

jpzip PHP SDK — 日本の郵便番号を CDN 配信の JSON データから引く

v0.1.2(3w ago)01MITPHPPHP ^8.2CI passing

Since May 16Pushed 3w agoCompare

[ Source](https://github.com/jpzip/php)[ Packagist](https://packagist.org/packages/jpzip/jpzip)[ Docs](https://jpzip.nadai.dev)[ RSS](/packages/jpzip-jpzip/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (4)Used By (0)

[![Latest Version on Packagist](https://camo.githubusercontent.com/aa8763886215ff493bb2a270c0eb013e5d9c4e16b695bd76da29b4e94dc0ec56/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a707a69702f6a707a69702e737667)](https://packagist.org/packages/jpzip/jpzip)[![PHP Version Require](https://camo.githubusercontent.com/8e132f77f9da5edb5f5761adfeda04e2bbf3817f06a6cc314527b67b1da4f8ae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6a707a69702f6a707a69702e737667)](https://packagist.org/packages/jpzip/jpzip)[![Docs](https://camo.githubusercontent.com/2d72ac95079309d93654b1fd1a6548f100fe1d24426a22501ae43ae7cd91dbbe/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f63732d6a707a69702e6e616461692e6465762d3030363663632e737667)](https://jpzip.nadai.dev)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](LICENSE)[![Test](https://github.com/jpzip/php/actions/workflows/test.yml/badge.svg)](https://github.com/jpzip/php/actions/workflows/test.yml)

> PHP SDK for **jpzip** — a free, unlimited Japanese postal code (郵便番号) API. 日本の全郵便番号 120,677 件を CDN 配信 JSON から引く PHP SDK。

**English** | [日本語](./README.ja.md)

`jpzip/jpzip` looks up Japanese postal codes (郵便番号) from `jpzip.nadai.dev`, a CDN-hosted dataset built from Japan Post's `KEN_ALL.csv` and `KEN_ALL_ROME.csv`normalized to JSON. No registration, no rate limits, no API key.

- 🇯🇵 **Complete dataset** — 120,677 entries with kanji, kana, romaji, and government codes (JIS X 0401 / 総務省地方公共団体コード)
- ⚡️ **Fast** — L1 LRU + optional L2 persistent cache; `preload()` to serve lookups without per-request network round-trips
- 🛡️ **Resilient** — 3-attempt retry with exponential backoff on 5xx / network failures
- 🐘 **Modern PHP** — PHP 8.2+, strict types, readonly DTOs, named arguments throughout
- 🆓 **Free forever** — backed by Cloudflare Pages' free tier (no billing axis exists)
- 🔌 **Drop-in** — same API surface across [every jpzip SDK](#other-languages)

Requirements
------------

[](#requirements)

- PHP 8.2+
- `ext-json`
- `guzzlehttp/guzzle ^7.8` (transitively pulls `psr/http-message`, `guzzlehttp/promises`, `guzzlehttp/psr7`)

Install
-------

[](#install)

```
composer require jpzip/jpzip
```

Quick Start
-----------

[](#quick-start)

```