class Geocoder::Lookup::Base

def cache


The working Cache object.
# 
def cache
  Geocoder.cache
end

def cache_key(query)


something else (like the URL before OAuth encoding).
timestamp, etc varies from one request to another, we need to use
request URL, but in cases where OAuth is used and the nonce,
Key to use for caching a geocoding result. Usually this will be the
# 
def cache_key(query)
  query_url(query)
end

def fetch_data(query)


Returns a parsed search result (Ruby hash).
# 
def fetch_data(query)
  parse_raw_data fetch_raw_data(query)
rescue SocketError => err
  raise_error(err) or warn "Geocoding API connection cannot be established."
rescue TimeoutError => err
  raise_error(err) or warn "Geocoding API not responding fast enough " +
    "(see Geocoder::Configuration.timeout to set limit)."
end

def fetch_raw_data(query)


The result might or might not be cached.
Fetch a raw geocoding result (JSON string).
# 
def fetch_raw_data(query)
  key = cache_key(query)
  if cache and body = cache[key]
    @cache_hit = true
  else
    response = make_api_request(query)
    body = response.body
    if cache and (200..399).include?(response.code.to_i)
      cache[key] = body
    end
    @cache_hit = false
  end
  body
end

def hash_to_query(hash)


Removes any keys with nil value.
Simulate ActiveSupport's Object#to_query.
# 
def hash_to_query(hash)
  require 'cgi' unless defined?(CGI) && defined?(CGI.escape)
  hash.collect{ |p|
    p[1].nil? ? nil : p.map{ |i| CGI.escape i.to_s } * '='
  }.compact.sort * '&'
end

def http_client


Object used to make HTTP requests.
# 
def http_client
  protocol = "http#{'s' if Geocoder::Configuration.use_https}"
  proxy_name = "#{protocol}_proxy"
  if proxy = Geocoder::Configuration.send(proxy_name)
    proxy_url = protocol + '://' + proxy
    begin
      uri = URI.parse(proxy_url)
    rescue URI::InvalidURIError
      raise ConfigurationError,
        "Error parsing #{protocol.upcase} proxy URL: '#{proxy_url}'"
    end
    Net::HTTP::Proxy(uri.host, uri.port, uri.user, uri.password)
  else
    Net::HTTP
  end
end

def make_api_request(query)


return the response object.
Make an HTTP(S) request to a geocoding API and
# 
def make_api_request(query)
  timeout(Geocoder::Configuration.timeout) do
    uri = URI.parse(query_url(query))
    client = http_client.new(uri.host, uri.port)
    client.use_ssl = true if Geocoder::Configuration.use_https
    client.get(uri.request_uri, Geocoder::Configuration.http_headers)
  end
end

def map_link_url(coordinates)


also provide maps.
Not necessarily implemented by all subclasses as only some lookups

Return the URL for a map of the given coordinates.
# 
def map_link_url(coordinates)
  nil
end

def parse_raw_data(raw_data)


Parses a raw search result (returns hash or array).
# 
def parse_raw_data(raw_data)
  if defined?(ActiveSupport::JSON)
    ActiveSupport::JSON.decode(raw_data)
  else
    JSON.parse(raw_data)
  end
rescue
  warn "Geocoding API's response was not valid JSON."
end

def protocol


Set in configuration but not available for every service.
Protocol to use for communication with geocoding services.
# 
def protocol
  "http" + (Geocoder::Configuration.use_https ? "s" : "")
end

def query_url(query)


URL to use for querying the geocoding engine.
# 
def query_url(query)
  fail
end

def query_url_params(query) 

def query_url_params(query)
  query.options[:params] || {}
end

def raise_error(error, message = nil)


Return false if exception not raised.
Raise exception if configuration specifies it should be raised.
# 
def raise_error(error, message = nil)
  exceptions = Geocoder::Configuration.always_raise
  if exceptions == :all or exceptions.include?( error.is_a?(Class) ? error : error.class )
    raise error, message
  else
    false
  end
end

def result_class


Class of the result objects
# 
def result_class
  Geocoder::Result.const_get(self.class.to_s.split(":").last)
end

def results(query)


Geocoder::Result object or nil on timeout or other error.
# 
def results(query)
  fail
end

def search(query, options = {})


for reverse geocoding. Returns an array of Geocoder::Results.
"205.128.54.202") for geocoding, or coordinates (latitude, longitude)
Takes a search string (eg: "Mississippi Coast Coliseumf, Biloxi, MS",

Returns +nil+ on timeout or error.
Query the geocoding API and return a Geocoder::Result object.
# 
def search(query, options = {})
  query = Geocoder::Query.new(query, options) unless query.is_a?(Geocoder::Query)
  results(query).map{ |r|
    result = result_class.new(r)
    result.cache_hit = @cache_hit if cache
    result
  }
end

def url_query_string(query) 

def url_query_string(query)
  hash_to_query(
    query_url_params(query).reject{ |key,value| value.nil? }
  )
end