Postal Code Resolver

This library resolves a postal code to a corresponding city or state.

Modes of operation

The library was designed to be minimal and responsive. It provides two transparent modes of operation.

  1. Fetch from file with reactive caching (default).

    Loading tens of thousands of records into memory can take several 100s of milliseconds and consume about 10 MB of RAM per 50k records. To avoid this overhead, the library fetches results from file. However, if a postal code query is successful, that record will be cached in memory.

    Fetching is performed using your system's grep command in a separate process. This generally performs faster and without the memory consumption compared to using native Ruby file parsing.

  2. Fetch from memory with proactive caching.

    If you do not want to hit the disk file because your OS's disk caching algorithms suck, or your system's grep command is inadequate, or you just want 100% blazing fast response for every query, then loading the entire postal code database into memory is for you. It's as simple as calling: PostalCode.load_cache.

Postal code data source

PostalCode uses a minimum required set of data (i.e., postal code, city, state) from the GeoNames.org geographical database.

Currently, the implementation is US only. As of January 15, 2015, the database contains 43,629 US postal code records.

Please give credit to GeoNames when you use this library. See their terms & conditions for details.

The genesis

This library was designed for an e-commerce site. On the actual site, customers enter their postal code into the shopping cart to calculate the shipping cost. Once the postal code is known, the city and state can be automatically populated in the shipping form later in the checkout process. Less typing makes customers happy!

Prior to this library, a third-party Google service was used via a Ruby Gem, which will remain unnamed. The remote call to the service was synchronous, which sometimes slowed or hanged the checkout process.

Then one day Google deprecated their API, which broke the Gem and consequently the site's checkout.

I decided against using another web service because of the fragility of such systems. I wanted something robust and responsive. Thus PostalCode was written!

Examples

First things first!

require 'postal_code'

All postal code parameters must be strings. See PostalCode.valid_format? for details.

Find a state

PostalCode.state '85001'       #=> "AZ"

Find a city

PostalCode.city '85001'        #=> "Phoenix"
PostalCode.city '85001-1234'   #=> "Phoenix"

Resolve a nonexistent postal code

PostalCode.city  '00000'       #=> nil
PostalCode.state '00000'       #=> nil

Load entire postal code database into memory

PostalCode.load_cache

Subsequent queries will be fetched directly from memory.

Clear postal code database from memory

PostalCode.clear_cache

Subsequent queries will be fetched directly from the database file. However, successful queries will be cached.

Caveats

Of the 43,000+ US postal codes in the database, 43 reside within two cities. In the case of this rare ambiguity, the last record for the given postal code is returned.

To put this in perspective, if the entire population was evenly distributed among all the postal codes and every single person used this library to find his or her city, it would be incorrect for less than 0.01% of the population.

Furthermore, GeoNames.org does not guarantee the completeness or accuracy of their data.

Homepage

ecentryx.com/gems/postal_code

Ruby Gem

rubygems.org/gems/postal_code

Source Code

bitbucket.org/pachl/postal_code/src

Bug Tracker

bitbucket.org/pachl/postal_code/issues

History

  1. 2014-05-02, v0.0.1

    • First public release.

  2. 2015-01-15, v0.2.0

    • Add rake task to update postal code database.

    • Update US database.

    • Change database extension from “csv” to “tsv” because we're using tabs.

    • Fix tests.

  3. 2015-01-15, v0.3.0

    • Add 4 new ZIP codes to US database.

    • Add rake task to upload RDoc HTML files to public server.

  4. 2016-04-12, v0.3.1

    • Update US database.

  5. 2016-08-10, v0.3.2

    • Update US database. (14 additions and 2,662 deletions)

  6. 2017-04-07, v0.3.3

    • Update US database. (427 additions and 468 deletions)

  7. 2017-06-03, v0.3.4

    • Fix deprecated test code.

  8. 2017-12-04, v0.3.5

    • Update US database. (515 additions and 7 deletions)

License

(ISC License)

Copyright © 2017, Clint Pachl <pachl@ecentryx.com>

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.