laravel-japan-postal-codes maintained by scarneros
Laravel Japan Postal Codes
Look up Japanese addresses by postal code. Returns kanji, kana and romaji.
Supports full‑width character normalization, CSV imports from Japan Post, and an optional JSON API.
Requirements
- PHP 8.2+ with
ext-mbstringandext-zip - Laravel 11, 12, or 13
- Any database supported by Laravel
Installation
composer require scarneros/laravel-japan-postal-codes
1. Publish the config (optional)
php artisan vendor:publish --tag=japan-postal-codes-config
2. Run the migration
php artisan migrate
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).
| Option | Description |
|---|---|
--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
NULLfields. This means you can runimport --type=jpandimport --type=romajiin any order.
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
use Scarneros\JapanPostalCodes\Facades\PostalCode;
// Lookup — accepts raw, hyphenated, or full‑width input
PostalCode::lookup('150-0001');
PostalCode::lookup('1500001');
PostalCode::lookup('150ー0001');
// search() is an alias for lookup()
PostalCode::search('160-0023');
// Normalize messy input to a clean 7‑digit string
PostalCode::normalize('160ー0023'); // "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
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
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
composer test
License
The MIT License (MIT). Data provided by Japan Post.