What

ZipCodeSearch is a Rails plugin that makes implementing location-based searches a cinch. If you've ever wondered how to do location-based radius searches in your snazzy new Web 2.0 application, then this plugin might save you some time.

This plugin will create a ZipCode model, which contains all the code for calculating distances and searching. This plugin will also create a migration that adds a zip code table to your database, complete with 45,000 zip codes and with their lat/lon and city/state information. Finally, this plugin will generate a fully functional controller/view that contains a simple example of how to use the ZipCode model for your location searches.

Why

This plugin is the direct result of my work on WalkingBoss. It powers the location search part of the site. I decided to make this into a plugin to avoid writing and re-writing it time and time again, since it seems as though every project I work on now requires some kind of zip code based search.

How

The radius calculation algorithm in this plugin is based on C# code featured in an article on CodeProject by Thomas Kurek. Thanks Thomas!!! It uses an approximation of the WGS-84 datum to calculate distances, which gives greater accuracy than simpler methods that assume a spherical model of the Earth.

The free zip code data provided can be found online at http://www.cfdynamics.com/zipbase/. This data will be automatically imported in the migration that is generated by this plugin, but, if you can afford it, I recommend buying data from ZipCodeWorld. They are relatively inexpensive and you can be sure the data is clean, recent, and accurate.

Examples/Docs

An example controller is generated by this plugin. You should consult the code in the example controller to see how the search method works. In general, here's how you install the plugin: 

  > ruby script/plugin install  svn://rubyforge.org/var/svn/zipcodesearch/trunk
  > ruby script/generate zip_code_search ZipCode

The 'generate' comand above will create the following output: 

  exists  app/models/
  create  app/models/zip_code.rb
  exists  db/migrate
  create  db/migrate/001_create_zip_codes.rb
  exists  app/controllers/
  create  app/views/zip_code_search_example
  create  app/controllers/zip_code_search_example_controller.rb
  create  app/views/zip_code_search_example/index.rhtml

Note that you can skip the migration or the example controller/view by passing the '-m' or '-e' options, respectively. For example: 

 > ruby script/generate zip_code_search -m ZipCode

If you'd like to use the free zip code data provided with the plugin, you can kick off the migration and go have a cup of coffee (it will take several minutes): 

  rake migrate
  (in /Users/doug/work/zip_plugin/zc_plugin)
  == CreateZipCodes: migrating ==================================================
  -- create_table("zip_codes", {:force=>true})
  -> 0.0536s
  == CreateZipCodes: migrated (624.1958s) =======================================

If you'd like to use your own zip code data, you should make sure it has the fields listed in the db/migrate/*_create_zip_codes.rb file.

Once you have zip code data in the appropriate table (such that the app/models/zip_code.rb model can see it), you can fire up webrick or whatever you use for development and go to http://localhost:3000/zip_code_search_example/index to test it out. You probably want to have a look at the app/controllers/zip_code_search_example_controller.rb file to see how to use the ZipCode model to search.

Who

My name is Doug Fales. I'm a software consultant in Boulder, Colorado, who loves ruby but would rather be fishing or skiing most days. If you would like to contact me about anything (bugs, patches, or freelance work), I can be reached at: doug [dot] fales [at] gmail [dot] com.