GCoder

GCoder geocodes stuff using the Google Geocoding API (V3) and caches the results somewhere, if you want. (Need something more bulldozer-like? Check out Geokit.)

# Bon Usage

require 'gcoder'

G = GCoder.connect(:storage => :heap)

G['dundas and sorauren', :region => :ca] # ... it geocodes!
G[[41.87, -74.16]]                       # ... and reverse-geocodes!

The returned value is the 'results' portion of the Google Geocoding API response.

These can be applied globally by setting GCoder.config or on a per-connection basis by passing them to GCoder.connect.

Specifies a string to append to the end of all queries.

Tells the Geocoder to favour results in a specific region. More info here.

By default this is whatever Google thinks it is, you can set it to something if you'd like. More info here.

Specifies a bounding box in which to favour results from. Described as an array of two latitude / longitude pairs. The first describes the Northeast corner of the box and the second describes the Southwest corner of the box. Here is an example input:

[[50.09, -94.88], [41.87, -74.16]]

More info here.

To access the special features of Google Maps API Premier, you must provide a client ID. All client IDs begin with a gme- prefix.

To access the special features of Google Maps API Premier, you must provide a signing key in addition to the client ID.

Defines the storage adapter to use for caching results from the geocoder to limit unnecessary throughput. See "Storage Adapters" below for more information.

Passed on to the selected adapter as configuration options. See "Storage Adapters" below for more information.

GCoder comes with two adapters: :heap, and :redis. You can check out lib/gcoder/storage.rb for examples of how these are implemented. You can select either of these, or pass nil (or false) as the :storage option to disable caching of results.

• :storage => nil - Disable caching (default.)
• :storage => :heap - Saves cached values in an in-memory Hash.
• :storage => :redis - Saves cached values within Redis.
• :storage => :rails_cache - Saves cached values via Rails's cache interface.

Some adapters have configuration settings that can be passed. The contents of :storage_config are passed to the adapter when it is instantiated.

HeapAdapter (:heap)

The Heap adapter has no options.

RedisAdapter (:redis)

The Redis adapter has the following options, none are required.

• :connection - Passed to Redis.connect.
• :keyspace - Prefixed to all keys generated by GCoder.
• :key_ttl - A time-to-live in seconds before cached results expire.

Making your own adapter is pretty easy. Your adapter needs to respond to four instance methods: connect, set, get, and clear. Let's make an adapter for Sequel.

class SequelAdapter < GCoder::Storage::Adapter
  def connect
    @db = Sequel.connect(config[:connection])
    @table_name = (config[:table_name] || :gcoder_results)
  end

  # The methods `nkey` and `nval` are used to "normalize" keys and values,
  # respectively. You are encouraged to use them.
  def set(key, value)
    if get(key)
      table.filter(:id => nkey(key)).update(:value => nval(value))
    else
      table.insert(:id => nkey(key), :value => nval(value))
    end
  end

  def get(key)
    if (row = table.filter(:id => nkey(key)).first)
      row[:value]
    else
      nil
    end
  end

  def clear
    table.delete_all
  end

  private

  def table
    @db[@table_name]
  end
end

GCoder::Storage.register(:sequel, SequelAdapter)

Now we can use our adapter as a caching layer by specifying it like this:

G = GCoder.connect \
  :storage => :sequel,
  :storage_config => {
    :connection => 'sqlite://geo.db',
    :table_name => :locations
  }

• Carsten Nielsen
• Christos Pappas - Added support for Google Maps API Premier and Rails.cache adapter.
• GUI - Ruby 1.8.7 compatibility, URI encoding fixes.