README.md in geocoder-1.2.5 vs README.md in geocoder-1.2.6
- old
+ new
@@ -382,11 +382,11 @@
The following is a comparison of the supported geocoding APIs. The "Limitations" listed for each are a very brief and incomplete summary of some special limitations beyond basic data source attribution. Please read the official Terms of Service for a service before using it.
#### Google (`:google`, `:google_premier`)
-* **API key**: required for Premier (do NOT use a key for the free version)
+* **API key**: required for Premier, optional for the free service (if using the free service with API key, https is required. Add `:use_https => true` to `Geocoder.configure`)
* **Key signup**: https://developers.google.com/maps/documentation/business/
* **Quota**: 2,500 requests/day, 100,000 with Google Maps API Premier
* **Region**: world
* **SSL support**: yes
* **Languages**: ar, eu, bg, bn, ca, cs, da, de, el, en, en-AU, en-GB, es, eu, fa, fi, fil, fr, gl, gu, hi, hr, hu, id, it, iw, ja, kn, ko, lt, lv, ml, mr, nl, no, pl, pt, pt-BR, pt-PT, ro, ru, sk, sl, sr, sv, tl, ta, te, th, tr, uk, vi, zh-CN, zh-TW (see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1)
@@ -394,10 +394,24 @@
* **Documentation**: http://code.google.com/apis/maps/documentation/geocoding/#JSON
* **Terms of Service**: http://code.google.com/apis/maps/terms.html#section_10_12
* **Limitations**: "You must not use or display the Content without a corresponding Google map, unless you are explicitly permitted to do so in the Maps APIs Documentation, or through written permission from Google." "You must not pre-fetch, cache, or store any Content, except that you may store: (i) limited amounts of Content for the purpose of improving the performance of your Maps API Implementation..."
* **Notes**: To use Google Premier set `Geocoder.configure(:lookup => :google_premier, :api_key => [key, client, channel])`.
+#### Google Places Details (`:google_places_details`)
+
+The [Google Places Details API](https://developers.google.com/places/documentation/details) is not, strictly speaking, a geocoding service. It accepts a Google `place_id` and returns address information, ratings and reviews. A `place_id` can be obtained from the Google Places Autocomplete API and should be passed to Geocoder as the first search argument: `Geocoder.search("ChIJhRwB-yFawokR5Phil-QQ3zM", :lookup => :google_places_details)`.
+
+* **API key**: required
+* **Key signup**: https://code.google.com/apis/console/
+* **Quota**: 1,000 request/day, 100,000 after credit card authentication
+* **Region**: world
+* **SSL support**: yes
+* **Languages**: ar, eu, bg, bn, ca, cs, da, de, el, en, en-AU, en-GB, es, eu, fa, fi, fil, fr, gl, gu, hi, hr, hu, id, it, iw, ja, kn, ko, lt, lv, ml, mr, nl, no, pl, pt, pt-BR, pt-PT, ro, ru, sk, sl, sr, sv, tl, ta, te, th, tr, uk, vi, zh-CN, zh-TW (see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1)
+* **Documentation**: https://developers.google.com/places/documentation/details
+* **Terms of Service**: https://developers.google.com/places/policies
+* **Limitations**: "If your application displays Places API data on a page or view that does not also display a Google Map, you must show a "Powered by Google" logo with that data."
+
#### Yahoo BOSS (`:yahoo`)
* **API key**: requires OAuth consumer key and secret (set `Geocoder.configure(:api_key => [key, secret])`)
* **Key signup**: http://developer.yahoo.com/boss/geo/
* **Quota**: unlimited, but subject to usage fees
@@ -408,11 +422,11 @@
* **Terms of Service**: http://info.yahoo.com/legal/us/yahoo/boss/tou/?pir=ucJPcJ1ibUn.h.d.lVmlcbcEkoHjwJ_PvxG9SLK9VIbIQAw1XFrnDqY-
* **Limitations**: No mass downloads, no commercial map production based on the data, no storage of data except for caching.
#### Bing (`:bing`)
-* **API key**: required
+* **API key**: required (set `Geocoder.configure(:lookup => :bing, :api_key => key)`)
* **Key signup**: http://www.bingmapsportal.com
* **Quota**: 50,000 requests/24 hrs
* **Region**: world
* **SSL support**: no
* **Languages**: ?
@@ -563,19 +577,47 @@
* **Terms of Service**: http://geocod.io/terms-of-use
* **Limitations**: ?
#### SmartyStreets (`:smarty_streets`)
-* **API key**: required
+* **API key**: requires auth_id and auth_token (set `Geocoder.configure(:api_key => [id, token])`)
* **Quota**: 10,000 free, 250/month then purchase at sliding scale.
* **Region**: US
* **SSL support**: yes
* **Languages**: en
* **Documentation**: http://smartystreets.com/kb/liveaddress-api/rest-endpoint
* **Terms of Service**: http://smartystreets.com/legal/terms-of-service
* **Limitations**: No reverse geocoding.
+
+#### OKF Geocoder (`:okf`)
+
+* **API key**: none
+* **Quota**: none
+* **Region**: FI
+* **SSL support**: no
+* **Languages**: fi
+* **Documentation**: http://books.okf.fi/geocoder/_full/
+* **Terms of Service**: http://www.itella.fi/liitteet/palvelutjatuotteet/yhteystietopalvelut/Postinumeropalvelut-Palvelukuvausjakayttoehdot.pdf
+* **Limitations**: ?
+
+
+#### PostcodeAnywhere Uk (`:postcode_anywhere_uk`)
+
+This uses the PostcodeAnywhere UK Geocode service, this will geocode any string from UK postcode, placename, point of interest or location.
+
+* **API key**: required
+* **Quota**: Dependant on service plan?
+* **Region**: UK
+* **SSL support**: yes
+* **Languages**: English
+* **Documentation**: [http://www.postcodeanywhere.co.uk/Support/WebService/Geocoding/UK/Geocode/2/](http://www.postcodeanywhere.co.uk/Support/WebService/Geocoding/UK/Geocode/2/)
+* **Terms of Service**: ?
+* **Limitations**: ?
+* **Notes**: To use PostcodeAnywhere you must include an API key: `Geocoder.configure(:lookup => :postcode_anywhere_uk, :api_key => 'your_api_key')`.
+
+
### IP Address Services
#### FreeGeoIP (`:freegeoip`)
* **API key**: none
@@ -645,16 +687,15 @@
Geocoder.configure(ip_lookup: :maxmind_local, maxmind_local: {package: :city})
You can generate ActiveRecord migrations and download and import data via provided rake tasks:
+ # generate migration to create tables
rails generate geocoder:maxmind:geolite PACKAGE=city
- rake geocoder:maxmind:geolite:download PACKAGE=city
- rake geocoder:maxmind:geolite:extract PACKAGE=city
- rake geocoder:maxmind:geolite:insert PACKAGE=city
- rake geocoder:maxmind:geolite:load PACKAGE=city # runs the above three in sequence
+ # download, unpack, and import data
+ rake geocoder:maxmind:geolite:load PACKAGE=city
You can replace `city` with `country` in any of the above tasks, generators, and configurations.
#### Baidu IP (`:baidu_ip`)
@@ -666,11 +707,41 @@
* **Documentation**: http://developer.baidu.com/map/webservice-geocoding.htm
* **Terms of Service**: http://developer.baidu.com/map/law.htm
* **Limitations**: Only good for non-commercial use. For commercial usage please check http://developer.baidu.com/map/question.htm#qa0013
* **Notes**: To use Baidu set `Geocoder.configure(:lookup => :baidu_ip, :api_key => "your_api_key")`.
+#### GeoLite2 (`:geoip2`)
+This lookup provides methods for geocoding IP addresses without making a call to a remote API (improves speed and availability). It works, but support is new and should not be considered production-ready. Please [report any bugs](https://github.com/alexreisner/geocoder/issues) you encounter.
+
+* **API key**: none (requires a GeoIP2 or free GeoLite2 City or Country binary database which can be downloaded from [MaxMind](http://dev.maxmind.com/geoip/geoip2/geoip2/))
+* **Quota**: none
+* **Region**: world
+* **SSL support**: N/A
+* **Languages**: English
+* **Documentation**: http://www.maxmind.com/en/city
+* **Terms of Service**: ?
+* **Limitations**: ?
+* **Notes**: **You must download a binary database file from MaxMind and set the `:file` configuration option.** The CSV format databases are not yet supported since they are still in alpha stage. Set the path to the database file in your configuration:
+
+ Geocoder.configure(
+ ip_lookup: :geoip2,
+ geoip2: {
+ file: File.join('folder', 'GeoLite2-City.mmdb')
+ }
+ )
+
+You must add either the *[hive_geoip2](https://rubygems.org/gems/hive_geoip2)* gem (native extension that relies on libmaxminddb) or the *[maxminddb](http://rubygems.org/gems/maxminddb)* gem (pure Ruby implementation) to your Gemfile or have it installed in your system. The pure Ruby gem (maxminddb) will be used by default. To use `hive_geoip2`:
+
+ Geocoder.configure(
+ ip_lookup: :geoip2,
+ geoip2: {
+ lib: 'hive_geoip2',
+ file: File.join('folder', 'GeoLite2-City.mmdb')
+ }
+ )
+
Caching
-------
It's a good idea, when relying on any external service, to cache retrieved data. When implemented correctly it improves your app's response time and stability. It's easy to cache geocoding results with Geocoder, just configure a cache store:
@@ -945,14 +1016,18 @@
* using the `pluck` method (selects only a single column)
* specifying another model through `includes` (selects columns from other tables)
### Unexpected Responses from Geocoding Services
-Take a look at the server's raw JSON response. You can do this by getting the request URL in an app console:
+Take a look at the server's raw response. You can do this by getting the request URL in an app console:
Geocoder::Lookup.get(:google).query_url(Geocoder::Query.new("..."))
Replace `:google` with the lookup you are using and replace `...` with the address you are trying to geocode. Then visit the returned URL in your web browser. Often the API will return an error message that helps you resolve the problem. If, after reading the raw response, you believe there is a problem with Geocoder, please post an issue and include both the URL and raw response body.
+
+You can also fetch the response in the console:
+
+ Geocoder::Lookup.get(:google).send(:fetch_raw_data, Geocoder::Query.new("..."))
Reporting Issues
----------------