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: ZipcoderError

Constant Summary collapse

VERSION = 
"0.9.0"
@@cacher = 
nil

Class Method Summary collapse

Class Method Details

._cache_key(city_state) ⇒ Object

Returns a cache key


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

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


215
216
217
218
219
220
 
# File 'lib/zipcoder.rb', line 215

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


171
172
173
174
175
176
177
178
179
180
 
# File 'lib/zipcoder.rb', line 171

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


197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/zipcoder.rb', line 197

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 


14
15
16
17
18
19
 
# File 'lib/zipcoder.rb', line 14

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

.city_info(city_state, **kwargs) ⇒ Object

Looks up city information


111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/zipcoder.rb', line 111

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

.load_cache(cacher = nil) ⇒ Object

Loads the data into memory


22
23
24
25
 
# File 'lib/zipcoder.rb', line 22

def self.load_cache(cacher=nil)
  @@cacher = cacher || Cacher::Memory.new
  self.cacher.load
end

.state_cities(state, **kwargs) ⇒ Object

Returns the cities in a state


137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/zipcoder.rb', line 137

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


158
159
160
161
162
163
 
# File 'lib/zipcoder.rb', line 158

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


166
167
168
 
# File 'lib/zipcoder.rb', line 166

def self.states
  self.cacher.read_states
end

.zip_cities(zip_string, **kwargs) ⇒ Object

Returns the cities that contain the zip codes


56
57
58
59
60
61
62
63
64
65
66
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
 
# File 'lib/zipcoder.rb', line 56

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


28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/zipcoder.rb', line 28

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