Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Geocodes stuff using Google Geocoding API (V3) and caches the results somewhere, if you want.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 Gemfile
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 gcoder.gemspec
README.md

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

Something went wrong with that request. Please try again.