PHPackages                             ajangsupardi/laravel-postcode-id - 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. [Database & ORM](/categories/database)
4. /
5. ajangsupardi/laravel-postcode-id

ActiveLibrary[Database & ORM](/categories/database)

ajangsupardi/laravel-postcode-id
================================

Laravel package for seeding Indonesian address data (provinces, regencies, districts, villages) with postal codes from Pos Indonesia

v1.1.0(1mo ago)19↓50%MITPHPPHP ^8.3CI passing

Since Jun 19Pushed 1w agoCompare

[ Source](https://github.com/ajangsupardi/laravel-postcode-id)[ Packagist](https://packagist.org/packages/ajangsupardi/laravel-postcode-id)[ RSS](/packages/ajangsupardi-laravel-postcode-id/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (3)Dependencies (12)Versions (3)Used By (0)

Laravel Postcode ID
===================

[](#laravel-postcode-id)

[![Latest Stable Version](https://camo.githubusercontent.com/3792e33d5c8a31afde927e52dfaa5c1be37a7bed3f7c2ef3c4adc2cc1b9cdf72/68747470733a2f2f706f7365722e707567782e6f72672f616a616e67737570617264692f6c61726176656c2d706f7374636f64652d69642f762f737461626c65)](https://packagist.org/packages/ajangsupardi/laravel-postcode-id)[![License](https://camo.githubusercontent.com/7061dab69ab5adb08e38a54f623f94af0fee04ad65544e6eb1468d51e2815126/68747470733a2f2f706f7365722e707567782e6f72672f616a616e67737570617264692f6c61726176656c2d706f7374636f64652d69642f6c6963656e7365)](https://packagist.org/packages/ajangsupardi/laravel-postcode-id)[![Total Downloads](https://camo.githubusercontent.com/17c0cd36c9502a749fe1748c3f2aceb56124760d721692b920dbf955f7571217/68747470733a2f2f706f7365722e707567782e6f72672f616a616e67737570617264692f6c61726176656c2d706f7374636f64652d69642f646f776e6c6f616473)](https://packagist.org/packages/ajangsupardi/laravel-postcode-id)

Laravel package for Indonesian address data with postal codes — downloaded fresh from Pos Indonesia.

Features
--------

[](#features)

- **Postal code lookup** — Query villages by postal code with full address hierarchy
- **Fresh data** — Downloads directly from [Pos Indonesia](https://kodepos.posindonesia.co.id), not static dumps
- **Idempotent seeders** — Safe to run multiple times without duplicates
- **Hierarchical parsing** — Province → Regency → District → Village with name normalization
- **Custom models** — Extend default models or use your own
- **Laravel 11, 12, 13** — Modern PHP 8.3+

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

[](#installation)

```
composer require ajangsupardi/laravel-postcode-id
```

### Publish Configuration (optional)

[](#publish-configuration-optional)

```
php artisan vendor:publish --tag=postcode-config
```

### Publish Migrations (optional)

[](#publish-migrations-optional)

```
php artisan vendor:publish --tag=postcode-migrations
```

> **Note:** Migrations are automatically loaded by the service provider, so publishing is only needed if you want to modify the table structure.

Usage
-----

[](#usage)

### 1. Download Postcode Data

[](#1-download-postcode-data)

```
php artisan postcode:download
```

This command will download all postcode data from Pos Indonesia and save it as a CSV file.

### 2. Run Migrations & Seeder

[](#2-run-migrations--seeder)

```
php artisan migrate
php artisan postcode:seed
```

Or add it to your `DatabaseSeeder.php`:

```
use Ajangsupardi\PostcodeId\Database\Seeders\PostcodeSeeder;

public function run(): void
{
    $this->call([
        PostcodeSeeder::class,
    ]);
}
```

### 3. Auto-download & Seed

[](#3-auto-download--seed)

If you want to combine download and seed in a single step, you can call the download command before the seeder:

```
use Illuminate\Support\Facades\Artisan;

$storagePath = config('postcode.storage_path');
if (! file_exists($storagePath.'/kodepos.csv')) {
    Artisan::call('postcode:download');
}
```

Postal Code Lookup
------------------

[](#postal-code-lookup)

The main feature — find any Indonesian address by postal code:

```
use Ajangsupardi\PostcodeId\Models\Village;

// Village by postal code
$village = Village::where('postal_code', '60111')->first();

// With full address hierarchy
$village = Village::with('district.regency.province')
    ->where('postal_code', '60111')
    ->first();

// Result: Gubeng → Kota Surabaya → Jawa Timur
```

```
// Search by village name
$villages = Village::where('name', 'LIKE', '%Gubeng%')
    ->with('district.regency')
    ->get();
```

Database Tables
---------------

[](#database-tables)

This package creates 4 tables:

TableDescription`provinces`Province data (id, name, code)`regencies`Regency/city data (id, province\_id, name)`districts`District/sub-district data (id, regency\_id, name)`villages`Village data (id, district\_id, name, postal\_code)Configuration
-------------

[](#configuration)

Edit `config/postcode.php`:

```
return [
    // CSV file storage path
    'storage_path' => storage_path('app/postcode'),

    // Database table prefix (null = no prefix)
    'table_prefix' => null,

    // Custom models
    'models' => [
        'province' => Ajangsupardi\PostcodeId\Models\Province::class,
        'regency'  => Ajangsupardi\PostcodeId\Models\Regency::class,
        'district' => Ajangsupardi\PostcodeId\Models\District::class,
        'village'  => Ajangsupardi\PostcodeId\Models\Village::class,
    ],

    // HTTP client settings
    'http' => [
        'timeout' => 60,
        'connect_timeout' => 10,
        'retry' => 3,
        'retry_delay' => 1000,
        'user_agent' => 'Mozilla/5.0 (compatible; LaravelPostcodeId/1.0)',
    ],
];
```

### Custom Models

[](#custom-models)

You can extend the default models to add columns or relationships:

```
namespace App\Models;

use Ajangsupardi\PostcodeId\Models\Province as BaseProvince;

class Province extends BaseProvince
{
    protected $fillable = ['name', 'code', 'your_custom_field'];

    // Add custom relationships or methods
}
```

Then update the configuration:

```
'models' => [
    'province' => App\Models\Province::class,
],
```

### Table Prefix

[](#table-prefix)

If you want to use a prefix for your tables:

```
'table_prefix' => 'postcode_',
```

This will create tables: `postcode_provinces`, `postcode_regencies`, `postcode_districts`, `postcode_villages`.

Example Queries
---------------

[](#example-queries)

```
use Ajangsupardi\PostcodeId\Models\Province;
use Ajangsupardi\PostcodeId\Models\Village;

// Get all provinces
$provinces = Province::all();

// Get regencies in East Java
$regencies = Province::where('name', 'Jawa Timur')
    ->first()
    ->regencies;

// Find a village by postal code
$village = Village::where('postal_code', '60111')->first();

// Get full address hierarchy from village to province
$village = Village::with('district.regency.province')
    ->where('postal_code', '60111')
    ->first();
```

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

[](#requirements)

- PHP ^8.3
- Laravel ^11.0 / ^12.0 / ^13.0

Changelog
---------

[](#changelog)

### v1.1.6

[](#v116)

- Fix progress bar not displaying in terminal during `postcode:seed`

### v1.1.5

[](#v115)

- Fix `postcode:seed` hanging on PostgreSQL — remove transaction wrapper that caused deadlock

### v1.1.4

[](#v114)

- Fix `postcode:seed` hanging indefinitely — use `Artisan::call()` instead of `Command::call()` to correctly invoke seeder

### v1.1.3

[](#v113)

- Add progress bar to all seeders for visual feedback during bulk operations

### v1.1.2

[](#v112)

- Fix `postcode:download` failing on transient network errors — retry now handles cURL connection exceptions

### v1.1.1

[](#v111)

- Fix `VillageSeeder` hanging/timing out on PostgreSQL — foreign key triggers are temporarily disabled during bulk insert

### v1.1.0

[](#v110)

- Added `postcode:seed` artisan command to fix shell escaping bug on Linux

### v1.0.0

[](#v100)

- Initial release — download, parse, and seed Indonesian address data with postal codes

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for more information.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance95

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

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

Total

2

Last Release

44d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/35716844?v=4)[ᑎᗩᒍ](/maintainers/ajangsupardi)[@ajangsupardi](https://github.com/ajangsupardi)

---

Top Contributors

[![ajangsupardi](https://avatars.githubusercontent.com/u/35716844?v=4)](https://github.com/ajangsupardi "ajangsupardi (17 commits)")

---

Tags

addressdatabase-seederindonesialaravellaravel-packagephppostal-codepostcodelaraveladdresspostcodeindonesiapostal-codedatabase-seeder

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ajangsupardi-laravel-postcode-id/health.svg)

```
[![Health](https://phpackages.com/badges/ajangsupardi-laravel-postcode-id/health.svg)](https://phpackages.com/packages/ajangsupardi-laravel-postcode-id)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.4M352](/packages/psalm-plugin-laravel)[spatie/laravel-medialibrary

Associate files with Eloquent models

6.2k45.4M679](/packages/spatie-laravel-medialibrary)[forjedio/inertia-table

Backend-driven dynamic tables for Laravel + Inertia.js

272.0k](/packages/forjedio-inertia-table)[laravel/ai

The official AI SDK for Laravel.

1.1k4.6M276](/packages/laravel-ai)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

78727.1M206](/packages/laravel-mcp)[calebdw/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

16132.2k4](/packages/calebdw-larastan)

PHPackages © 2026

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