Deal with swiss zip codes, cantons and communities, using the official swiss post mat[ch] database.
Install the gem:
gem install swissmatch-location
Depending on how you installed rubygems, you have to use
sudo gem install swissmatch-location
To automatically load the datafiles:
Due to a change in the license agreement of the swiss post, I'm no longer allowed to ship the data together with the gem. Here's a guide on how to install and update your swissmatch data:
- Go to https://www.post.ch/de/pages/downloadcenter-match
- In the pop-up menu top-left select "Register"
- Once you're registered (you'll get a snail-mail letter from the post to sign), you visit the same page again and this time you choose "Login" from the pop-up menu top-left, the login button top right does not work for this! (the former logs you into the downloadcenter, the latter into the customer center).
- After login, you choose the download page for "Address master data" (de: "Adressstammdaten", fr: "Base de données d'adresses de référence", it: "Banca dati indirizzi di riferimento")
- Download "Existing data" (de: "Bestand", fr: "Etat", it: "Versione completa")
- Unzip the file
- Open a shell and cd into the directory with the unzipped master data
swissmatch-location install-data PATH_TO_MASTER_DATA_FILE
You can test your installation by running
swissmatch-location stats. It should
tell you the age of the data and a number >0 of zip codes.
A negative age is possible since the swiss post provides files which start to be valid in the future.
require 'swissmatch/location/autoload' # use this to automatically load the data # Get all zip codes for a given code, the example returns the official name of the first SwissMatch.zip_codes(8000).first.name # => "Zürich"(de, 0) # Get a single zip code, uniquely identified by the 4 digit code and the 2 digit add-on SwissMatch.zip_code(8000, 0).name # => "Zürich"(de, 0) # Get all names of a zip code for any given language (or all languages) SwissMatch.zip_code(8000, 0).names(:it) # => ["Zurigo"(it, 3)] # Get the suggested name for a zip code for a given language, avoiding issues with # zip codes that have multiple or no name for a given language. SwissMatch.zip_code(8000, 0).suggested_name(:it) # => "Zurigo"(it, 3) # Get a zip code by 4 digit code and name, get its add-on SwissMatch.zip_code(8000, "Zürich").add_on # => 0 # SwissMatch also provides data over the swiss cantons (Kantone) SwissMatch.canton("ZH").name(:it) # => "Zurigo" SwissMatch.canton("Zurigo").name # => "Zürich" # SwissMatch also provides data over swiss communities (Gemeinden) SwissMatch.community("Zürich").community_number # => 261 SwissMatch.community(261).name # => "Zürich"
SwissMatch and Rails/Databases
If you want to load the data into your database, or use it in a rails project, then you should look at swissmatch-rails. It provides a couple of models and a data loading script.
Notable Recent Changes
0.1.2.x -> 1.0.0
- Zip code master data is no longer bundled with the gem. Check the installation guide for how to obtain, install and update the data.
- swissmatch-location executable added to support the installation and updating of the master data
- SwissMatch.communities and SwissMatch::Location.communities no longer return communities by name. This has moved to the .community methods since community names are unique now.
- SwissMatch::Location::Converter has been added to convert the new data format into a compact data file (~140MB down to ~400KB)
- SwissMatch::Location::DataFiles rewritten to read the new compact master data file.
- Dropped rubyzip dependency.
Relevant Classes and Modules
- Convenience methods to access cantons, communities and zip codes
- Swiss canton collection
- A swiss canton
- Swiss communities collection
- A swiss community
- Swiss zip code collection
- A swiss zip code (a zip code can be described and uniquely identified by either code and city, code and add-on or the swiss posts ONRP)
- Main Project
- Online API Documentation
- Public Repository
- Bug Reporting
- RubyGems Site
- Swiss Posts MAT[CH]
You can use this code under the BSD-2-Clause License, free of charge. If you need a different license, please ask the author.