gcoder

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.

Configuration Options

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

:append

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

:region

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

:language

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

:bounds

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.

:client

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

:key

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

:storage

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

:storage_config

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

Storage Adapters

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.

Adapter Configuration

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.

Roll Your Own Adapter

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
  }

Contributors

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