Zipcoder

Gem Version Circle CI Codecov

Gem for performing zip code lookup operations

Revision History

  • v0.2.0:
    • Internal code rework
    • API Change!! - changed "city,state" to return normalized info rather than array of zips, lats, longs
  • v0.1.0:
    • Initial Revision

Installation

Add this line to your application's Gemfile:

gem 'zipcoder'

And then execute:

$ bundle

Or install it yourself as:

$ gem install zipcoder

Usage

Setup

By default, the library will lazy-load the data structures when you first try to use it. If you would like to have the data structures already loaded when application is loaded, you can do the following RAILS example

config/initializers/zipcoder.rb:

require 'zipcoder'
Zipcoder.load_data

This will immediately load the data structures

Methods

The library overrides the String (and in some instances Integer) class to provide the following methods

Lookup Zip Code

This will return information about the zip code

require 'zipcoder'

puts "78748".zip_info
# > {:zip=>"78748", :city=>"AUSTIN", :state=>"TX", :lat=>30.26, :long=>-97.74}

Note that this also works with Integer zip codes, for example

require 'zipcoder'

puts 78748.zip_info
# > {:zip=>"78748", :city=>"AUSTIN", :state=>"TX", :lat=>30.26, :long=>-97.74}
"keys" argument

You can filter the keys that are returned by including the "keys" argument as shown below

require 'zipcoder'

puts "78748".zip_info(keys: [:city, :state])
# > {:city=>"AUSTIN", :state=>"TX"}

Lookup City

This will return info about a city

require 'zipcoder'

puts "Austin, TX".city_info
# > {:zip=>"78701-78799", :city=>"AUSTIN", :state=>"TX", :lat=>30.26, :long=>-97.74}

Notes:

  • the "zip", "lat", "long" are the combined values from all of the individual zip codes
  • the library will normalize the key by removing all of the whitespace and capitalizing the letters. So for example, "Austin, TX" becomes "AUSTIN,TX"
  • the library will cache the normalized cities to improve performance on subsequent calls
"keys" argument

You can filter the keys that are returned by including the "keys" argument as shown below

require 'zipcoder'

puts "Austin, TX".city_info(keys: [:zip])
# > {:zip=>"78701-78799"}

Updating Data

The library is using the free public zip code data base located here. To update the database, run the following at command line from the top directory

%> rake zipcoder:update  # Pulls the latest CSV file from the website
%> rake zipcoder:convert  # Updates the zipcoder data structures

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ericchapman/zipcoder.

License

The gem is available as open source under the terms of the MIT License.