PHPackages                             madkhix/tr-address - 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. madkhix/tr-address

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

madkhix/tr-address
==================

A Laravel package for Turkey's provinces, districts, neighborhoods, and postal codes.

011PHP

Since Jul 1Pushed 1y agoCompare

[ Source](https://github.com/Madkhix/tr-address)[ Packagist](https://packagist.org/packages/madkhix/tr-address)[ RSS](/packages/madkhix-tr-address/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

tr-address
==========

[](#tr-address)

A Laravel package for Turkey's provinces, districts, quarters (subdistricts), neighborhoods, and postal codes. Easily import, query, and keep up-to-date address data from

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

[](#installation)

```
composer require madkhix/tr-address
```

Publishing Migrations, Seeders, and Config
------------------------------------------

[](#publishing-migrations-seeders-and-config)

```
php artisan vendor:publish --provider="TrAddress\TrAddressServiceProvider" --tag="migrations"
php artisan migrate
php artisan vendor:publish --provider="TrAddress\TrAddressServiceProvider" --tag="seeders"
php artisan vendor:publish --provider="TrAddress\TrAddressServiceProvider" --tag="traddress-config"
```

> After running the Python scraper, copy the generated `tr-address-data.json` file to your Laravel project root (where the `artisan` file is located). You can also use the following artisan command to copy it automatically:
>
> ```
> php artisan traddress:publish-json
> ```
>
>
>
> You can change the JSON data file path in `config/traddress.php` if needed.

Data Structure
--------------

[](#data-structure)

The JSON data must have the following structure:

```
[
  {
    "name": "ADANA",
    "districts": [
      {
        "name": "ALADAĞ",
        "quarters": [
          {
            "name": "KARSANTI",
            "neighborhoods": [
              { "name": "MANSURLU MAH.", "postcode": "01720" }
            ]
          }
        ]
      }
    ]
  }
]
```

- `cities` have many `districts`
- `districts` have many `quarters` (subdistricts)
- `quarters` have many `neighborhoods`
- Each `neighborhood` has a `postcode`

Migration Structure
-------------------

[](#migration-structure)

Each table has its own migration file:

- `cities`
- `districts`
- `subdistricts` (quarters)
- `neighborhoods`
- `postcodes`

You can run all migrations at once:

```
php artisan migrate
```

Or, to run a specific migration file (advanced usage):

```
php artisan migrate --path=src/database/migrations/2024_01_03_000000_create_subdistricts_table.php
```

Seeder Structure
----------------

[](#seeder-structure)

Each table has its own seeder:

- `CitySeeder`
- `DistrictSeeder`
- `SubdistrictSeeder` (seeds all quarters)
- `NeighborhoodSeeder` (seeds all neighborhoods and links to subdistricts)
- `PostcodeSeeder`
- `TrAddressSeeder` (runs all in order)

Seed all data:

```
php artisan db:seed --class=Database\Seeders\TrAddressSeeder
```

> **Note:**
>
> - Run `SubdistrictSeeder` before `NeighborhoodSeeder` if you seed them separately.
> - `NeighborhoodSeeder` will not create subdistricts, only link to existing ones.

Importing Data
--------------

[](#importing-data)

After generating or updating your `tr-address-data.json` file, import it with:

```
php artisan traddress:import tr-address-data.json
```

Usage
-----

[](#usage)

```
use TrAddress\Models\City;
use TrAddress\Models\District;
use TrAddress\Models\Subdistrict;
use TrAddress\Models\Neighborhood;
use TrAddress\Models\Postcode;

$cities = City::all();
$districts = $cities[0]->districts;
$quarters = $districts[0]->subdistricts; // quarters
$neighborhoods = $quarters[0]->neighborhoods;
$postcode = $neighborhoods[0]->postcodes->first()->code;
```

Updating Address Data (Fetching from PTT)
-----------------------------------------

[](#updating-address-data-fetching-from-ptt)

This package does **not** include the Python data fetcher script by default. To update the address data from the official PTT source, use the separate Python script available at:

**Usage:**

1. Clone or download the script from the repository above.
2. Run the script in your terminal: ```
    python fetch_tr_address_data.py
    ```
3. The script will generate a `tr-address-data.json` file.
4. Copy this file to your Laravel project root (where `artisan` is located).
5. Import the data using the package's artisan command: ```
    php artisan traddress:import tr-address-data.json
    ```

> This approach keeps the PHP package clean and dependency-free, while still allowing advanced users to update the address data as needed.

License
-------

[](#license)

MIT

###  Health Score

15

—

LowBetter than 3% of packages

Maintenance34

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity15

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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/73113b9c3bd09353a1360ac6a167a50413186b631f14f1d079c0d43f880f75dc?d=identicon)[Madkhix](/maintainers/Madkhix)

---

Top Contributors

[![Madkhix](https://avatars.githubusercontent.com/u/62099980?v=4)](https://github.com/Madkhix "Madkhix (20 commits)")

---

Tags

citycodedistrictlaravelpostal-codestateturkey

### Embed Badge

![Health badge](/badges/madkhix-tr-address/health.svg)

```
[![Health](https://phpackages.com/badges/madkhix-tr-address/health.svg)](https://phpackages.com/packages/madkhix-tr-address)
```

PHPackages © 2026

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