zipcoder 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 167924f1ab89a79ad0abf1e38fc06346dadc10d8
-  data.tar.gz: b9c9d73b3facea10d02c92970fc2f7bfb8fa078c
+  metadata.gz: 5a3ed8a72bc6297d47835fa432a6ef7329afa105
+  data.tar.gz: dcd374d44e39bc8a7c11991a3e7e7d6ebd232c03
 SHA512:
-  metadata.gz: 28eb144189cb04c3b097b5c8bb25635d2170999a89a0f3dd55c3d5f52383a6e43ca3251556e76c647abf38a52231ef10c22090f5581cfd78784fd8b93191d521
-  data.tar.gz: 206ae14c6b611a25f0d5bd790257083684e60b9c88313543ea3c6608126e3f39c4a7d48dc24ea71e7433159199b6dcba14aae847904e4a3bed3a24846da0671e
+  metadata.gz: 9fe034ee31e6ee82c61d4b4aba9b0a2a61635b81e236ceafb2100e858d27e2e842e2e8c43a88db5d6234cc05b18c1b57f3bdd6c6e31e9256d1fb55f3eb3bdadf
+  data.tar.gz: ba288abb61c112e26c09e7788792b30123634bb69af4d93cdf0007e67c4eacd2a46f8e77bcef2c946ab283636985dcb3caa95f4a54e088d5d8684051d4bdf359

data/README.md

@@ -7,6 +7,13 @@ Gem for performing zip code lookup operations
 
 ## Revision History
 
+ - v0.4.0:
+   - abstracted "cacher" object to later support "redis" and "memcacher"
+   - API Change!! - changed name of "cities" to "state_cities"
+   - added "names_only" option to "state_cities"
+   - added "states" method that returns list of states
+   - added "zip_cities" method that returns the cities associated with a
+     list of zip codes
  - v0.3.0:
    - API Change!! - intitialization method change from "load_data" to "load_cache"
    - added city and state caches
@@ -58,104 +65,178 @@ reduce this later.
 The library overrides the String (and in some instances Integer) class to 
 provide the following methods
 
-#### "zip".zip_info
+#### Method: Zipcoder.zip_info(zip, **args)
 
-This will return information about the zip code
+Returns the info for the "zip"
+
+**variations:**
+
+ - ```Zipcoder.zip_info(78748, **args)```
+ - ```Zipcoder.zip_info("78748", **args)```
+ - ```"78748".zip_info(**args)```
+ - ```78748.zip_info(**args)```
+
+**parameters:**
+
+ - zip [String, Integer] - a string or integer representing a single zip code
+ - **return** [Hash] - zip object
+
+**arguments:**
+
+ - keys [Array] - array of keys to include (filters out the others)
+
+**notes:**
+
+ - none
+ 
+**examples:**
 
 ``` ruby
 require 'zipcoder'
 
+# Looks up a zip code by string
 puts "78748".zip_info
 # > {:zip=>"78748", :city=>"AUSTIN", :state=>"TX", :lat=>30.26, :long=>-97.74}
+
+# Looks up a zip code by integer
+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
+#### Method: Zipcoder.zip_cities(zip_string, **args)
 
-``` ruby
-require 'zipcoder'
+Returns the cities that are covered by the "zip_string"
 
-puts 78748.zip_info
-# > {:zip=>"78748", :city=>"AUSTIN", :state=>"TX", :lat=>30.26, :long=>-97.74}
-```
+**variations:**
 
-##### "keys" argument
+ - ```Zipcoder.zip_cities("78701-78799,78613", **args)```
+ - ```"78701-78799,78613".zip_cities(**args)```
 
-You can filter the keys that are returned by including the "keys" argument
-as shown below
+**parameters:**
 
-``` ruby
-require 'zipcoder'
+ - zip_string [String] - a string containing comma delimited list of
+   zip codes and zip code ranges (ex. "78701-78750, 78613")
+ - **return** [Array] - array of zip objects or names (if "names_only"
+   is specified)
 
-puts "78748".zip_info(keys: [:city, :state])
-# > {:city=>"AUSTIN", :state=>"TX"}
-```
+**arguments:**
 
-#### "city, state".city_info
+ - keys [Array] - array of keys to include (filters out the others)
+ - names_only [Bool] - set to "true" if you only want the city names returned
+ - max [Integer] - maximum number of cities to return
+ 
+**notes:**
 
-This will return info about a city
+ - none
+ 
+**examples:**
 
 ``` ruby
 require 'zipcoder'
 
-puts "Austin, TX".city_info
-# > {:zip=>"78701-78799", :city=>"AUSTIN", :state=>"TX", :lat=>30.26, :long=>-97.74}
+# Returns the cities for a zip_code
+puts "78701-78750,78613".zip_cities
+# > [{:zip=>"78748", :city=>"Austin", :state=>"TX", :lat=>30.26, :long=>-97.74}, ...
+
+# Returns just the name of the cities
+puts "78701-78750,78613".zip_cities names_only: true
+# > ["Austin", "Cedar Park"]
 ```
 
-Notes:
+#### Method: Zipcoder.city_info(city_state, **args)
+
+Returns the zip object for a city
+
+**variations:**
+
+ - ```Zipcoder.city_info("Atlanta, GA", **args)```
+ - ```"zip_string".zip_cities(**args)```
+
+**parameters:**
+
+ - city_state [String] - a string "city, state"
+ - **return** [Hash] - zip object
+
+**arguments:**
+
+ - keys [Array] - array of keys to include (filters out the others)
+ 
+**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
+   and capitalizing the letters.  So for example, " Los Angeles , CA " becomes 
+   "LOS ANGELES,CA"
 
-##### "keys" argument
-
-You can filter the keys that are returned by including the "keys" argument
-as shown below
+**examples:**
 
 ``` ruby
 require 'zipcoder'
 
-puts "Austin, TX".city_info(keys: [:zip])
-# > {:zip=>"78701-78799"}
+puts "Austin, TX".city_info
+# > {:zip=>"78701-78799", :city=>"AUSTIN", :state=>"TX", :lat=>30.26, :long=>-97.74}
 ```
 
-#### "state".cities
+#### Method: Zipcoder.state_cities(state, **args)
 
 This will return the cities in a state
 
+**variations:**
+
+ - ```Zipcoder.state_cities("GA", **args)```
+ - ```"GA".state_cities(**args)```
+ 
+**parameters:**
+
+ - state [String] - the 2 letter state abbreviation
+ - **return** [Array] - list of zip objects (or city names if "names_only")
+   is set
+
+**arguments:**
+
+ - keys [Array] - array of keys to include (filters out the others)
+ - names_only [Bool] - set to "true" if you only want the city names returned
+ 
+**examples:**
+
 ``` ruby
 require 'zipcoder'
 
-puts "TX".cities
-# > {:zip=>"78701-7879", :city=>"AUSTIN", :state=>"TX", :lat=>30.26, :long=>-97.74}
+# Returns Objects
+puts "TX".state_cities
+# > [{:city=>"Abbott", :state=>"TX" ...
+
+# Returns List
+puts "TX".state_cities names_only: true
+# > ["Abbott", ...
 ```
 
-Notes:
+#### Method: Zipcoder.states
 
- - 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
+This will return the states in the US
+
+**variations:**
+
+ - ```Zipcoder.states```
+ 
+**parameters:**
 
-##### "keys" argument
+ - none
 
-You can filter the keys that are returned by including the "keys" argument
-as shown below
+**arguments:**
+
+ - none
+ 
+**examples:**
 
 ``` ruby
 require 'zipcoder'
 
-puts "Austin, TX".city_info(keys: [:zip])
-# > {:zip=>"78701-78799"}
+puts Zipcoder.states
+# > ["AK", "AL", ...
 ```
-
 ### Updating Data
 
 The library is using the free public zip code data base located 

data/lib/ext/string.rb

@@ -6,16 +6,24 @@ class String
     Zipcoder.zip_info self, **kwargs
   end
 
+  def zip_cities(**kwargs)
+    Zipcoder.zip_cities self, **kwargs
+  end
+
   def city_info(**kwargs)
     Zipcoder.city_info self, **kwargs
   end
 
-  def cities(**kwargs)
-    Zipcoder.cities self, **kwargs
+  def state_cities(**kwargs)
+    Zipcoder.state_cities self, **kwargs
   end
 
   def to_zip
     self
   end
 
+  def capitalize_all
+    self.split(' ').map {|w| w.capitalize }.join(' ')
+  end
+
 end

data/lib/zipcoder/cacher/base.rb

@@ -0,0 +1,190 @@
+module Cacher
+  # The cacher base class places all of the objects in memory.  The
+  # abstraction will later allow us to override for MemCacher and
+  # Redis implementations
+  class Base
+
+    #region Override These
+    def _init_cache(**kwargs)
+      @cache = {}
+    end
+
+    def _empty_cache
+      @cache.clear
+    end
+
+    def _write_cache(key, value)
+      @cache[key] = value
+    end
+
+    def _read_cache(key)
+      @cache[key]
+    end
+
+    def _iterate_keys(**kwargs, &block)
+      return if block == nil
+
+      start_with = kwargs[:start_with]
+
+      @cache.keys.each do |key|
+        if start_with == nil or key.start_with?(start_with)
+          block.call(key)
+        end
+      end
+    end
+
+    #endregion
+
+    def initialize(**kwargs)
+      self._init_cache **kwargs
+    end
+
+    def load
+      this_dir = File.expand_path(File.dirname(__FILE__))
+
+      # Load zip cache from file
+      zip_data = File.join(this_dir, '..', '..', 'data', 'zip_data.yml')
+      zip_codes = YAML.load(File.open(zip_data))
+
+      # Initialize
+      _empty_cache
+      city_states = {}
+      state_lookup = {}
+
+      # Add the zip codes to the cache
+      zip_codes.each do |zip, info|
+        city = info[:city].capitalize_all
+        info[:city] = city
+        state = info[:state]
+
+        # Iterate through the zip codes and add them to the zip cache
+        _write_cache _zip_cache(zip), info
+
+        # Create the city lookups
+        city_state = "#{city.upcase},#{state.upcase}"
+        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|
+        city = infos[0][:city]
+        state = infos[0][:state]
+
+        # Populate the City Cache
+        normalized = _normalize_city(infos)
+        _write_cache _city_cache(city_state), normalized
+
+        # Populate the State Cache
+        cities = state_lookup[state] || []
+        cities << city
+        state_lookup[state] = cities
+      end
+
+      # Set the cities cache
+      state_lookup.each do |state, cities|
+        _write_cache _state_cache(state), cities.sort
+      end
+
+      # Set the states cache
+      self._write_cache _states, state_lookup.keys.sort
+    end
+
+    def read_zip_cache(zip)
+      _read_cache _zip_cache(zip)
+    end
+
+    def read_city_cache(city_state)
+      _read_cache _city_cache(city_state)
+    end
+
+    def read_state_cache(state)
+      _read_cache _state_cache(state)
+    end
+
+    def read_states
+      _read_cache _states
+    end
+
+    def iterate_zips(&block)
+      return if block == nil
+      _iterate_keys(start_with: "zipcoder:zip") do |key|
+        info = _read_cache(key)
+        block.call(info) if block != nil
+      end
+    end
+
+    def iterate_cities(&block)
+      return if block == nil
+      _iterate_keys(start_with: "zipcoder:city") do |key|
+        info = _read_cache(key)
+        block.call(info) if block != nil
+      end
+    end
+
+    private
+
+    def _zip_cache(zip)
+      "zipcoder:zip:#{zip}"
+    end
+
+    def _city_cache(city_state)
+      "zipcoder:city:#{city_state}"
+    end
+
+    def _state_cache(state)
+      "zipcoder:state:#{state}"
+    end
+
+    def _states
+      "zipcoder:states"
+    end
+
+    # Normalizes the values
+    def _normalize_city(infos)
+      # Values
+      zip_min = 100000
+      zip_max = 0
+      lat_min = 200
+      lat_max = -200
+      long_min = 200
+      long_max = -200
+
+      # 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
+        lat_min = info[:lat] if info[:lat] < lat_min
+        lat_max = info[:lat] if info[:lat] > lat_max
+        long_min = info[:long] if info[:long] < long_min
+        long_max = info[:long] if info[:long] > long_max
+      end
+
+      # Create the normalized value
+      if infos.count == 0
+        normalized = nil
+      elsif infos.count == 1
+        normalized = {
+            city: infos[0][:city],
+            state: infos[0][:state],
+            zip: infos[0][:zip],
+            lat: infos[0][:lat],
+            long: infos[0][:long],
+        }
+      else
+        normalized = {
+            city: infos[0][:city],
+            state: infos[0][:state],
+            zip: "#{zip_min.to_zip}-#{zip_max.to_zip}",
+            lat: ((lat_min+lat_max)/2).round(4),
+            long: ((long_min+long_max)/2).round(4)
+        }
+      end
+
+      normalized
+    end
+
+  end
+end

data/lib/zipcoder/version.rb

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

data/lib/zipcoder.rb

@@ -1,151 +1,121 @@
 require "zipcoder/version"
+require "zipcoder/cacher/base"
 require "ext/string"
 require "ext/integer"
 require "yaml"
 
 module Zipcoder
 
-  # Data Structure Load and Lookup
-  @@zip_cache = nil
-  def self.zip_cache
-    if @@zip_cache == nil
-      self.load_cache
-    end
-    @@zip_cache
-  end
-
-  @@city_cache = {}
-  def self.city_cache
-    @@city_cache
+  class ZipcoderError < Exception
   end
 
-  @@state_cache = {}
-  def self.state_cache
-    @@state_cache
+  @@cacher = nil
+  def self.cacher
+    if @@cacher == nil
+      self.load_cache
+    end
+    @@cacher
   end
 
   # Loads the data into memory
-  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_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
+  def self.load_cache(cacher=nil)
+    @@cacher = cacher || Cacher::Base.new
+    self.cacher.load
   end
 
   # Looks up zip code information
-  def self.zip_info(zip=nil, **kwargs, &block)
+  def self.zip_info(zip=nil, **kwargs)
 
     # If zip is not nil, then we are returning a single value
     if zip != nil
       # Get the info
-      info = self.zip_cache[zip.to_zip]
-
-      # Inform callback that we have a match
-      block.call(info) if block != nil
+      info = self.cacher.read_zip_cache(zip.to_zip)
 
       # Filter to the included keys
       self._filter_hash_args info, kwargs[:keys]
     else
       # If zip is nil, then we are returning an array of values
-
       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
       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)
+      self.cacher.iterate_zips do |info|
+        if (city_filter == nil or info[:city].upcase == city_filter) and
+            (state_filter == nil or info[:state].upcase == state_filter)
           infos << self._filter_hash_args(info, kwargs[:keys])
-
-          # Inform callback that we have a match
-          block.call(info) if block != nil
         end
-      }
+      end
 
       infos
     end
   end
 
-  # Looks up city information
-  def self.city_info(city_state, infos=nil, **kwargs)
-    unless city_state.include? ','
-      raise Exception, "city/state must include ','"
-    end
+  # Returns the cities that contain the zip codes
+  def self.zip_cities(zip_string, **kwargs)
+    max = kwargs[:max]
+
+    cities = {}
+    self._parse_zip_string(zip_string).each do |zip|
+      info = zip.zip_info
+      if info == nil
+        next
+      end
+
+      cities["#{info[:city]}, #{info[:state]}"] = true
 
-    # Check the cache
-    cache_key = city_state.delete(' ').upcase
-    cached_value = self.city_cache[cache_key]
-    if cached_value != nil
-      return self._filter_hash_args cached_value, kwargs[:keys]
+      if max != nil and cities.keys.count >= max
+        break
+      end
     end
 
-    # Cleanup city/state
-    components = city_state.split(",")
-    city = components[0].strip.upcase
-    state = components[1].strip.upcase
+    cities = cities.keys.uniq.sort
 
-    # 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
+    if kwargs[:names_only]
+      zips = cities.map{ |x| x.split(",")[0].strip }
+    else
+      zips = []
+      cities.each do |key|
+        zips << key.city_info(keys: kwargs[:keys])
+      end
     end
+    zips
+  end
 
-    # Cache the value
-    self.city_cache[cache_key] = info if info != nil
+  # Looks up city information
+  def self.city_info(city_state, **kwargs)
+    # Get the city from the cache
+    cache_key = self._cache_key(city_state)
+    cached_value = self.cacher.read_city_cache(cache_key)
 
-    # Filter the args
-    self._filter_hash_args info, kwargs[:keys]
+    # Return it
+    self._filter_hash_args cached_value, kwargs[:keys]
   end
 
   # Returns the cities in a state
-  def self.cities(state, **kwargs)
+  def self.state_cities(state, **kwargs)
     state = state.strip.upcase
 
+    names_only = kwargs[:names_only]
+    keys = kwargs[:keys]
+
     # Filter the returned cities
-    infos = []
-    self.state_cache[state].each { |info|
-      infos << self._filter_hash_args(info, kwargs[:keys])
-    }
+    cities = self.cacher.read_state_cache(state)
+    if names_only
+      cities
+    else
+      infos = []
+      self.cacher.read_state_cache(state).each { |city|
+        infos << self.city_info("#{city}, #{state}", keys: keys)
+      }
 
-    infos
+      infos
+    end
+  end
+
+  # Returns the states
+  def self.states
+    self.cacher.read_states
   end
 
   # Filters arguments in return hash
@@ -160,45 +130,45 @@ module Zipcoder
     hash
   end
 
-  # Normalizes the values
-  def self._normalize_city(infos)
-    # Values
-    zip_min = 100000
-    zip_max = 0
-    lat_min = 200
-    lat_max = 0
-    long_min = 200
-    long_max = 0
-
-    # 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
-      lat_min = info[:lat] if info[:lat] < lat_min
-      lat_max = info[:lat] if info[:lat] > lat_max
-      long_min = info[:long] if info[:long] < long_min
-      long_max = info[:long] if info[:long] > long_max
+  # Returns a cache key
+  def self._cache_key(city_state)
+    unless city_state.include? ','
+      raise ZipcoderError, "city/state must include ','"
     end
 
-    # Create the normalized value
-    if infos.count == 0
-      normalized = nil
-    elsif infos.count == 1
-      normalized = {
-          zip: infos[0][:zip],
-          lat: infos[0][:lat],
-          long: infos[0][:long],
-      }
-    else
-      normalized = {
-          zip: "#{zip_min.to_zip}-#{zip_max.to_zip}",
-          lat: (lat_min+lat_max)/2,
-          long: (long_min+long_max)/2
-      }
+    components = city_state.split(',')
+    city = components[0].strip.upcase
+    state = components[1].strip.upcase
+
+    "#{city},#{state}"
+  end
+
+  # Parses a zip code string and returns all of the zip codes as
+  # an array
+  def self._parse_zip_string(zip_string)
+    zips = []
+
+    zip_string.split(",").each do |zip_component|
+      if zip_component.include? "-"
+        z = zip_component.split("-")
+        (z[0].strip.to_i..z[1].strip.to_i).each do |zip|
+          zips << self._check_zip(zip.to_zip)
+        end
+      else
+        zips << self._check_zip(zip_component.strip)
+      end
     end
 
-    normalized
+    zips.sort.uniq
+  end
+
+  # Check the zip codes
+  def self._check_zip(zip)
+    if zip.length != 5
+      raise ZipcoderError, "zip code #{zip} is not 5 characters"
+    end
+    zip
   end
 
+
 end

data/spec/zipcoder_spec.rb

@@ -6,10 +6,19 @@ describe Zipcoder do
     expect(Zipcoder::VERSION).not_to be nil
   end
 
+  describe "#states" do
+    it "returns the states" do
+      states = described_class.states
+      expect(states.count).to eq(54)
+      expect(states[0]).to eq("AK")
+      expect(states[1]).to eq("AL")
+    end
+  end
+
   describe "#zip_info" do
     it "returns the info for a particular zip_code" do
       zip_info = described_class.zip_info "78748"
-      expect(zip_info[:city]).to eq("AUSTIN")
+      expect(zip_info[:city]).to eq("Austin")
       expect(zip_info[:state]).to eq("TX")
       expect(zip_info[:zip]).to eq("78748")
       expect(zip_info[:lat]).to eq(30.26)
@@ -18,7 +27,7 @@ describe Zipcoder do
 
     it "returns the info for a particular zip_code" do
       zip_info = described_class.zip_info 78748
-      expect(zip_info[:city]).to eq("AUSTIN")
+      expect(zip_info[:city]).to eq("Austin")
       expect(zip_info[:state]).to eq("TX")
       expect(zip_info[:zip]).to eq("78748")
       expect(zip_info[:lat]).to eq(30.26)
@@ -27,13 +36,13 @@ describe Zipcoder do
 
     it "zero pads the zip code when using an integer" do
       zip_info = described_class.zip_info 705
-      expect(zip_info[:city]).to eq("AIBONITO")
+      expect(zip_info[:city]).to eq("Aibonito")
     end
 
     describe "keys filter" do
       it "only returns specified keys" do
         zip_info = described_class.zip_info "78748", keys: [:city, :state]
-        expect(zip_info[:city]).to eq("AUSTIN")
+        expect(zip_info[:city]).to eq("Austin")
         expect(zip_info[:state]).to eq("TX")
         expect(zip_info[:zip]).to be_nil
         expect(zip_info[:lat]).to be_nil
@@ -52,10 +61,15 @@ describe Zipcoder do
         expect(zip_infos.count).to eq(1745)
       end
 
-      it "returns zip codes that match a particular city/state" do
+      it "returns zip codes that match a particular city and state" do
         zip_infos = described_class.zip_info city: "Austin", state: "TX"
         expect(zip_infos.count).to eq(47)
       end
+
+      it "returns zip codes that match a particular city with spaces and state" do
+        zip_infos = described_class.zip_info city: "San Antonio", state: "TX"
+        expect(zip_infos.count).to eq(65)
+      end
     end
 
   end
@@ -64,16 +78,25 @@ describe Zipcoder do
     it "raises exception if no ','" do
       expect {
         described_class.city_info "Austin TX"
-      }.to raise_error(Exception)
+      }.to raise_error(Zipcoder::ZipcoderError)
     end
 
     it "returns the normalized city/state value" do
       city_info = described_class.city_info "Austin, TX"
-      expect(city_info[:city]).to eq("AUSTIN")
+      expect(city_info[:city]).to eq("Austin")
       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[:long]).to eq(-97.71)
+    end
+
+    it "returns the normalized city/state value with space" do
+      city_info = described_class.city_info " San Antonio , TX"
+      expect(city_info[:city]).to eq("San Antonio")
+      expect(city_info[:state]).to eq("TX")
+      expect(city_info[:zip]).to eq("78201-78285")
+      expect(city_info[:lat]).to eq(29.435)
+      expect(city_info[:long]).to eq(-98.495)
     end
 
     it "returns the normalized city/state filtered" do
@@ -82,7 +105,7 @@ describe Zipcoder do
       expect(city_info[:state]).to be_nil
       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[:long]).to eq(-97.71)
     end
 
     it 'returns nil on mismatch' do
@@ -92,36 +115,103 @@ describe Zipcoder do
 
   end
 
-  describe "#cities" do
+  describe "#state_cities" do
     it "returns the cities for a state" do
-      cities = described_class.cities "TX"
+      cities = described_class.state_cities "TX"
       expect(cities.count).to eq(1170)
 
       city_info = cities[0]
-      expect(city_info[:city]).to eq("ABBOTT")
+      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 = described_class.cities "TX", keys: [:zip, :city]
+      cities = described_class.state_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[: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
+    it "returns the names of the cities" do
+      cities = described_class.state_cities "TX", names_only: true
+      expect(cities.count).to eq(1170)
+
+      expect(cities[0]).to eq("Abbott")
+    end
+  end
+
+  describe "#zip_cities" do
+    it "returns a city for one zip code" do
+      zip_cities = "78748".zip_cities
+      expect(zip_cities.count).to eq(1)
+
+      zip_info = zip_cities[0]
+      expect(zip_info[:city]).to eq("Austin")
+      expect(zip_info[:state]).to eq("TX")
+      expect(zip_info[:zip]).to eq("78701-78799")
+      expect(zip_info[:lat]).to eq(30.315)
+      expect(zip_info[:long]).to eq(-97.71)
+    end
+
+    it "returns multiple cities" do
+      zip_cities = "78702-78750,78613".zip_cities
+      expect(zip_cities.count).to eq(2)
+
+      zip_info = zip_cities[0]
+      expect(zip_info[:city]).to eq("Austin")
+      expect(zip_info[:state]).to eq("TX")
+      expect(zip_info[:zip]).to eq("78701-78799")
+      expect(zip_info[:lat]).to eq(30.315)
+      expect(zip_info[:long]).to eq(-97.71)
+
+      zip_info = zip_cities[1]
+      expect(zip_info[:city]).to eq("Cedar Park")
+      expect(zip_info[:state]).to eq("TX")
+      expect(zip_info[:zip]).to eq("78613")
+      expect(zip_info[:lat]).to eq(30.51)
+      expect(zip_info[:long]).to eq(-97.83)
+    end
+
+    it "breaks on max" do
+      zip_cities = "13601,11223,78748,78613".zip_cities max: 2
+      expect(zip_cities.count).to eq(2)
+    end
+
+    it "returns just names of cities sorted" do
+      zip_cities = "13601,78613,78702-78750".zip_cities names_only: true
+      expect(zip_cities).to eq(["Austin", "Cedar Park", "Watertown"])
+    end
+  end
+
+  describe "#_parse_zip_string" do
+    it "parses the zip_string" do
+      [
+          ["78703, 78701", ["78701", "78703"]],
+          ["78701-78703, 78702", ["78701", "78702", "78703"]],
+      ].each do |t|
+        zips = described_class._parse_zip_string(t[0])
+        expect(zips).to eq(t[1])
+      end
+    end
+
+    it "raises an error for invalid zip code" do
+      expect {
+        described_class._parse_zip_string "100"
+      }.to raise_error(Zipcoder::ZipcoderError)
+    end
   end
 
   describe("String") 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")
+        expect(zip_info[:city]).to eq("Austin")
         expect(zip_info[:state]).to eq("TX")
         expect(zip_info[:zip]).to eq("78748")
         expect(zip_info[:lat]).to eq(30.26)
@@ -130,7 +220,7 @@ describe Zipcoder do
 
       it "only returns specified keys" do
         zip_info = "78748".zip_info keys: [:city, :state]
-        expect(zip_info[:city]).to eq("AUSTIN")
+        expect(zip_info[:city]).to eq("Austin")
         expect(zip_info[:state]).to eq("TX")
         expect(zip_info[:zip]).to be_nil
         expect(zip_info[:lat]).to be_nil
@@ -141,15 +231,15 @@ describe Zipcoder 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")
+        expect(city_info[:city]).to eq("Austin")
         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[:long]).to eq(-97.71)
       end
       it "only returns specified keys" do
         city_info = "Austin, TX".city_info keys: [:zip, :city]
-        expect(city_info[:city]).to eq("AUSTIN")
+        expect(city_info[:city]).to eq("Austin")
         expect(city_info[:state]).to be_nil
         expect(city_info[:zip]).to eq("78701-78799")
         expect(city_info[:lat]).to be_nil
@@ -157,24 +247,24 @@ describe Zipcoder do
       end
     end
 
-    describe "cities" do
+    describe "state_cities" do
       it "returns the cities for a state" do
-        cities = "TX".cities
+        cities = "TX".state_cities
         expect(cities.count).to eq(1170)
 
         city_info = cities[0]
-        expect(city_info[:city]).to eq("ABBOTT")
+        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]
+        cities = "TX".state_cities keys: [:zip, :city]
         expect(cities.count).to eq(1170)
 
         city_info = cities[0]
-        expect(city_info[:city]).to eq("ABBOTT")
+        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
@@ -186,7 +276,7 @@ describe Zipcoder do
   describe("Integer") do
     it "returns the info for a particular zip_code" do
       zip_info = 78748.zip_info
-      expect(zip_info[:city]).to eq("AUSTIN")
+      expect(zip_info[:city]).to eq("Austin")
       expect(zip_info[:state]).to eq("TX")
       expect(zip_info[:zip]).to eq("78748")
       expect(zip_info[:lat]).to eq(30.26)
@@ -195,7 +285,7 @@ describe Zipcoder do
 
     it "zero pads the zip code when using an integer" do
       zip_info = 705.zip_info
-      expect(zip_info[:city]).to eq("AIBONITO")
+      expect(zip_info[:city]).to eq("Aibonito")
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zipcoder
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eric Chapman
@@ -104,6 +104,7 @@ files:
 - lib/ext/integer.rb
 - lib/ext/string.rb
 - lib/zipcoder.rb
+- lib/zipcoder/cacher/base.rb
 - lib/zipcoder/version.rb
 - spec/spec_helper.rb
 - spec/zipcoder_spec.rb