README

A Laravel package for importing and managing Italian geographical data from ISTAT.

Features

• 🇮🇹 Import Italian regions, provinces, and municipalities from ISTAT
• 📮 Import Italian postal codes (CAP) with support for multi-CAP municipalities
• 📍 Optional latitude and longitude for every municipality
• 🔄 Incremental updates: add new records, update changes, soft-delete removed ones
• 📊 Daily CSV caching to avoid unnecessary requests
• 🔗 Eloquent models with hierarchical relationships
• ⚡ Artisan commands for easy data import and synchronization
• 🔧 Fully configurable via configuration file
• 🆔 UUID primary keys and soft deletes support
• 🧪 Comprehensive test suite with mocked HTTP requests

Requirements

• PHP 8.3+
• Laravel 11.0+ or 12.0+
• league/csv 9.0+
• guzzlehttp/guzzle 7.0+

Installation

composer require plin-code/laravel-istat-geography

Quick Start

1. Install the package:

composer require plin-code/laravel-istat-geography

1. Publish the configuration:

php artisan vendor:publish --provider="PlinCode\IstatGeography\IstatGeographyServiceProvider"

1. Run migrations:

php artisan migrate

1. Import the data:

php artisan geography:import

That's it! You now have all Italian geographical data in your database.

Commands

geography:import

Performs a full import of all geographical data from ISTAT. Use this for the initial data load.

php artisan geography:import

Options

Examples

# Import ISTAT data only
php artisan geography:import

# Import ISTAT data + CAP (using local file - recommended)
php artisan geography:import --cap --cap-file=cap-dataset.json

# Update only CAP on existing municipalities
php artisan geography:import --cap-only --cap-file=cap-dataset.json

# Import ISTAT data + coordinates
php artisan geography:import --coordinates

# Update only coordinates on existing municipalities
php artisan geography:import --coordinates-only

Note: The remote GeoJSON with geometries is ~464MB. Using --cap-file with a preprocessed JSON file (~3MB) is recommended for better performance.

geography:download-cap

Downloads CAP GeoJSON data and saves it locally for offline import. Useful when you want to download once and import multiple times.

# Download from default URL (config/env)
php artisan geography:download-cap

# Download from custom URL
php artisan geography:download-cap --url=https://example.com/cap.json

# Specify output path
php artisan geography:download-cap --output=storage/app/my-cap.json

After downloading, import with:

php artisan geography:import --cap --cap-file=storage/app/cap-dataset.json

geography:download-coordinates

Downloads the coordinates dataset and saves it locally (decompressed) for offline import.

# Download from default URL (config/env)
php artisan geography:download-coordinates

# Download from custom URL
php artisan geography:download-coordinates --url=https://example.com/coordinates.json.gz

# Specify output path
php artisan geography:download-coordinates --output=storage/app/my-coordinates.json

After downloading, import with:

php artisan geography:import --coordinates-only --coordinates-file=storage/app/coordinates-dataset.json

geography:update

Incrementally synchronizes your database with the latest ISTAT data. It compares the current ISTAT CSV against your existing records and applies only the differences: new records are added, changed records are updated, and records no longer present in ISTAT are soft-deleted.

php artisan geography:update

Options

Verbosity Levels

Examples

# Preview changes without applying them
php artisan geography:update --dry-run

# Run with verbose output
php artisan geography:update -v

# Run with full debug output
php artisan geography:update -vvv

# Force continue on non-critical errors
php artisan geography:update --force

All database operations are wrapped in a transaction. If any error occurs (and --force is not set), all changes are automatically rolled back.

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="PlinCode\IstatGeography\IstatGeographyServiceProvider"

The config/istat-geography.php file allows you to customize:

• Database connection: Choose which database connection the package tables should use (defaults to the main connection)
• Table names: Customize the database table names
• Model classes: Use your own model classes by extending the base ones
• CSV URL: Change the ISTAT data source URL (also via ISTAT_CSV_URL env)
• CAP GeoJSON URL: Change the CAP data source URL (also via CAP_GEOJSON_URL env)
• Coordinates: Import coordinates on every geography:import (also via ISTAT_IMPORT_COORDINATES env) and change the dataset URL (also via ISTAT_COORDINATES_URL env)
• Temporary file name: Customize the cache file name

Database Connection

By default the package uses your application's default database connection. To store the geographical tables on a separate connection, set the connection key in config/istat-geography.php or the ISTAT_DB_CONNECTION environment variable:

ISTAT_DB_CONNECTION=geography

Note

The connection config key is additive and fully backward compatible. If you published the config file before this option existed, the package falls back to your default database connection (config('database.default')), so no action is required on upgrade. To opt into a custom connection, either republish the config file or set the ISTAT_DB_CONNECTION environment variable.

Municipality Coordinates

Coordinates are optional. The extend_municipalities_with_coordinates migration adds two nullable columns, latitude and longitude, to the municipalities table, and they stay empty until you import them.

Import them once with --coordinates, or enable the import on every geography:import run:

ISTAT_IMPORT_COORDINATES=true

Each municipality gets one representative point of its administrative area: the centroid of the municipal boundary when it falls inside the municipality, otherwise a point guaranteed to be inside it. The point is not the town hall or the main inhabited centre, so for large or irregular municipalities it can be a few kilometres away from the town centre (and sometimes in open countryside). It is meant for maps, sorting by distance and proximity searches, not for navigation.

geography:update never overwrites coordinates, because they are not ISTAT fields. When ISTAT adds a new municipality, it gets coordinates the next time you run the coordinates import with an updated dataset.

$municipality = Municipality::where('istat_code', '058091')->first();

$municipality->latitude;  // 41.8853588
$municipality->longitude; // 12.4607809

Example Configuration

return [
    'connection' => env('ISTAT_DB_CONNECTION', env('DB_CONNECTION')),
    'tables' => [
        'regions' => 'my_regions',
        'provinces' => 'my_provinces',
        'municipalities' => 'my_municipalities',
    ],
    'models' => [
        'region' => \App\Models\Region::class,
        'province' => \App\Models\Province::class,
        'municipality' => \App\Models\Municipality::class,
    ],
    'import' => [
        'csv_url' => 'https://custom-url.com/data.csv',
        'temp_filename' => 'my_istat_data.csv',
    ],
];

Models

The package provides three Eloquent models:

Region

use PlinCode\IstatGeography\Models\Geography\Region;

$region = Region::where('name', 'Piemonte')->first();
$provinces = $region->provinces;

Province

use PlinCode\IstatGeography\Models\Geography\Province;

$province = Province::where('code', 'TO')->first();
$municipalities = $province->municipalities;
$region = $province->region;

Municipality

use PlinCode\IstatGeography\Models\Geography\Municipality;

$municipality = Municipality::where('name', 'Torino')->first();
$province = $municipality->province;

ISTAT Fields

Each model exposes a static istatFields() method that returns the list of fields managed by ISTAT data. These are the fields that the geography:update command is allowed to overwrite. Any additional fields you add to your extended models will not be touched during updates.

Region::istatFields();       // ['name', 'istat_code']
Province::istatFields();     // ['name', 'code', 'istat_code', 'region_id']
Municipality::istatFields(); // ['name', 'istat_code', 'province_id', 'bel_code']
Municipality::capFields();   // ['postal_code', 'postal_codes']
Municipality::coordinateFields(); // ['latitude', 'longitude']

Extending Models

If you want to use the package models in your main project, you can extend them:

// app/Models/Region.php
namespace App\Models;

use PlinCode\IstatGeography\Models\Geography\Region as BaseRegion;

class Region extends BaseRegion
{
    // Add your project-specific logic here
    public function customMethod()
    {
        return $this->provinces()->count();
    }
}

// app/Models/Province.php
namespace App\Models;

use PlinCode\IstatGeography\Models\Geography\Province as BaseProvince;

class Province extends BaseProvince
{
    // Add your project-specific logic here
}

// app/Models/Municipality.php
namespace App\Models;

use PlinCode\IstatGeography\Models\Geography\Municipality as BaseMunicipality;

class Municipality extends BaseMunicipality
{
    // Add your project-specific logic here
}

Remember to update the models section in the configuration file to point to your custom classes.

Database Structure

Regions

• id (UUID, primary key)
• name (string)
• istat_code (string, unique)
• created_at, updated_at, deleted_at

Provinces

• id (UUID, primary key)
• region_id (UUID, foreign key)
• name (string)
• code (string, unique)
• istat_code (string, unique)
• created_at, updated_at, deleted_at

Municipalities

• id (UUID, primary key)
• province_id (UUID, foreign key)
• name (string)
• istat_code (string, unique)
• bel_code (string, nullable) - Cadastral/Belfiore code for CAP matching
• postal_code (string, nullable) - Primary postal code (CAP)
• postal_codes (string, nullable) - Range of postal codes for large municipalities (e.g., "00118-00199")
• latitude (decimal 10,7, nullable): latitude of the representative point (WGS 84)
• longitude (decimal 10,7, nullable): longitude of the representative point (WGS 84)
• created_at, updated_at, deleted_at

Relationships

• Region → hasMany → Province
• Province → belongsTo → Region
• Province → hasMany → Municipality
• Municipality → belongsTo → Province

Replacing Existing Command

If you already have a geography:import command in your project, you can replace it with the package's command:

// In app/Console/Kernel.php or in your existing command
Artisan::command('geography:import', function () {
    $this->info('Starting geographical data import...');

    try {
        $count = \PlinCode\IstatGeography\Facades\IstatGeography::import();
        $this->info("Import completed successfully! Imported {$count} municipalities.");
    } catch (\Exception $e) {
        $this->error('Error during import: ' . $e->getMessage());
    }
})->purpose('Import regions, provinces and municipalities from ISTAT');

Testing

Run the test suite:

composer test

The package includes:

• ✅ Unit tests for models and relationships
• ✅ Feature tests for the import service
• ✅ Feature tests for the update command and services
• ✅ Mocked HTTP requests (no external dependencies)
• ✅ PHPStan static analysis
• ✅ Pest PHP testing framework

Test Coverage

• Models and their relationships
• Import service with CSV processing
• Compare service for detecting changes
• Update service for applying changes
• Artisan command functionality (import and update)
• Configuration handling

Data Sources

ISTAT Data

Geographic data (regions, provinces, municipalities) is sourced from ISTAT (Italian National Institute of Statistics), the official Italian government statistics agency.

Postal Codes (CAP) and Boundaries

Postal code data (data-properties-v1) and the full boundaries GeoJSON (data-geo-v1) are sourced from Zornade Data Downloads. They are derived from OpenStreetMap addresses, so they are licensed under the Open Database License (ODbL). If you use or redistribute them, keep this attribution and share derived databases under the same license:

© OpenStreetMap contributors (ODbL). Data processed by Zornade (https://zornade.com).

Municipality Coordinates

Coordinates are derived from the ISTAT municipal boundaries (Confini Amministrativi) published by Zornade Data Downloads, licensed under CC BY 4.0. If you show these coordinates in your product, keep this attribution visible:

Source: ISTAT, administrative boundaries (CC BY 4.0). Data processed by Zornade (https://zornade.com).

The points were computed by this package from the boundary polygons (centroid in EPSG:3035, or a point on surface when the centroid falls outside the polygon), so they are an adaptation of the original data. The dataset file includes the same attribution, license and generation date in its meta section.

A huge thanks to Zornade for their incredible work in making Italian public data freely available. Their dedication to open data helps developers build better applications for Italian users.

Regenerating the Coordinates Dataset

Maintainers can rebuild the dataset with scripts/build-coordinates-dataset.php (PHP with pdo_sqlite, plus Docker for the official GDAL image). It downloads the boundaries and the current ISTAT list, computes one point per municipality and writes build/municipality_coordinates_dataset.json.gz:

php scripts/build-coordinates-dataset.php

# Optional sanity check with the Zornade reverse geocoding API
ZORNADE_TOKEN=your-token php scripts/build-coordinates-dataset.php --spot-check

Municipalities created by a merger after the boundaries were published are computed on the union of their predecessors, listed in MERGED_MUNICIPALITIES inside the script. The script stops with an error when a municipality has no polygon and no merger entry.

Contributing

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

The MIT License (MIT). Please see License File for more information.