stefanzweifel / php-swiss-cantons

🇨🇭 Find Swiss Canton by abbreviation, name or zipcode.

🇨🇭 PHP Swiss Cantons

Using Javascript? Check out @stefanzweifel/js-swiss-cantons.

Installation

The easiest way to install the package is by using composer. The package requires PHP 8.2.

composer require "wnx/php-swiss-cantons"

Usage

Use the CantonManager Class to interact with this package. Below you find an example how you can use with in the Laravel Framework. Further you find all public API methods for CantonManager and Canton.

<?php 

use Wnx\SwissCantons\CantonManager;

$cantonManager = new CantonManager();

/** @var \Wnx\SwissCantons\Canton $canton */
$canton = $cantonManager->getByAbbreviation('zh');
$canton = $cantonManager->getByName('Zurigo');
$canton = $cantonManager->getByZipcode(8000);

// "Zürich"
$cantonName = $canton->setLanguage('de')->getName();

CantonManager

Use the CantonManager to find a Canton. It will return a new Instance of Canton or throws an Exception if no Canton could be found for the abbreviation, name or zipcode.

getByAbbreviation()

Find a Canton by its abbreviation. See this list for available abbreviations.

$cantonManager = new Wnx\SwissCantons\CantonManager();

/** @var \Wnx\SwissCantons\Canton $canton */
$canton = $cantonManager->getByAbbreviation('GR');

getByName()

Search for a Canton by its name. The name must exactly match one of the translations of the Canton (German, French, Italian, Romansh or English).

$cantonManager = new Wnx\SwissCantons\CantonManager();

/** @var \Wnx\SwissCantons\Canton $canton */
$canton = $cantonManager->getByName('Zürich');

getByZipcode()

Returns an array of possible Cantons for a given Zipcode. (Some zipcodes are shared between multiple Cantons).

$cantonManager = new Wnx\SwissCantons\CantonManager();

/** @var \Wnx\SwissCantons\Canton[] $cantons */
$cantons = $cantonManager->getByZipcode(3005);

getByZipcodeAndCity()

Find Canton by a given zipcode and optionally by a city name.

$cantonManager = new Wnx\SwissCantons\CantonManager();

/** @var \Wnx\SwissCantons\Canton $canton */
$canton = $cantonManager->getByZipcodeAndCity(1003);
$canton = $cantonManager->getByZipcodeAndCity(1290, 'Lausanne');

Canton

setLanguage($string = 'en')

Set the language, which should be used to display the name of the canton. The following languages are currently supported.

• German (de)
• French (fr)
• Italian (it)
• Romansh (rm)
• English (en, default)

The method returns the current instance of Canton for easier method chaining.

$canton->setLanguage('rm');

$canton->setLanguage('fr')->getName();

getName()

Return the Name for the given Canton. If the method is used without calling the setLanguage() method first, it will return the name in English.

$canton->getName(); // Grisons
$canton->setLanguage('de')->getName(); // Graubünden

getAbbreviation()

Return the offical abbreviation for the given Canton.

$canton->getAbbreviation(); // e.g. ZH

Cantons

This class is used internally but can also be used in your own project if you need a list of all cantons

getAll()

Returns an array containg Wnx\SwissCantons\Canton objects.

use Wnx\SwissCantons\Cantons;

$cantons = (new Cantons)->getAll();

getAllAsArray($defaultLanguage = 'en')

Returns a one dimensionl array of all Cantons. The key is the abbreviation. The value will be the translated name of the Canton. The default language is English. Pass one of the valid languages to the method, to localize the names.

use Wnx\SwissCantons\Cantons;

$cantons = (new Cantons)->getAllAsArray('en');

$cantonsAsArray = $cantons->getAllAsArray(); 

// var_dump($cantonsAsArray);
// [
//     'ZH' => 'Zurich', 
//     'GE' => 'Geneva',
//     // ...
// ]

Security

If you discover a security vulnerability within this package, please send an e-mail to [email protected]. All security vulnerabilities will be promptly addressed.

Data Sources

• https://en.wikipedia.org/wiki/Cantons_of_Switzerland
• Zipcodes / Swiss Post

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Credits

• Stefan Zweifel
• All Contributors

License

This project is licensed under the MIT License - see the LICENSE file for details.

php-swiss-cantons's Issues

Zip-code 9496 isn't swiss

The zip-code 9496 is part of Liechtenstein and not swiss.
https://en.wikipedia.org/wiki/Balzers
So the $cantonManager->getByZipcode(9496) throws an exception with message Couldn't find Canton for given abbreviation..

Because this package is about the swiss this zip-code shouldn't be part of it at all!?

Lowercase abbreviations throws error

1. What's your issue?

The package throws an exception, if the provided abbreviation is not in uppercase.

2. Which PHP Version are you using?

I'm using PHP Version 7.0.

3. Which Version of the php-swiss-cantons Package are you using?

I'm using version 1.2.0.

5. What did you expect to happen in the first place?

The following code snippet shouldn't throw an exception.

$canton = $cantonManager->getByAppreviation('zh');

Zipcode and Canton is not a One-to-One relationship

Hi,

I'm using this library since a few months, thank you for your work !

But unfortunately, some cases don't work when guessing the canton from the zipcode.
In fact, in Switzerland, a zipcode (NPA) does not contain the information of a specific canton. It's based on geographical and physical information, like train endpoint. For some zipcode, you can have different cities, which are in different cantons.

Example: 1290 is assigned to Chavanne-les-bois in the canton of Vaud, and Versoix in the canton of Geneva.

It's the same issue with zipcode and cities: a city can have several zipcode...
Example: Kefikon has a zipcode for its part in Thurgovie canton et a zipcode for its part in Zurich canton..

Conclusion
Is it possible to have a system covering all cases ? If not, it would be necessary to add this information as a warning in the library documentation.

Fribourg should be Fribourg in english

Thanks for your work!

There is a small typo for the Canton Fribourg, in english.

php-swiss-cantons/src/data/cantons.json

Line 69 in abda04a

"en": "Friburg"

Zip-code 2400 is duplicated

The zip-code 2400 is duplicated.

php-swiss-cantons/src/data/zipcodes.json

Lines 11852 to 11863 in b6487fc

	{
	"city_name": "Le Locle",
	"zipcode": 2400,
	"community_name": "",
	"canton": ""
	},
	{
	"city_name": "Le Locle",
	"zipcode": 2400,
	"community_name": "Le Locle",
	"canton": "NE"
	},

Throws exception if passed zipcode is not an integer

1. What's your issue?

Package throws an error if zipcode was provided as string instead of an integer.

2. Which PHP Version are you using?

I'm using PHP Version 7.0.

3. Which Version of the php-swiss-cantons Package are you using?

I'm using version 1.2.0.

4. In which context are you using the package? (Code Example goes here)

$canton = $cantonManager->getByZipcode('8000');

// Workaround:
$canton = $cantonManager->getByZipcode(intval('8000'));

5. What did you expect to happen in the first place?

Don't throw an exception :)

Allow search by zip code

It would be helpful if a canton could also be found by zip code.

$canton = $cantonManager->getByZipCode(8001);

Keep Zipcode Dataset automatically up to date

The original zipcode data set has been downloaded from cadastre.ch in 2016.
Between 2016 and now, there have probably been some changes: Cities merged with other cities and received a new zipcode, Cities switched Cantons, etc.

I would like to add some bit of code (little bash script) to automatically download the latest dataset from a trusted source. Maybe we can use the open sourced data of the Swiss Post? (https://swisspost.opendatasoft.com/explore/dataset/politische-gemeinden_v2/table/)

If possible, it would also be great to automate this step. GitHub Actions makes it easy to schedule a monthly workflow to execute some scripts.

Related Issues

• #27 (comment)

Zipcodes 8060 and 7001 not found in data files

Found that the following zipcodes are not in the data files:

8060 - Should be Zürich
7001 - City of Chur

Thanks for this great extension