README.md in geocoder-1.3.1 vs README.md in geocoder-1.3.2

- old
+ new

@@ -432,23 +432,10 @@ * **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`) -**Warning - [this API will be discontinued on March 31.](https://developer.yahoo.com/boss/placefinder/)** - -* **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 -* **Region**: world -* **SSL support**: no -* **Languages**: en, fr, de, it, es, pt, nl, zh, ja, ko -* **Documentation**: http://developer.yahoo.com/boss/geo/docs/index.html -* **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 (set `Geocoder.configure(:lookup => :bing, :api_key => key)`) * **Key signup**: https://www.microsoft.com/maps/create-a-bing-maps-key.aspx * **Quota**: 50,0000 requests/day (Windows app), 125,000 requests/year (non-Windows app) @@ -576,10 +563,35 @@ * **Documentation**: http://resources.arcgis.com/en/help/arcgis-online-geocoding-rest-api/ * **Terms of Service**: http://www.esri.com/legal/software-license * **Limitations**: ? * **Notes**: You can specify which projection you want to use by setting, for example: `Geocoder.configure(:esri => {:outSR => 102100})`. +#### Mapzen (`:mapzen`) + +* **About**: Mapzen is the primary author of pelias and offers Pelias-as-a-service in free and paid versions https://mapzen.com/pelias. +* **API key**: required +* **Quota**: 6/sec, up to 30k per day, paid plan info at https://mapzen.com/documentation/search/api-keys-rate-limits/#rate-limits +* **Region**: World +* **SSL support**: yes +* **Languages**: en +* **Documentation**: https://mapzen.com/documentation/search/search/ +* **Terms of Service**: http://mapzen.com/terms +* **Limitations**: See terms + +#### Pelias (`:pelias`) + +* **About**: Pelias is a modular open-source geocoder using ElasticSearch for fast geocoding https://github.com/pelias/pelias. +* **API key**: required +* **Quota**: None, self-hosted service. +* **Region**: World +* **SSL support**: yes +* **Languages**: en +* **Documentation**: https://mapzen.com/documentation/search/search/ +* **Terms of Service**: http://mapzen.com/terms +* **Limitations**: See terms +* **Notes**: Configure your self-hosted pelias with the `endpoint` option: `Geocoder.configure(:lookup => :pelias, :api_key => 'your_api_key', :pelias => {:endpoint => 'self.hosted/pelias'})`. Defaults to `localhost`. + #### Data Science Toolkit (`:dstk`) Data Science Toolkit provides an API whose reponse format is like Google's but which can be set up as a privately hosted service. * **API key**: none @@ -661,11 +673,22 @@ * **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')`. +#### LatLon.io (`:latlon`) +* **API key**: required +* **Quota**: Depends on the user's plan (free and paid plans available) +* **Region**: US +* **SSL support**: yes +* **Languages**: en +* **Documentation**: https://latlon.io/documentation +* **Terms of Service**: ? +* **Limitations**: No restrictions on use + + ### IP Address Services #### FreeGeoIP (`:freegeoip`) * **API key**: none @@ -724,11 +747,32 @@ * **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")`. +#### MaxMind GeoIP2 Precision Web Services (`:maxmind_geoip2`) +* **API key**: required +* **Quota**: Request Packs can be purchased +* **Region**: world +* **SSL support**: yes +* **Languages**: English +* **Documentation**: http://dev.maxmind.com/geoip/geoip2/web-services/ +* **Terms of Service**: ? +* **Limitations**: ? +* **Notes**: You must specify which MaxMind service you are using in your configuration, and also basic authentication. For example: `Geocoder.configure(:maxmind_geoip2 => {:service => :country, :basic_auth => {:user => '', :password => ''}})`. + +#### IPInfo.io (`:ipinfo_io`) + +* **API key**: optional - see http://ipinfo.io/pricing +* **Quota**: 1,000/day - more with api key +* **Region**: world +* **SSL support**: no (not without access key - see http://ipinfo.io/pricing) +* **Languages**: English +* **Documentation**: http://ipinfo.io/developers +* **Terms of Service**: http://ipinfo.io/developers + ### IP Address Local Database Services #### MaxMind Local (`:maxmind_local`) - EXPERIMENTAL 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. @@ -1031,27 +1075,27 @@ Error Handling -------------- By default Geocoder will rescue any exceptions raised by calls to a geocoding service and return an empty array. You can override this on a per-exception basis, and also have Geocoder raise its own exceptions for certain events (eg: API quota exceeded) by using the `:always_raise` option: - Geocoder.configure(:always_raise => [SocketError, TimeoutError]) + Geocoder.configure(:always_raise => [SocketError, Timeout::Error]) You can also do this to raise all exceptions: Geocoder.configure(:always_raise => :all) The raise-able exceptions are: SocketError - TimeoutError + Timeout::Error Geocoder::OverQueryLimitError Geocoder::RequestDenied Geocoder::InvalidRequest Geocoder::InvalidApiKey Geocoder::ServiceUnavailable -Note that only a few of the above exceptions are raised by any given lookup, so there's no guarantee if you configure Geocoder to raise `ServiceUnavailable` that it will actually be raised under those conditions (because most APIs don't return 503 when they should; you may get a `TimeoutError` instead). Please see the source code for your particular lookup for details. +Note that only a few of the above exceptions are raised by any given lookup, so there's no guarantee if you configure Geocoder to raise `ServiceUnavailable` that it will actually be raised under those conditions (because most APIs don't return 503 when they should; you may get a `Timeout::Error` instead). Please see the source code for your particular lookup for details. Troubleshooting --------------- @@ -1068,9 +1112,19 @@ A lot of debugging time can be saved by understanding how Geocoder works with ActiveRecord. When you use the `near` scope or the `nearbys` method of a geocoded object, Geocoder creates an ActiveModel::Relation object which adds some attributes (eg: distance, bearing) to the SELECT clause. It also adds a condition to the WHERE clause to check that distance is within the given radius. Because the SELECT clause is modified, anything else that modifies the SELECT clause may produce strange results, for example: * using the `pluck` method (selects only a single column) * specifying another model through `includes` (selects columns from other tables) + +### Geocoding is Slow + +With most lookups, addresses are translated into coordinates via an API that must be accessed through the Internet. These requests are subject to the same bandwidth constraints as every other HTTP request, and will vary in speed depending on network conditions. Furthermore, many of the services supported by Geocoder are free and thus very popular. Often they cannot keep up with demand and their response times become quite bad. + +If your application requires quick geocoding responses you will probably need to pay for a non-free service, or--if you're doing IP address geocoding--use a lookup that doesn't require an external (network-accessed) service. + +For IP address lookups in Rails applications, it is generally NOT a good idea to run `request.location` during a synchronous page load without understanding the speed/behavior of your configured lookup. If the lookup becomes slow, so will your website. + +For the most part, the speed of geocoding requests has little to do with the Geocoder gem. Please take the time to learn about your configured lookup (links to documentation are provided above) before posting performance-related issues. ### Unexpected Responses from Geocoding Services Take a look at the server's raw response. You can do this by getting the request URL in an app console: