PHPackages                             ethantechnology/laravel-jp-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. ethantechnology/laravel-jp-postal-codes

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

ethantechnology/laravel-jp-postal-codes
=======================================

Laravel package for Japanese prefectures and postal codes

v3.0.1(11mo ago)0203MITPHPPHP ^7.4|^8.0|^8.1|^8.2|^8.3|^8.4

Since Jul 21Pushed 11mo agoCompare

[ Source](https://github.com/ethantechnology/laravel-jp-postal-codes)[ Packagist](https://packagist.org/packages/ethantechnology/laravel-jp-postal-codes)[ RSS](/packages/ethantechnology-laravel-jp-postal-codes/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (8)Used By (0)

Japanese Postal Codes
=====================

[](#japanese-postal-codes)

Laravel package for Japanese prefectures and postal codes. The data is imported from the official Japan Post service.

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

[](#requirements)

- PHP 7.4 or higher
- Laravel 7.0 or higher

Installation
------------

[](#installation)

```
composer require ethantechnology/laravel-jp-postal-codes
```

### Service Provider Registration

[](#service-provider-registration)

#### For Laravel 5.5+

[](#for-laravel-55)

If you're using Laravel 5.5 or higher, the package will automatically register its service provider thanks to Laravel's package discovery feature.

#### For Laravel 5.4 and below

[](#for-laravel-54-and-below)

If you're using Laravel 5.4 or below, you need to manually register the service provider. Add the following line to the `providers` array in your `config/app.php` file:

```
Eta\JpPostalCodes\JpPostalCodesServiceProvider::class,
```

Configuration
-------------

[](#configuration)

To customize the table names and other settings, publish the configuration file:

```
php artisan vendor:publish --tag=jp-postal-codes-config
```

This will create a `config/jp-postal-codes.php` file where you can:

- Change the table names for prefectures, cities, and postal codes
- Modify the URL for downloading postal code data
- Adjust import settings like chunk size

### Customizing Migrations

[](#customizing-migrations)

Since we no longer automatically load migrations, you need to publish them first:

```
php artisan vendor:publish --tag=jp-postal-codes-migrations
```

After publishing, you can find and modify the migration files in your `database/migrations` directory. You should customize them before running migrations if you:

1. Changed table names in the config
2. Need to adjust table structures (add or modify columns)
3. Want to change indexes or foreign key constraints

> **Important**: Make sure your migration table names match those in the config file. If you change table names in the config, update the corresponding migration files before running migrations.

Migration
---------

[](#migration)

After installing and configuring, run:

```
php artisan migrate
```

This will create the following tables:

- `prefectures`: Contains all Japanese prefectures (or your custom table name if configured)
- `cities`: Contains all Japanese cities/municipalities (or your custom table name if configured)
- `postal_codes`: Contains Japanese postal codes with their corresponding prefectures and cities (or your custom table name if configured)

Updating Postal Code Data
-------------------------

[](#updating-postal-code-data)

To download and update all data from the official Japan Post service:

```
php artisan jp-postal-codes:update
```

This command will:

1. Download the latest postal code data from Japan Post
2. Clean all existing data in the tables
3. Import the postal codes
4. Automatically extract and create prefectures and cities from the postal code data

Note: This process downloads data from the official Japan Post service and might take some time to complete. The data is provided in Shift-JIS encoding and will be automatically converted to UTF-8 during import.

Usage
-----

[](#usage)

```
use Eta\JpPostalCodes\Models\Prefecture;
use Eta\JpPostalCodes\Models\City;
use Eta\JpPostalCodes\Models\PostalCode;

// Get all prefectures
$prefectures = Prefecture::all();

// Find prefecture by ID
$tokyo = Prefecture::find(13);

// Get all cities in a prefecture
$tokyoCities = $tokyo->cities;

// Find city by ID
$city = City::find('13104');

// Get the prefecture for a city
$prefecture = $city->prefecture;

// Find location by postal code
$locations = PostalCode::where('postal_code', '1600022')->get();
// Or using the scope
$locations = PostalCode::postal('1600022')->get();

// Get the city and prefecture for a postal code
$location = PostalCode::postal('1600022')->first();
$city = $location->city;
$prefecture = $location->prefecture;
```

Custom Table Names
------------------

[](#custom-table-names)

After publishing the config file, you can modify the table names:

```
// config/jp-postal-codes.php
return [
    'tables' => [
        'prefectures' => 'custom_prefectures',
        'cities' => 'custom_cities',
        'postal_codes' => 'custom_postal_codes',
    ],
    // ...
];
```

Make sure to update your migration files to match these table names before running migrations.

License
-------

[](#license)

MIT

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance51

Moderate activity, may be stable

Popularity11

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

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 ~1 days

Total

7

Last Release

346d ago

Major Versions

v1.0.3 → v2.0.02025-07-24

v2.0.0 → v3.0.02025-07-24

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/185058892?v=4)[eta-h](/maintainers/eta-h)[@eta-h](https://github.com/eta-h)

---

Tags

laraveljapanjapaneseaddressesregionspostal-codeszip codesPrefectures

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ethantechnology-laravel-jp-postal-codes/health.svg)

```
[![Health](https://phpackages.com/badges/ethantechnology-laravel-jp-postal-codes/health.svg)](https://phpackages.com/packages/ethantechnology-laravel-jp-postal-codes)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[spatie/laravel-health

Monitor the health of a Laravel application

87512.0M167](/packages/spatie-laravel-health)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[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.0k](/packages/simplestats-io-laravel-client)[flarum/core

Delightfully simple forum software.

201.4M2.3k](/packages/flarum-core)[api-platform/laravel

API Platform support for Laravel

58171.6k14](/packages/api-platform-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)