zipcoder 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81f8212570017ee9537ad0ff17af68e6d4abec2d
-  data.tar.gz: c24abbd919537c6ebcc4d9f21f72abff19979613
+  metadata.gz: 167924f1ab89a79ad0abf1e38fc06346dadc10d8
+  data.tar.gz: b9c9d73b3facea10d02c92970fc2f7bfb8fa078c
 SHA512:
-  metadata.gz: b6c6b76529f9741f02b1e46c743452b496483d72b89e2c4d0cb164646aa5764d6fd2ed3e9e63760cfc12f98606bc96066fb66ea50be1a12b5c3ca8906301b069
-  data.tar.gz: 16f706497a1007b065a70aa50bcc08c3b94c7934da54f682601751065b8ce47727922a993089d11d7273f1e534e82eb0c861787f24b6131a2be73ea5006661e3
+  metadata.gz: 28eb144189cb04c3b097b5c8bb25635d2170999a89a0f3dd55c3d5f52383a6e43ca3251556e76c647abf38a52231ef10c22090f5581cfd78784fd8b93191d521
+  data.tar.gz: 206ae14c6b611a25f0d5bd790257083684e60b9c88313543ea3c6608126e3f39c4a7d48dc24ea71e7433159199b6dcba14aae847904e4a3bed3a24846da0671e

data/README.md

@@ -7,6 +7,10 @@ Gem for performing zip code lookup operations
 
 ## Revision History
 
+ - v0.3.0:
+   - API Change!! - intitialization method change from "load_data" to "load_cache"
+   - added city and state caches
+   - added "cities" call
  - v0.2.0:
    - Internal code rework
    - API Change!! - changed "city,state" to return normalized info rather
@@ -42,17 +46,19 @@ when application is loaded, you can do the following RAILS example
 
 ``` ruby
 require 'zipcoder'
-Zipcoder.load_data
+Zipcoder.load_cache
 ```
 
-This will immediately load the data structures
+This will immediately load the data structures.  Currently it takes roughly 3s
+to create and import all of the data structures.  I will look at ways to
+reduce this later.
 
 ### Methods
 
 The library overrides the String (and in some instances Integer) class to 
 provide the following methods
 
-#### Lookup Zip Code
+#### "zip".zip_info
 
 This will return information about the zip code
 
@@ -84,7 +90,7 @@ puts "78748".zip_info(keys: [:city, :state])
 # > {:city=>"AUSTIN", :state=>"TX"}
 ```
 
-#### Lookup City
+#### "city, state".city_info
 
 This will return info about a city
 
@@ -117,6 +123,39 @@ puts "Austin, TX".city_info(keys: [:zip])
 # > {:zip=>"78701-78799"}
 ```
 
+#### "state".cities
+
+This will return the cities in a state
+
+``` ruby
+require 'zipcoder'
+
+puts "TX".cities
+# > {:zip=>"78701-7879", :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
+
+``` ruby
+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 

data/lib/ext/string.rb

@@ -10,6 +10,10 @@ class String
     Zipcoder.city_info self, **kwargs
   end
 
+  def cities(**kwargs)
+    Zipcoder.cities self, **kwargs
+  end
+
   def to_zip
     self
   end

data/lib/zipcoder/version.rb

@@ -1,3 +1,3 @@
 module Zipcoder
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/zipcoder.rb

@@ -6,10 +6,12 @@ require "yaml"
 module Zipcoder
 
   # Data Structure Load and Lookup
-  @@zip_data = nil
-  def self.zip_data
-    self.load_data if @@zip_data == nil
-    @@zip_data
+  @@zip_cache = nil
+  def self.zip_cache
+    if @@zip_cache == nil
+      self.load_cache
+    end
+    @@zip_cache
   end
 
   @@city_cache = {}
@@ -17,12 +19,52 @@ module Zipcoder
     @@city_cache
   end
 
+  @@state_cache = {}
+  def self.state_cache
+    @@state_cache
+  end
+
   # Loads the data into memory
-  def self.load_data
+  def self.load_cache
     this_dir = File.expand_path(File.dirname(__FILE__))
 
+    # Load zip cache from file
     zip_data = File.join(this_dir, 'data', 'zip_data.yml')
-    @@zip_data = YAML.load(File.open(zip_data))
+    @@zip_cache = YAML.load(File.open(zip_data))
+
+    # Iterate through zip codes to populate city and state data
+    city_states = {}
+    self.zip_cache.values.each do |info|
+      city = info[:city]
+      state = info[:state]
+
+      # Create the city lookups
+      city_state = "#{city},#{state}"
+      infos = city_states[city_state] || []
+      infos << info
+      city_states[city_state] = infos
+    end
+
+    # Normalize each city and populate the state cache
+    city_states.each do |city_state, infos|
+      state = infos[0][:state]
+
+      # Populate the City Cache
+      normalized = self.city_info(city_state, infos)
+      self.city_cache[city_state] = normalized
+
+      # Populate the State Cache
+      cities = self.state_cache[state] || []
+      cities << normalized
+      self.state_cache[state] = cities
+    end
+
+    # Sort the city arrays
+    self.state_cache.keys.each do |state|
+      infos = self.state_cache[state]
+      new_infos = infos.sort_by { |hsh| hsh[:city] }
+      self.state_cache[state] = new_infos
+    end
   end
 
   # Looks up zip code information
@@ -31,7 +73,7 @@ module Zipcoder
     # If zip is not nil, then we are returning a single value
     if zip != nil
       # Get the info
-      info = self.zip_data[zip.to_zip]
+      info = self.zip_cache[zip.to_zip]
 
       # Inform callback that we have a match
       block.call(info) if block != nil
@@ -41,12 +83,12 @@ module Zipcoder
     else
       # If zip is nil, then we are returning an array of values
 
-      infos = []
       city_filter = kwargs[:city] != nil ? kwargs[:city].upcase : nil
       state_filter = kwargs[:state] != nil ? kwargs[:state].upcase : nil
 
       # Iterate through and only add the ones that match the filters
-      self.zip_data.values.each { |info|
+      infos = []
+      self.zip_cache.values.each { |info|
         if (city_filter == nil or info[:city] == city_filter) and
             (state_filter == nil or info[:state] == state_filter)
           infos << self._filter_hash_args(info, kwargs[:keys])
@@ -61,7 +103,7 @@ module Zipcoder
   end
 
   # Looks up city information
-  def self.city_info(city_state, **kwargs)
+  def self.city_info(city_state, infos=nil, **kwargs)
     unless city_state.include? ','
       raise Exception, "city/state must include ','"
     end
@@ -78,7 +120,49 @@ module Zipcoder
     city = components[0].strip.upcase
     state = components[1].strip.upcase
 
-    # Normalize response
+    # Get the infos
+    infos ||= self.zip_info(city: city, state: state)
+    info = self._normalize_city(infos)
+    if info != nil
+      info[:city] = city
+      info[:state] = state
+    end
+
+    # Cache the value
+    self.city_cache[cache_key] = info if info != nil
+
+    # Filter the args
+    self._filter_hash_args info, kwargs[:keys]
+  end
+
+  # Returns the cities in a state
+  def self.cities(state, **kwargs)
+    state = state.strip.upcase
+
+    # Filter the returned cities
+    infos = []
+    self.state_cache[state].each { |info|
+      infos << self._filter_hash_args(info, kwargs[:keys])
+    }
+
+    infos
+  end
+
+  # Filters arguments in return hash
+  def self._filter_hash_args(hash, keys)
+    return nil if hash == nil
+
+    if keys != nil
+      new_hash = {}
+      keys.each { |k| new_hash[k] = hash[k] }
+      hash = new_hash
+    end
+    hash
+  end
+
+  # Normalizes the values
+  def self._normalize_city(infos)
+    # Values
     zip_min = 100000
     zip_max = 0
     lat_min = 200
@@ -86,10 +170,8 @@ module Zipcoder
     long_min = 200
     long_max = 0
 
-    # Get the infos associated with this city/state.  While
-    # getting those, store the min/max so we can create a
-    # normalized version of this object
-    infos = self.zip_info(city: city, state: state) do |info|
+    # Iterate through the info and get min/max of zip/lat/long
+    infos.each do |info|
       zip = info[:zip].to_i
       zip_min = zip if zip < zip_min
       zip_max = zip if zip > zip_max
@@ -99,40 +181,24 @@ module Zipcoder
       long_max = info[:long] if info[:long] > long_max
     end
 
+    # Create the normalized value
     if infos.count == 0
-      # If there were no matches, return 0
-      info = nil
+      normalized = nil
     elsif infos.count == 1
-      # If there was 1 match, return it
-      info = infos[0]
+      normalized = {
+          zip: infos[0][:zip],
+          lat: infos[0][:lat],
+          long: infos[0][:long],
+      }
     else
-      # Create normalized object
-      info = {
+      normalized = {
           zip: "#{zip_min.to_zip}-#{zip_max.to_zip}",
-          city: city,
-          state: state,
           lat: (lat_min+lat_max)/2,
           long: (long_min+long_max)/2
       }
     end
 
-    # Cache the value
-    self.city_cache[cache_key] = info if info != nil
-
-    # Filter the args
-    self._filter_hash_args info, kwargs[:keys]
-  end
-
-  # Filters arguments in return hash
-  def self._filter_hash_args(hash, keys)
-    return nil if hash == nil
-
-    if keys != nil
-      new_hash = {}
-      keys.each { |k| new_hash[k] = hash[k] }
-      hash = new_hash
-    end
-    hash
+    normalized
   end
 
 end

data/spec/zipcoder_spec.rb

@@ -1,14 +1,7 @@
 require "spec_helper"
+require 'benchmark'
 
 describe Zipcoder do
-  before(:all) do
-    described_class.load_data
-  end
-
-  before(:each) do
-    described_class.city_cache.clear
-  end
-
   it "has a version number" do
     expect(Zipcoder::VERSION).not_to be nil
   end
@@ -92,27 +85,40 @@ describe Zipcoder do
       expect(city_info[:long]).to eq(-48.87)
     end
 
-    it "caches the unfiltered value" do
-      expect {
-        described_class.city_info "Austin, TX", keys: [:zip, :lat, :long]
-      }.to change{ described_class.city_cache.values.count }.by(1)
+    it 'returns nil on mismatch' do
+      city_info = described_class.city_info "Bad City, TX"
+      expect(city_info).to be_nil
+    end
 
-      expect {
-        described_class.city_info "Austin, TX"
-      }.to change{ described_class.city_cache.values.count }.by(0)
+  end
 
-      city_info = described_class.city_info "Austin, TX"
-      expect(city_info[:city]).to eq("AUSTIN")
+  describe "#cities" do
+    it "returns the cities for a state" do
+      cities = described_class.cities "TX"
+      expect(cities.count).to eq(1170)
+
+      city_info = cities[0]
+      expect(city_info[:city]).to eq("ABBOTT")
       expect(city_info[:state]).to eq("TX")
-      expect(city_info[:zip]).to eq("78701-78799")
-      expect(city_info[:lat]).to eq(30.315)
-      expect(city_info[:long]).to eq(-48.87)
+      expect(city_info[:zip]).to eq("76621")
+      expect(city_info[:lat]).to eq(31.88)
+      expect(city_info[:long]).to eq(-97.07)
     end
-  end
+    it "returns the cities for a state filtered" do
+      cities = described_class.cities "TX", keys: [:zip, :city]
+      expect(cities.count).to eq(1170)
 
+      city_info = cities[0]
+      expect(city_info[:city]).to eq("ABBOTT")
+      expect(city_info[:state]).to be_nil
+      expect(city_info[:zip]).to eq("76621")
+      expect(city_info[:lat]).to be_nil
+      expect(city_info[:long]).to be_nil
+    end
+  end
 
   describe("String") do
-    describe "zip lookup" do
+    describe "zip_info" do
       it "returns the info for a particular zip_code" do
         zip_info = "78748".zip_info
         expect(zip_info[:city]).to eq("AUSTIN")
@@ -132,7 +138,7 @@ describe Zipcoder do
       end
     end
 
-    describe "city lookup" do
+    describe "city_info" do
       it "returns the info for a particular city" do
         city_info = "Austin, TX".city_info
         expect(city_info[:city]).to eq("AUSTIN")
@@ -150,6 +156,31 @@ describe Zipcoder do
         expect(city_info[:long]).to be_nil
       end
     end
+
+    describe "cities" do
+      it "returns the cities for a state" do
+        cities = "TX".cities
+        expect(cities.count).to eq(1170)
+
+        city_info = cities[0]
+        expect(city_info[:city]).to eq("ABBOTT")
+        expect(city_info[:state]).to eq("TX")
+        expect(city_info[:zip]).to eq("76621")
+        expect(city_info[:lat]).to eq(31.88)
+        expect(city_info[:long]).to eq(-97.07)
+      end
+      it "returns the cities for a state filtered" do
+        cities = "TX".cities keys: [:zip, :city]
+        expect(cities.count).to eq(1170)
+
+        city_info = cities[0]
+        expect(city_info[:city]).to eq("ABBOTT")
+        expect(city_info[:state]).to be_nil
+        expect(city_info[:zip]).to eq("76621")
+        expect(city_info[:lat]).to be_nil
+        expect(city_info[:long]).to be_nil
+      end
+    end
   end
 
   describe("Integer") do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zipcoder
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Eric Chapman