README

Summary

Deal with swiss zip codes, cantons and communities, using the official swiss post mat[ch] database.

Installation

Install the gem: gem install swissmatch-location
Depending on how you installed rubygems, you have to use sudo: sudo gem install swissmatch-location
In Ruby: require 'swissmatch/location'
To automatically load the datafiles: require 'swissmatch/location/autoload'

IMPORTANT!

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:

  1. Go to https://www.post.ch/de/pages/downloadcenter-match
  2. In the pop-up menu top-left select "Register"
  3. 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).
  4. 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")
  5. Download "Existing data" (de: "Bestand", fr: "Etat", it: "Versione completa")
  6. Unzip the file
  7. Open a shell and cd into the directory with the unzipped master data
  8. Run 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.

Usage

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

License

You can use this code under the BSD-2-Clause License, free of charge. If you need a different license, please ask the author.

Credits