Project

zipcode-db

0.0
No commit activity in last 3 years
No release in over 3 years
Uniformly query city information by zip/postal code and city name.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

>= 0
>= 0
 Project Readme

zipcode-db

Unified interface to query international zip/postal codes

Build Status

Usage

require 'zipcode-db'
require 'zipcode-fr'                 # load data source per country
require 'zipcode-de'

# load data banks individually, typically builds memory-backed global index
ZipCode::FR.load
ZipCode::DE.load

ZipCode::DB.for(:fr).search(:zip, '50000')     # exact zip code search
ZipCode::DB.for(:fr).search(:zip, '50')        # prefixes work
ZipCode::DB.for(:fr).search(:name, 'PARIS')    # search by name
ZipCode::DB.for(:fr).search(:name, 'BORD')     # prefixes work
ZipCode::DB.for(:fr).search(:name, 'MARIE')    # prefixes work on inner words
ZipCode::DB.for(:de).search(:name, 'BERLIN')   # another country

Main fields are:

  • :name: normalised name without diacritics nor symbols
  • :zip: zip code, as used by postal service

Extra fields can be provided depending on data source. See the correspondig gem documentation.

Extending data

Defining a new database is as simple as creating a class defining a search method complying with expectations, and registering it as a country:

require 'zipcode-db'

class MyZipCodeData
  def search(key, value)
    return [{name: 'foo', zip: '42']
  end
end

ZipCode::DB.register(:mine, MyZipCodeData)

The storage, indexing and search itself is delegated to each class.

License

MIT