README.markdown in geokit-1.7.1 vs README.markdown in geokit-1.8.0
- old
+ new
@@ -1,11 +1,11 @@
Geokit
======
[](http://badge.fury.io/rb/geokit)
[](https://travis-ci.org/geokit/geokit)
-[](https://coveralls.io/r/geokit/geokit)
+[](https://coveralls.io/r/geokit/geokit)
[](https://gemnasium.com/geokit/geokit)
[](https://codeclimate.com/github/geokit/geokit)
## DESCRIPTION
@@ -15,29 +15,59 @@
* Geocoding from multiple providers. It supports Google, Yahoo, Geocoder.us, and Geocoder.ca geocoders, and others. It provides a uniform response structure from all of them.
It also provides a fail-over mechanism, in case your input fails to geocode in one service.
* Rectangular bounds calculations: is a point within a given rectangular bounds?
* Heading and midpoint calculations
-Combine this gem with the [geokit-rails plugin](http://github.com/geokit/geokit-rails) to get location-based finders for your Rails app.
+Combine this gem with the [geokit-rails](http://github.com/geokit/geokit-rails) to get location-based finders for your Rails app.
* Repository at Github: [http://github.com/geokit/geokit](http://github.com/geokit/geokit).
* RDoc pages: [http://rdoc.info/github/geokit/geokit/master/frames](http://rdoc.info/github/geokit/geokit/master/frames)
-* Follow the Google Group for updates and discussion on Geokit: [http://groups.google.com/group/geokit](http://groups.google.com/group/geokit)
+## COMMUNICATION
+
+* If you **need help**, use [Stack Overflow](http://stackoverflow.com/questions/tagged/geokit). (Tag 'geokit' and we'll be alerted)
+* If you **found a bug**, use GitHub issues.
+* If you **have an idea**, use GitHub issues.
+* If you'd like to **ask a general question**, use GitHub issues.
+* If you **want to contribute**, submit a pull request.
+
## INSTALL
gem install geokit
+## SUPPORTED GEOCODERS
+
+### "regular" address geocoders
+* Yahoo BOSS - requires an API key.
+* Geocoder.us - may require authentication if performing more than the free request limit.
+* Geocoder.ca - for Canada; may require authentication as well.
+* Geonames - a free geocoder
+* Bing
+* Yandex
+* MapQuest
+
+### address geocoders that also provide reverse geocoding
+* Google - requires an API key. Also supports multiple results and bounding box/country code biasing.
+* FCC
+* Open Street Map
+
+### IP address geocoders
+* IP - geocodes an IP address using hostip.info's web service.
+* Geoplugin.net -- another IP address geocoder
+* RIPE
+* MaxMind
+* freegeoip.net
+
## QUICK START
```ruby
irb> require 'rubygems'
irb> require 'geokit'
- irb> a=Geokit::Geocoders::YahooGeocoder.geocode '140 Market St, San Francisco, CA'
+ irb> a=Geokit::Geocoders::GoogleGeocoder.geocode '140 Market St, San Francisco, CA'
irb> a.ll
=> 37.79363,-122.396116
- irb> b=Geokit::Geocoders::YahooGeocoder.geocode '789 Geary St, San Francisco, CA'
+ irb> b=Geokit::Geocoders::GoogleGeocoder.geocode '789 Geary St, San Francisco, CA'
irb> b.ll
=> 37.786217,-122.41619
irb> a.distance_to(b)
=> 1.21120007413626
irb> a.heading_to(b)
@@ -66,28 +96,27 @@
# This is the timeout value in seconds to be used for calls to the geocoder web
# services. For no timeout at all, comment out the setting. The timeout unit
# is in seconds.
Geokit::Geocoders::request_timeout = 3
- # These settings are used if web service calls must be routed through a proxy.
- # These setting can be nil if not needed, otherwise, addr and port must be
+ # This setting can be used if web service calls must be routed through a proxy.
+ # These setting can be nil if not needed, otherwise, a valid URI must be
# filled in at a minimum. If the proxy requires authentication, the username
# and password can be provided as well.
- Geokit::Geocoders::proxy_addr = nil
- Geokit::Geocoders::proxy_port = nil
- Geokit::Geocoders::proxy_user = nil
- Geokit::Geocoders::proxy_pass = nil
+ Geokit::Geocoders::proxy = 'https://user:password@host:port'
# This is your yahoo application key for the Yahoo Geocoder.
# See http://developer.yahoo.com/faq/index.html#appid
# and http://developer.yahoo.com/maps/rest/V1/geocode.html
Geokit::Geocoders::yahoo = 'REPLACE_WITH_YOUR_YAHOO_KEY'
- # This is your Google Maps geocoder key.
+ # This is your Google Maps geocoder keys (all optional).
# See http://www.google.com/apis/maps/signup.html
# and http://www.google.com/apis/maps/documentation/#Geocoding_Examples
- Geokit::Geocoders::google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
+ Geokit::Geocoders::google_client_id = ''
+ Geokit::Geocoders::google_cryptographic_key = ''
+ Geokit::Geocoders::google_channel = ''
# You can also set multiple API KEYS for different domains that may be directed to this same application.
# The domain from which the current user is being directed will automatically be updated for Geokit via
# the GeocoderControl class, which gets it's begin filter mixed into the ActionController.
# You define these keys with a Hash as follows:
@@ -123,28 +152,10 @@
# The IP provider order. Valid symbols are :ip,:geo_plugin.
# As before, make sure you read up on relevant Terms of Use for each.
# Geokit::Geocoders::ip_provider_order = [:external,:geo_plugin,:ip]
```
-If you're using this gem with the [geokit-rails plugin](http://github.com/geokit/geokit-rails), the plugin
-creates a template with these settings and places it in `config/initializers/geokit_config.rb`.
-
-## SUPPORTED GEOCODERS
-
-### "regular" address geocoders
-* Yahoo Geocoder - requires an API key.
-* Geocoder.us - may require authentication if performing more than the free request limit.
-* Geocoder.ca - for Canada; may require authentication as well.
-* Geonames - a free geocoder
-
-### address geocoders that also provide reverse geocoding
-* Google Geocoder - requires an API key. Also supports multiple results and bounding box/country code biasing.
-
-### IP address geocoders
-* IP Geocoder - geocodes an IP address using hostip.info's web service.
-* Geoplugin.net -- another IP address geocoder
-
### Google Geocoder Tricks
The Google Geocoder sports a number of useful tricks that elevate it a little bit above the rest of the currently supported geocoders. For starters, it returns a `suggested_bounds` property for all your geocoded results, so you can more easily decide where and how to center a map on the places you geocode. Here's a quick example:
```ruby
@@ -221,20 +232,19 @@
mappable.rb contains the Mappable module, which provides basic
distance calculation methods, i.e., calculating the distance
between two points.
-mappable.rb also contains LatLng, GeoLoc, and Bounds.
LatLng 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 (also in mappable.rb) represents an address or location which
+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.
+AND the Mappable module goodness for free.
geocoders.rb contains all the geocoder implemenations. All the gercoders
inherit from a common base (class Geocoder) and implement the private method
do_geocode.
@@ -267,10 +277,5 @@
end
end
end
```
-
-## GOOGLE GROUP
-
-Follow the Google Group for updates and discussion on Geokit: http://groups.google.com/group/geokit
-