{"id":17118499,"url":"https://github.com/mlocati/comuni-italiani","last_synced_at":"2025-04-23T01:52:51.850Z","repository":{"id":246735819,"uuid":"821332233","full_name":"mlocati/comuni-italiani","owner":"mlocati","description":"A PHP library to work with Italian Regions, Provinces, and Municipalities","archived":false,"fork":false,"pushed_at":"2025-01-20T08:37:32.000Z","size":640,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T01:52:45.046Z","etag":null,"topics":["comuni","istat","italian","italiani","italy","municipalities","province","provinces","regioni","regions"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlocati.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mlocati","custom":"https://paypal.me/mlocati"}},"created_at":"2024-06-28T09:55:27.000Z","updated_at":"2025-03-06T15:04:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"8d6abdc3-5a6e-4bab-8ef0-637b484ea84a","html_url":"https://github.com/mlocati/comuni-italiani","commit_stats":null,"previous_names":["mlocati/comuni-italiani"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlocati%2Fcomuni-italiani","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlocati%2Fcomuni-italiani/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlocati%2Fcomuni-italiani/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlocati%2Fcomuni-italiani/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlocati","download_url":"https://codeload.github.com/mlocati/comuni-italiani/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250354298,"owners_count":21416751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comuni","istat","italian","italiani","italy","municipalities","province","provinces","regioni","regions"],"created_at":"2024-10-14T17:54:43.398Z","updated_at":"2025-04-23T01:52:51.827Z","avatar_url":"https://github.com/mlocati.png","language":"PHP","funding_links":["https://github.com/sponsors/mlocati","https://paypal.me/mlocati"],"categories":[],"sub_categories":[],"readme":"[![Tests](https://github.com/mlocati/comuni-italiani/actions/workflows/tests.yml/badge.svg)](https://github.com/mlocati/comuni-italiani/actions/workflows/tests.yml)\n[![Coverage](https://coveralls.io/repos/github/mlocati/comuni-italiani/badge.svg?branch=main)](https://coveralls.io/github/mlocati/comuni-italiani?branch=main)\n\n## Comuni Italiani\n\nThis PHP library contains the whole list of Italian Regions (regioni), Provinces (province/UTS), and Municipalities (comuni).\n\nThe data comes from the official [Situas](https://situas.istat.it) service of the Istituto nazionale di statistica (Istat), that publishes its data with the [CC-BY-4.0 license](https://creativecommons.org/licenses/by/4.0/) .\n\n### Installation\n\nYou can install this package with [Composer](https://getcomposer.org/):\n\n```sh\ncomposer require mlocati/comuni-italiani\n```\n\n### Data Structure\n\nThis library provides the following Italian Administrative divisions:\n\n- **Geographical Subdivisions** (*ripartizioni geografiche*)\n  For example \"Nord-ovest\", \"Centro\", \"Sud\"\n- **Regions** (*regioni*)\n  For example \"Piemonte\", \"Lazio\", \"Campania\"\n- **Provinces** (*province*) and **Supra-Municipal Territorial Units** (**UTS** - *unità territoriale sovracomunale*)\n- **Municipalities** (*comuni*)\n\nWhere:\n- every Geographical Subdivision contains one or more Regions\n- every Region contains one or more Provinces/UTS\n- every Province/UTS contains one or more Municipalities\n\n### Data Available\n\nThis library provides the following data:\n\n- for the **Geographical Subdivisions**\n  - the Istat ID (example: `1`)\n  - the name (example: `'Nord-ovest'`)\n  - the first level of the current Nomenclature of Territorial Units for Statistics (NUTS1) (example: `'ITC'`)\n  - the list of Regions\n- for the **Regions**\n  - the parent Geographical Subdivision\n  - the Istat ID (example: `'01'`)\n  - the name (example: `'Piemonte'`)\n  - the type:\n    - Ordinary Status (*regione a statuto ordinario*)\n    - Special Status (*regione a statuto speciale*)\n  - the Fiscal Code (*codice fiscale*) assigned by the Agenzia delle Entrate (example: `'80087670016'`)\n  - the second level of the current Nomenclature of Territorial Units for Statistics (NUTS2) (example: `'ITC1'`)\n  - the Capital Municipality of this Region (*capoluogo di regione*) (example: `'Torino'`)\n  - the list of Provinces/UTS\n- for the **Provinces** / **UTS**\n  - the parent Region\n  - the Istat ID (example: `'201'`)\n  - the name (example: `'Torino'`)\n  - the historical Province code (example: `'001'`)\n  - the type:\n    - Province (*provincia*)\n    - Autonomous Province (*provincia autonoma*)\n    - Metropolitan City (*città metropolitana*)\n    - Free Consortium of Municipalities (*libero consorzio di comuni*)\n    - Non-Administrative Unit (*unità non amministrativa*) - former Provinces of Friuli-Venezia Giulia\n  - the vehicle code (*sigla automobilistica*) (example: `'TO'`)\n  - the Fiscal Code (*codice fiscale*) assigned by the Agenzia delle Entrate (example: `'01907990012'`)\n  - the third level of the current Nomenclature of Territorial Units for Statistics (NUTS3) (example: `'ITC11'`)\n  - the Capital Municipalities of this Province/UTS (*capoluogo di provincia*) (example: `'Torino'`)\n  - the list of Municipalities\n- for the **Municipalities**\n  - the parent Province/UTS\n  - the Istat ID (example: `'001272'`)\n  - the name (example: `'Torino'`)\n  - the Italian and Foreign names for bilingual municipalities (for example: `'Bolzano'` and `'Bozen'`)\n  - if the Municipality is the Capital Municipality of its Region (*capoluogo di regione*)\n  - if the Municipalities is a Capital Municipalities of its Province/UTS (*capoluogo di provincia*)\n  - the Cadastral Code (*codice catastale*) (example: `'L219'`)\n  - the Fiscal Code (*codice fiscale*) assigned by the Agenzia delle Entrate (example: `'00514490010'`)\n  - the first level of the current Nomenclature of Territorial Units for Statistics (NUTS1) (example: `'ITC'`)\n  - the second level of the current Nomenclature of Territorial Units for Statistics (NUTS2) (example: `'ITC1'`)\n  - the third level of the current Nomenclature of Territorial Units for Statistics (NUTS3) (example: `'ITC11'`)\n\n### Retrieving All Territories\n\nYou can have a list of all the Geographical Subdivisions, Regions, Provinces/UTS, and Municipalities using the `Factory` class.\n\nFor example:\n\n```php\nuse MLocati\\ComuniItaliani\\Factory;\n\n$factory = new Factory();\n\n$allGeographicalSubdivisions = $factory-\u003egetGeographicalSubdivisions();\n$allRegions = $factory-\u003egetRegions();\n$allProvinces = $factory-\u003egetProvinces();\n$allMunicipalities = $factory-\u003egetMunicipalities();\n```\n\n### Finding Territories by ID\n\nIf you want to retrieve a territory given its ID, you can use the `Finder` class:\n\n```php\nuse MLocati\\ComuniItaliani\\Finder;\n\n$finder = new Finder();\n\n$geographicalSubdivision = $finder-\u003egetGeographicalSubdivisionByID(1);\n$region = $finder-\u003egetRegionByID('01');\n$province = $finder-\u003egetProvinceByID('201');\n$municipality = $finder-\u003egetMunicipalityByID('001272');\n```\n\n### Finding Provinces by Vehicle Code\n\nYou can use the `getProvinceByVehicleCode` method of the `Finder` class:\n\n```php\nuse MLocati\\ComuniItaliani\\Finder;\n\n$finder = new Finder();\n\necho $finder-\u003egetProvinceByVehicleCode('CO')-\u003egetName();\n// prints Como\n```\n\n### Finding Territories by Name\n\nYou can use the `Finder` class to find Geographical Subdivisions, Regions, Provinces/UTS, and Municipalities by name.\n\nThe text to be searched will be split into words, and you'll get the territories whose names contain all the words.\n\nFor example, searching for `roma lombard` will return the `Romano di Lombardia (BG)` municipality.\n\nExamples:\n\n```php\nuse MLocati\\ComuniItaliani\\Finder;\n\n$finder = new Finder();\n\n$geographicalSubdivisions = $finder-\u003efindGeographicalSubdivisionsByName('Nord');\n$regions = $finder-\u003efindRegionsByName('Campa');\n$provinces = $finder-\u003efindProvincesByName('Bozen');\n$municipalities = $finder-\u003efindMunicipalitiesByName('Roma lombard');\n```\n\nBy default, Finder will look for the beginning of words.\nSo, `ampania` won't match `Campania`.\n\nIf you want to allow searching in the middle of the words, specify `true` as the second parameter:\n\n```php\nuse MLocati\\ComuniItaliani\\Finder;\n\n$finder = new Finder();\n\n$geographicalSubdivisions = $finder-\u003efindGeographicalSubdivisionsByName('ord', true);\n$regions = $finder-\u003efindRegionsByName('ampania', true);\n$provinces = $finder-\u003efindProvincesByName('ozen', true);\n$municipalities = $finder-\u003efindMunicipalitiesByName('oma ombard', true);\n```\n\nYou can also restrict the search to specific territories:\n\n```php\nuse MLocati\\ComuniItaliani\\Finder;\n\n$finder = new Finder();\n\n$province = $finder-\u003egetProvinceByVehicleCode('BG');\n$municipalities = $finder-\u003efindMunicipalitiesByName('romano', false, $province);\n// The same applies to findRegionsByName and findProvincesByName\n```\n\n### Testing Hierarchy\n\nGiven two territories, you can check if they are the same by using the `isSame()` method:\n\n```php\nif ($territory1-\u003eisSame($territory2)) {\n    echo 'Same territory';\n}\n```\n\nYou can also check if a territory is contained in another territory:\n\n```php\nif ($territory1-\u003eisContainedIn($territory2)) {\n    echo \"{$territory1} is contained in {$territory2}\";\n}\nif ($territory1-\u003eisSameOrContainedIn($territory2)) {\n    echo \"{$territory1} is contained in {$territory2} (or they are the same)\";\n}\n```\n\nFor Geographical Subdivisions, Regions, and Provinces/UTS (which are containers of other territories) you can also use the `contains()` and `isSameOrContains()` methods.\n\n```php\n// $region is an instance of Region here\nif ($region-\u003econtains($territory)) {\n    echo \"{$region} contains {$terrtory}\";\n}\n\nif ($region-\u003eisSameOrContains($territory)) {\n    echo \"{$region} is same (or contains) {$terrtory}\";\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlocati%2Fcomuni-italiani","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlocati%2Fcomuni-italiani","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlocati%2Fcomuni-italiani/lists"}