ruby script/plugin install svn://svn.geekisp.com/science/geox/trunk

Make sure to put your API keys for your preferred engines in constant value in ./lib/geox_api_keys.rb like this:

MAPQUEST_API_KEY = 'your_key_goes_here..'

You must have the following gems installed to use this tool:

'rubygems' # often available by default
'Hpricot' # Google for install instructions - pretty easy if you don't compile from source code!
'open-uri' # available by default
'cgi' # available by default

Testing
===========
Once you've installed the system into your Rails application, you can run tests of GeoX from the root of your rails application (nice, huh?):

rake geox:test

Usage
==========
Using the GeoX::Geocoder is quite simple. You can look in the ./test/geox_test.rb file for lots of examples. Here are some basic examples:

 require 'geox'
 geocoder = GeoX::Geocoder.new(:geoengine => GeoX::Google) # uses the google engine
 location = {:address => '701 Ocean St', :post_code => '95060'}
 geocode = geocoder.geocode(location)
 puts geocode.inspect # geocode will be a hash containing the geocode data returned from the server

Notes
==========
The main "geocode" function returns an array of object instances descended from "Geox::Geocode" - It can be one of:
* GeoX::City
* GeoX::PostCode
* GeoX::Block
* GeoX::Street

If multiple objects are returned, it means that the backend geocoder could not decide which of them is right. You should have your user pick one of the choices or otherwise disambiguate. Picking the first item in the array is not really a good solution to this dilemma. If no geocode was found at all, an empty array is returned.

Each returned Geocode instance returned will have several attributes:
* address
* city
* state
* county
* country
* latitude
* longitude

You can access these attributes just like any Ruby object:

 puts geocode.city

What values are actually available will depend on the backend geocoding engine you are using.

You can also evaluate your geocode instance to see how specific it is:

puts "Very specific!" if geocode < GeoX::Block

"<" means that the instance being compared is MORE specific geographically (tighter range of error) than the right hand comparision
">" means that the instance is LESS specific

You can also compare two instances:

puts "Street wins!" if GeoX::Street.new < GeoX::Block.new

Note, it's best to use the following syntax to see if your instance is of a particular kind (though "==" works too, but it probably shouldn't)

puts "City level coding" if geocode.kind_of?(GeoX::City)

There is currently no advanced documentation for this plugin.