The optional parameters are units, formula, and distance_field_name.
Values for units can be :miles, :kms (kilometers), or :nms (nautical miles),
with :miles as the default.
Values for formula can be :sphere or :flat with :sphere as the default.
:sphere gives you Haversine calculations, while :flat gives the Pythagoreum Theory.
These defaults persist through out the gem.

The plug-in creates a calculated distance field on AR instances that have
been retrieved throw a Geokit location query. By default, these fields are
known as "distance" but this can be changed through the :distance_field_name key.

You can also define alternative column names for latitude and longitude using
the :lat_column_name and :lng_column_name keys. The defaults are lat and
lng respectively.

NEW SCOPES TO USE

Once you've specified acts_as_mappable, a few scopes are available :

within and beyond find records within or beyond a certain distance from the origin point.

in_range finds records within a certain distance range from the origin point.

in_bounds finds redords within a rectangle on the map

closest and farthest find the closest or farthest record from the origin point

All these scopes are the porcelain for a lower level scope named geo_scope that take a hash of options.
Their first parameter is simply one of the possible options, without the name

When using a point of reference or bounds, you leverage the power of Geokit
to build this objects. Basicaly, if Geokit can make a Geokit::Point
or a Geokit::Bounds with what you give to it, you're good to go.

FIND BY SQL

Finaly, if all that is desired is the raw SQL for distance
calculations, you can use the following:

FINDING WITHIN A BOUNDING BOX

If you are displaying points on a map, you probably need to query for whatever falls within the rectangular bounds of the map:

Store.in_bounds([sw_point,ne_point]).all

The input to bounds can be array with the two points or a Bounds object. However you provide them, the order should always be the southwest corner, northeast corner of the rectangle. Typically, you will be getting the sw_point and ne_point from a map that is displayed on a web page.

If you need to calculate the bounding box from a point and radius, you can do that:

USING :through

You can also specify a model as mappable "through" another associated model.
In other words, that associated model is the actual mappable model with
"lat" and "lng" attributes, but this "through" model can still utilize
all of the above find methods to search for records.

Remember that the notes above about USING INCLUDES apply to the results from
this find, since an include is automatically used.

IP GEOCODING

You can obtain the location for an IP at any time using the geocoder
as in the following example:

location = IpGeocoder.geocode('12.215.42.19')

where Location is a GeoLoc instance containing the latitude,
longitude, city, state, and country code. Also, the success
value is true.

If the IP cannot be geocoded, a GeoLoc instance is returned with a
success value of false.

It should be noted that the IP address needs to be visible to the
Rails application. In other words, you need to ensure that the
requesting IP address is forwarded by any front-end servers that
are out in front of the Rails app. Otherwise, the IP will always
be that of the front-end server.

The Multi-Geocoder will also geocode IP addresses and provide
failover among multiple IP geocoders. Just pass in an IP address for the
parameter instead of a street address. Eg:

location = Geocoders::MultiGeocoder.geocode('12.215.42.19')

The MultiGeocoder class requires 2 configuration setting for the provider order.
Ordering is done through Geokit::Geocoders::provider_order and
Geokit::Geocoders::ip_provider_order, found in
config/initializers/geokit_config.rb. If you don't already have a
geokit_config.rb file, the plugin creates one when it is first installed.

IP GEOCODING HELPER

A class method called geocode_ip_address has been mixed into the
ActionController::Base. This enables before_filter style lookup of
the IP address. Since it is a filter, it can accept any of the
available filter options.

A first-time lookup will result in the GeoLoc class being stored
in the session as :geo_location as well as in a cookie called
:geo_session. Subsequent lookups will use the session value if it
exists or the cookie value if it doesn't exist. The last resort is
to make a call to the web service. Clients are free to manage the
cookie as they wish.

The intent of this feature is to be able to provide a good guess as
to a new visitor's location.

INTEGRATED FIND AND GEOCODING

Geocoding has been integrated with the finders enabling you to pass
a physical address or an IP address. This would look the following:

where the IP or physical address would be geocoded to a location and
then the resulting latitude and longitude coordinates would be used
in the find. This is not expected to be common usage, but it can be
done nevertheless.

ADDRESS GEOCODING

Geocoding is provided by the Geokit gem, which is required for this plugin.
See the top of this file for instructions on installing the Geokit gem.

Geokit can geocode addresses using multiple geocodeing web services.
Geokit supports services like Google, Yahoo, and Geocoder.us, and more --
see the Geokit gem API for a complete list.

These geocoder services are made available through the following classes:
GoogleGeocoder, YahooGeocoder, UsGeocoder, CaGeocoder, and GeonamesGeocoder.
Further, an additional geocoder class called MultiGeocoder incorporates an ordered failover
sequence to increase the probability of successful geocoding.

All classes are called using the following signature:

include Geokit::Geocoders
location = XxxGeocoder.geocode(address)

where you replace Xxx Geocoder with the appropriate class. A GeoLoc
instance is the result of the call. This class has a "success"
attribute which will be true if a successful geocoding occurred.
If successful, the lat and lng properties will be populated.

Geocoders are named with the convention NameGeocoder. This
naming convention enables Geocoder to auto-detect its sub-classes
in order to create methods called name_geocoder(address) so that
all geocoders can be called through the base class. This is done
purely for convenience; the individual geocoder classes are expected
to be used independently.

The MultiGeocoder class requires the configuration of a provider
order which dictates what order to use the various geocoders. Ordering
is done through Geokit::Geocoders::provider_order, found in
config/initializers/geokit_config.rb.

If you don't already have a geokit_config.rb file, the plugin creates one
when it is first installed.

Make sure your failover configuration matches the usage characteristics
of your application -- for example, if you routinely get bogus input to
geocode, your code will be much slower if you have to failover among
multiple geocoders before determining that the input was in fact bogus.

The address will usually appear as a range, as it does in the above example.

INTEGRATED FIND WITH ADDRESS GEOCODING

Just has you can pass an IP address directly into an ActiveRecord finder
as the origin, you can also pass a physical address as the origin:

Location.find_closest(:origin => '100 Spear st, San Francisco, CA')

where the physical address would be geocoded to a location and then the
resulting latitude and longitude coordinates would be used in the
find.

Note that if the address fails to geocode, the find method will raise an
ActiveRecord::GeocodeError you must be prepared to catch. Alternatively,
You can geocoder the address beforehand, and pass the resulting lat/lng
into the finder if successful.

Auto Geocoding

If your geocoding needs are simple, you can tell your model to automatically
geocode itself on create:

If you need any more complicated geocoding behavior for your model, you should roll your own
before_validate callback.

Distances, headings, endpoints, and midpoints

distance = home.distance_from(work, :units=>:miles)
heading = home.heading_to(work) # result is in degrees, 0 is north
endpoint = home.endpoint(90,2) # two miles due east
midpoing = home.midpoint_to(work)

How to geocode an address

also in geokit_config.rb, make sure that Geokit::Geocoders::provider_order reflects the
geocoder(s). If you only want to use one geocoder, there should
be only one symbol in the array. For example:

Geokit::Geocoders::provider_order=[:google]

Test it out in script/console

include Geokit::Geocoders
res = MultiGeocoder.geocode('100 Spear St, San Francisco, CA')
puts res.lat
puts res.lng
puts res.full_address
... etc. The return type is GeoLoc, see the API for
all the methods you can call on it.

How to find all stores within 10 miles of a given address

as above, ensure your table has the lat/lng columns, and you've
applied acts_as_mappable to the Store model.

Obviously, each of the items in the array must have a latitude/longitude so
they can be sorted by distance.

Database indexes

MySQL can't create indexes on a calculated field such as those Geokit uses to
calculate distance based on latitude/longitude values for a record. However,
indexing the lat and lng columns does improve Geokit distance calculation
performance since the lat and lng columns are used in a straight comparison
for distance calculation. Assuming a Page model that is incorporating the
Geokit plugin the migration would be as follows.

The Geokit gem provides the building blocks of distance-based operations:

The Mappable module, which provides basic
distance calculation methods, i.e., calculating the distance
between two points.

The LatLng class is a simple container for latitude and longitude, but
it's made more powerful by mixing in the above-mentioned Mappable
module -- therefore, you can calculate easily the distance between two
LatLng ojbects with distance = first.distance_to(other)

GeoLoc represents an address or location which
has been geocoded. You can get the city, zipcode, street address, etc.
from a GeoLoc object. GeoLoc extends LatLng, so you also get lat/lng
AND the Mappable modeule goodness for free.

GOOGLE GROUP

IMPORTANT POST-INSTALLATION NOTES:

1. The configuration file: Geokit for Rails uses a configuration file in config/initializers.
You must add your own keys for the various geocoding services if you want to use geocoding.
If you need to refer to the original template again, see the assets/api_keys_template file.

2. The gem dependency: Geokit for Rails depends on the Geokit gem. Tell Rails about this
dependency in config/environment.rb, within the initializer block:
config.gem "geokit"

If you're having trouble with dependencies ....

Try installing the gem manually (sudo gem install geokit), then adding a require 'geokit' to the top of
vendor/plugins/geokit-rails3/init.rb and/or config/geokit_config.rb.