Yet another geoding library. Initial version geocodes using Google only but I plan to extend it to use Yahoo and possibly Tiger/Line.

Geocode an address using google:

geocode -s google -g abcd1234_SAMPLE_GOOGLE_API_KEY_etc 1600 Amphitheatre Parkway, Mountain View, CA
# => 37.421759,-122.08437

Reverse geocode a lat/lng (with google api key set in configuration file):

geocode -r 37.421759,-122.08437
# => 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA

g = Geocode.new_geocoder :google, {:google_api_key => "abcd1234_SAMPLE_GOOGLE_API_KEY_etc"}
result1 = g.geocode "1600 Amphitheatre Parkway, Mountain View, CA"
result2 = g.reverse_geocode "37.421759,-122.08437"

result1 and result2 are hashes with the following extension functions added in:

result.success? # true if the geocode/reverse_geocode succeeded.
result.error? # opposite of success.
result.latlng # array of 2 floats, [latitude, longitude], returned by geocode.
result.address # string containing the address returned by reverse_geocode.

Get the most up to date help.

Which service to use. Can be configured in geocode.yml. Currently only google is supported.

Your google API key. Can be configured in geocode.yml.

Displays the lat/lng of the given address.

Default information to display, on by default if no other display mode is selected.

Displays the map viewport extends (bounding box) of the given address.

Displays the geocoding accuracy.

Reverse geocodes a lat/lng to an address. Not compatible with –latlng, –viewport or –accuracy; if any of those options are also set they will be disabled.

Note: If you input a negative latitude from the command line, Trollop tries to interpret this as an argument to the program. You should move to the Northern Hemisphere. As a temporary workaround, however, you can use ‘–’ to tell Trollop to stop processing arguments, e.g.

$ geocode -r -- -23.548943,-46.638818
Address: Av. Vinte e Três de Maio, 149-165 - República, São Paulo - SP, 01316-060, Brazil

Geocodes (or reverse geocodes) the address and then dumps the returned object. Use this to noodle around in the geocode result object for other data.

Turns off label printing. Useful when geocode is part of an external toolchain, e.g.

$ echo The President lives at $(geocode -q 1600 Pennsylvania Ave, Charleston, WV 25302)

For example, I produced that full address with:

$ geocode -r $(geocode -q 1600 Pennsylvania Ave)

gem install geocode

Ideally, then create ~/.geocode and in it, write a geocode.yml file containing your google API key. See Configuration below for details.

You can create a configuration file in ~/.geocode called geocode.yml. It’s a handy place to put your Google API key, for example. You can also place geocode.yml in the current directory if you don’t want to place it in your home folder. A sample file would look like:

---
service: google
google_api_key: abcd1234_SAMPLE_GOOGLE_API_KEY_etc

The Google geocoding service uses the Google Map API and thus you are bound by their Terms of Service. Most notably, this says that you MAY NOT “use or display the Content without a corresponding Google map”. There are specific exceptions to this rule but be aware.

• David Brady <github@shinybit.com>

MIT. See MIT-LICENSE file for details.

Google STRONGLY recommends caching geocoded data. For now, caching is the responsibility of the client using the geocode library. Eventually I’d like to just include a caching strategy and/or caching object to Geocode.new_geocoder(). This hides the caching strategy from the geocoding client.

Possible implementations might include defining internal strategies (give me a sqlite3 file, or an ActiveRecord connection, or the address of a memcached server, etc) or creating a cache object API and passing that in.

UPDATE: As a command-line introspection/visualizing tool, caching is pretty much useless. I’m burying this for now until and unless somebody decides they want to use this as part of a toolchain or as a library.

It is not unreasonable to expect a new geocode user to do this:

$ sudo gem install geocode
$ geocode 123 Some Address

This will fail because there’s no Google API configured. It would be nice to throw up an error message telling the user to create the geocode.yml file. Optionally it should even offer to create ~/.geocode and write the file there with a default API key.

Remember the user from the step above? So he runs it and it creates the default settings file with a sample API key. So he runs it again without editing the file. The app should make it clear that the sample API key needs to be edited. Or at the very least it should report whatever error Google returns when an invalid API key is used.

As I use geocode as a debugging and introspection tool, I keep wanting to jump to a map to visualize the results. Consider emitting the uri to a map using the Google static map API.