PHPackages scarneros/laravel-japan-postal-codes - 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. scarneros/laravel-japan-postal-codes ActiveLibrary[Utility & Helpers](/categories/utility) scarneros/laravel-japan-postal-codes ==================================== Laravel package for looking up Japanese addresses by postal code. Supports kanji, kana and romaji, full-width character normalization, CSV imports from Japan Post, and an optional JSON API. v0.1.3(1mo ago)1396MITPHPPHP ^8.2CI passing Since Jun 11Pushed 1mo agoCompare [ Source](https://github.com/scarneros/laravel-japan-postal-codes)[ Packagist](https://packagist.org/packages/scarneros/laravel-japan-postal-codes)[ RSS](/packages/scarneros-laravel-japan-postal-codes/feed)WikiDiscussions main Synced 1w ago READMEChangelog (1)Dependencies (12)Versions (5)Used By (0) Laravel Japan Postal Codes ========================== [](#laravel-japan-postal-codes) [![Latest Version](https://camo.githubusercontent.com/592b6b99bc98ef4fbfb8f2d3bbc23b26047622d07b796e73b6db5b16bf840091/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736361726e65726f732f6c61726176656c2d6a6170616e2d706f7374616c2d636f6465732e737667)](https://packagist.org/packages/scarneros/laravel-japan-postal-codes)[![Tests](https://github.com/scarneros/laravel-japan-postal-codes/actions/workflows/tests.yml/badge.svg)](https://github.com/scarneros/laravel-japan-postal-codes/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/2a5b1af7425b2c8b7071556a5cb33a24879e21806e211e1c3ab36c00daf788a5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f736361726e65726f732f6c61726176656c2d6a6170616e2d706f7374616c2d636f646573)](LICENSE) Look up Japanese addresses by postal code. Returns **kanji**, **kana** and **romaji**. Supports full‑width character normalization, CSV imports from [Japan Post](https://www.post.japanpost.jp/service/search/zipcode/download/readme.html), and an optional JSON API. --- Requirements ------------ [](#requirements) - **PHP** 8.2+ with `ext-mbstring` and `ext-zip` - **Laravel** 11, 12, or 13 - Any database supported by Laravel --- Installation ------------ [](#installation) ``` composer require scarneros/laravel-japan-postal-codes ``` ### 1. Publish the config (optional) [](#1-publish-the-config-optional) ``` php artisan vendor:publish --tag=japan-postal-codes-config ``` ### 2. Run the migration [](#2-run-the-migration) ``` php artisan migrate ``` ### 3. Import the postal code data [](#3-import-the-postal-code-data) ``` php artisan japan-postal-codes:import ``` This downloads and imports both official CSV datasets from Japan Post (kanji + kana, and romaji). OptionDescription`--file=`Use a local CSV or ZIP instead of downloading`--type=jp`Import only Japanese (kanji + kana)`--type=romaji`Import only romaji`--chunk=1000`Rows per batch (default: 500)> The importer never overwrites data when you import a second dataset — it only fills in `NULL` fields. This means you can run `import --type=jp` and `import --type=romaji` in any order. ### 4. Keep data up to date [](#4-keep-data-up-to-date) ``` php artisan japan-postal-codes:update ``` The update command downloads the latest CSV files and **overwrites** any changed fields. Use `--force` to skip the confirmation prompt. --- Usage ----- [](#usage) ``` use Scarneros\JapanPostalCodes\Facades\PostalCode; // Lookup — accepts raw, hyphenated, or full‑width input PostalCode::lookup('150-0001'); PostalCode::lookup('1500001'); PostalCode::lookup('１５０ー０００１'); // search() is an alias for lookup() PostalCode::search('160-0023'); // Normalize messy input to a clean 7‑digit string PostalCode::normalize('１６０ー００２３'); // "1600023" // Format a 7‑digit number with hyphen PostalCode::format('1600023'); // "160-0023" ``` **Return value:** ``` // PostalCode::lookup('150-0001') [ [ 'postal_code' => '1500001', 'postal_code_formatted' => '150-0001', 'prefecture' => '東京都', 'city' => '渋谷区', 'town' => '神宮前', 'address' => '東京都渋谷区神宮前', 'kana' => 'トウキョウト シブヤク ジングウマエ', 'romaji' => 'TOKYO SHIBUYA-KU JINGUMAE', ], ] ``` ### Eloquent model [](#eloquent-model) ``` use Scarneros\JapanPostalCodes\Models\JapanPostalCode; $row = JapanPostalCode::where('postal_code', '1600023')->first(); $row->address; // "東京都新宿区西新宿" $row->address_kana; // "トウキョウト シンジュクク ニシシンジュク" $row->address_romaji; // "TOKYO SHINJUKU-KU NISHI-SHINJUKU" ``` --- JSON API -------- [](#json-api) Enabled by default. You can toggle it, change the prefix, or adjust middleware in the published config. ``` GET /api/postal-codes/{postalCode} ``` ``` { "data": [ { "postal_code": "1600023", "formatted": "160-0023", "prefecture": "東京都", "city": "新宿区", "town": "西新宿", "address": "東京都新宿区西新宿", "kana": "トウキョウト シンジュクク ニシシンジュク", "romaji": "TOKYO SHINJUKU-KU NISHI-SHINJUKU" } ] } ``` Invalid postal codes return `422`. --- Testing ------- [](#testing) ``` composer test ``` --- License ------- [](#license) The MIT License (MIT). Data provided by [Japan Post](https://www.post.japanpost.jp/service/search/zipcode/download/readme.html). ### Health Score 41 — FairBetter than 87% of packages Maintenance91 Actively maintained with recent releases Popularity19 Limited adoption so far Community6 Small or concentrated contributor base Maturity39 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 45d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/7466299?v=4)[Sergi Carneros](/maintainers/scarneros)[@scarneros](https://github.com/scarneros) --- Top Contributors [![scarneros](https://avatars.githubusercontent.com/u/7466299?v=4)](https://github.com/scarneros "scarneros (3 commits)") --- Tags laraveladdresszip codejapanjapanesepostal-code ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/scarneros-laravel-japan-postal-codes/health.svg) ``` [![Health](https://phpackages.com/badges/scarneros-laravel-japan-postal-codes/health.svg)](https://phpackages.com/packages/scarneros-laravel-japan-postal-codes) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.3M347](/packages/psalm-plugin-laravel)[api-platform/laravel API Platform support for Laravel 58174.6k17](/packages/api-platform-laravel)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5022.6k](/packages/simplestats-io-laravel-client)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)