module Zipcoder

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

Constants

CONFIG
VERSION

Public Class Methods

_cache_key(city_state) click to toggle source

Returns a cache key

# 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) click to toggle source

Check the zip codes

# 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) click to toggle source

Filters arguments in return hash

# 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) click to toggle source

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

# 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() click to toggle source
# File lib/zipcoder.rb, line 25
def self.cacher
  if @@cacher == nil
    self.load_cache
  end
  @@cacher
end
city_info(city_state, **kwargs) click to toggle source

Looks up city information

# 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) click to toggle source
# File lib/zipcoder.rb, line 20
def self.config(&block)
  block.call(CONFIG)
end
load_cache() click to toggle source

Loads the data into memory

# 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) click to toggle source

Returns the cities in a state

# 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) click to toggle source

Returns the counties in a state

# 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() click to toggle source

Returns the states

# File lib/zipcoder.rb, line 177
def self.states
  self.cacher.read_states
end
zip_cities(zip_string, **kwargs) click to toggle source

Returns the cities that contain the zip codes

# 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) click to toggle source

Looks up zip code information

# 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