Module: Zipcoder

Defined in:
lib/zipcoder/cacher/base.rb,
lib/zipcoder.rb,
lib/zipcoder/version.rb,
lib/zipcoder/cacher/redis.rb,
lib/zipcoder/cacher/memory.rb

Overview

The ZipCoder::Cacher::Base class generates different data structures and then stores them for later access based on whichever cacher is selected. For example, they could be stored in memory, Redis, etc.

The generated data structures are as follows

## zipcoder:zip:ZIP

Information for each zip code

- zip: zip code (e.g. "55340")
- city: city name (e.g. "Hamel")
- county: County(s) for the zip code (e.g. ["Travis"])
- state: state (e.g. "MN")
- lat: latitude for the city (e.g. "45.07")
- long: longitude for the city (e.g. "-93.58")

## zipcoder:city:CITY,STATE

Information for each city

- city: city name (e.g. "Anderson")
- county: city county(s) (e.g. ["Travis"])
- state: city state (e.g. "IN")
- zip: list of zip codes for the city (e.g. "46011-46013,46016-46017")
- lat: latitude for the city (e.g. "40.09")
- long: longitude for the city (e.g. "-85.68")

## zipcoder:county:COUNTY,STATE

Information for each county

- county: county name
- cities: cities in the county
- state: county state
- zip: list of zip codes for the county (e.g. "46011-46013,46016-46017")
- lat: latitude for the county (e.g. "40.09")
- long: longitude for the county (e.g. "-85.68")

## zipcoder:state:cities:STATE

List of cities in the state

## zipcoder:state:counties:STATE

List of counties in the state

## zipcoder:states

List of the states in the US

Defined Under Namespace

Modules: Cacher Classes: Config, ZipcoderError

Constant Summary collapse

CONFIG = 
Config.new
VERSION = 
"0.9.2"
@@cacher = 
nil

Class Method Summary collapse

Class Method Details

._cache_key(city_state) ⇒ Object

Returns a cache key



194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/zipcoder.rb', line 194

def self._cache_key(city_state)
  unless city_state.include? ','
    raise ZipcoderError, "city/state must include ','"
  end

  components = city_state.split(',')
  city = components[0].strip.upcase
  state = components[1].strip.upcase

  "#{city},#{state}"
end

._check_zip(zip) ⇒ Object

Check the zip codes



226
227
228
229
230
231
 
# File 'lib/zipcoder.rb', line 226

def self._check_zip(zip)
  unless zip.is_zip?
    raise ZipcoderError, "zip code #{zip} is not 5 characters"
  end
  zip
end

._filter_hash_args(hash, keys) ⇒ Object

Filters arguments in return hash



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/zipcoder.rb', line 182

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

._parse_zip_string(zip_string) ⇒ Object

Parses a zip code string and returns all of the zip codes as an array



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/zipcoder.rb', line 208

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

  zips.sort.uniq
end

.cacher ⇒ Object 



25
26
27
28
29
30
 
# File 'lib/zipcoder.rb', line 25

def self.cacher
  if @@cacher == nil
    self.load_cache
  end
  @@cacher
end

.city_info(city_state, **kwargs) ⇒ Object

Looks up city information



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/zipcoder.rb', line 122

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)

  # Return it
  if cached_value == nil
    nil
  elsif kwargs[:zips_only]
    cached_value[:zip].breakout_zips
  else
    # Clone the object
    cached_value = cached_value.clone

    # If filter specified, create "specified_zip"
    if kwargs[:filter]
      normal_zips = cached_value[:zip].breakout_zips
      filter_zips = kwargs[:filter].breakout_zips
      cached_value[:specified_zip] = (normal_zips & filter_zips).combine_zips
    end

    self._filter_hash_args cached_value, kwargs[:keys]
  end
end

.config(&block) ⇒ Object 



20
21
22
 
# File 'lib/zipcoder.rb', line 20

def self.config(&block)
  block.call(CONFIG)
end

.load_cache ⇒ Object

Loads the data into memory



33
34
35
36
 
# File 'lib/zipcoder.rb', line 33

def self.load_cache
  @@cacher = CONFIG.cacher || Cacher::Memory.new
  self.cacher.load data: CONFIG.data
end

.state_cities(state, **kwargs) ⇒ Object

Returns the cities in a state



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/zipcoder.rb', line 148

def self.state_cities(state, **kwargs)
  state = state.strip.upcase

  names_only = kwargs[:names_only]
  keys = kwargs[:keys]

  # Filter the returned cities
  cities = self.cacher.read_state_cities_cache(state)
  if names_only
    cities
  else
    infos = []
    self.cacher.read_state_cities_cache(state).each { |city|
      infos << self.city_info("#{city}, #{state}", keys: keys)
    }

    infos
  end
end

.state_counties(state, **kwargs) ⇒ Object

Returns the counties in a state



169
170
171
172
173
174
 
# File 'lib/zipcoder.rb', line 169

def self.state_counties(state, **kwargs)
  state = state.strip.upcase

  # Return the counties
  self.cacher.read_state_counties_cache(state)
end

.states ⇒ Object

Returns the states



177
178
179
 
# File 'lib/zipcoder.rb', line 177

def self.states
  self.cacher.read_states
end

.zip_cities(zip_string, **kwargs) ⇒ Object

Returns the cities that contain the zip codes



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/zipcoder.rb', line 67

def self.zip_cities(zip_string, **kwargs)
  max = kwargs[:max]

  cities = {}
  self._parse_zip_string(zip_string).each do |zip|
    info = zip.zip_info
    key = nil
    if info != nil
      key = "#{info[:city]}, #{info[:state]}"
    end

    if key == nil
      next
    end

    zip_codes = cities[key] || []
    zip_codes << zip
    cities[key] = zip_codes

    if max != nil and cities.keys.count >= max
      break
    end
  end


  if kwargs[:grouped]
    zips = {}
    cities.each do |city, zip_codes|
      key = zip_codes.combine_zips
      if kwargs[:names_only]
        zips[key] = city
      else
        zips[key] = city.city_info(keys: kwargs[:keys])
      end
    end
  else
    sorted_cities = cities.keys.uniq.sort
    if kwargs[:names_only]
      zips = sorted_cities
    else
      zips = []
      sorted_cities.each do |city|
        zip_codes = cities[city]
        city_detail = city.city_info(keys: kwargs[:keys])
        if kwargs[:keys] == nil or kwargs[:keys].include? :specified_zip
          city_detail[:specified_zip] = zip_codes.combine_zips
        end
        zips << city_detail
      end
    end
  end
  zips
end

.zip_info(zip = nil, **kwargs) ⇒ Object

Looks up zip code information



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/zipcoder.rb', line 39

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.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.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])
      end
    end

    infos
  end
end