zip_meta¶ ↑

zip_meta is a Rails plugin that supplies a simple “zip_meta” helper method to your app’s controllers and views that, when passed a US zip code (either as a string or a fixnum), gives you a hash of the following associated meta info:

• city (String)

• state (String)

• latitude (Float)

• longitude (Float)

• timezone (Integer)

The plugin queries a table populated with zip code meta info, and you’ll need to run a migration (see section below) to create and populate this table. This gem was written to solve an issue encountered during the ongoing development of Secure Scheduling.

Installation¶ ↑

To use this gem in your Rails app, add an appropriate entry to your Gemfile:

gem 'zip_meta'

The zip_meta method queries a database table populated with the contents of the ‘zipcodes.csv’ file (which can be found in zip_meta/lib/data) originally published by CivicSpace Labs in 2004. You’ll need to generate and run a migration to create and populate this table. To do so, run:

rails generate zip_meta_migration && rake db:migrate

The zipcodes.csv file whose data the migration loads into the zip_meta table contains > 43,000 rows, so be patient (on my 2009 MacBook Pro, the migration takes ~11 seconds to run).

Once you’ve run the migration, you’ll be able to use the “zip_meta” method from within your controllers and views to query meta info for any US zip code!

Example Usage¶ ↑

class MapItemsController < ApplicationController
  # (...assuming we have a MapItem model with a string or fixnum "zipcode" property...)
  def show
    @map_item = MapItem.find(params[:id])
    @location_details = zip_meta(@map_item.zipcode)
    # => {:zip=>"10003", :city=>"New York", :state=>"NY", :latitude=>40.732509, :longitude=>-73.98935, :timezone=>-5}
  end
end

Running Tests¶ ↑

This gem uses Rspec for testing.  To run tests:

  $ rspec spec

from the project's root directory