README.md in geocoder-1.2.7 vs README.md in geocoder-1.2.8

- old
+ new

@@ -1,11 +1,13 @@ Geocoder ======== -Geocoder is a complete geocoding solution for Ruby. With Rails it adds geocoding (by street or IP address), reverse geocoding (find street address based on given coordinates), and distance queries. It's as simple as calling `geocode` on your objects, and then using a scope like `Venue.near("Billings, MT")`. +Geocoder is a complete geocoding solution for Ruby. With Rails it adds geocoding (by street or IP address), reverse geocoding (finding street address based on given coordinates), and distance queries. It's as simple as calling `geocode` on your objects, and then using a scope like `Venue.near("Billings, MT")`. +_Please note that this README is for the current `HEAD` and may document features not present in the latest gem release. For this reason, you may want to instead view the README for your particular version._ + Compatibility ------------- * Supports multiple Ruby versions: Ruby 1.9.3, 2.0.x, 2.1.x, JRuby, and Rubinius. * Supports multiple databases: MySQL, PostgreSQL, SQLite, and MongoDB (1.7.0 and higher). @@ -121,17 +123,19 @@ Request Geocoding by IP Address ------------------------------- -Geocoder adds a `location` method to the standard `Rack::Request` object so you can easily look up the location of any HTTP request by IP address. For example, in a Rails controller or a Sinatra app: +Geocoder adds `location` and `safe_location` methods to the standard `Rack::Request` object so you can easily look up the location of any HTTP request by IP address. For example, in a Rails controller or a Sinatra app: # returns Geocoder::Result object result = request.location -Note that this will usually return `nil` in your test and development environments because things like "localhost" and "0.0.0.0" are not an Internet IP addresses. +**The `location` method is vulnerable to trivial IP address spoofing via HTTP headers.** If that's a problem for your application, use `safe_location` instead, but be aware that `safe_location` will *not* try to trace a request's originating IP through proxy headers; you will instead get the location of the last proxy the request passed through, if any (excepting any proxies you have explicitly whitelisted in your Rack config). +Note that these methods will usually return `nil` in your test and development environments because things like "localhost" and "0.0.0.0" are not an Internet IP addresses. + See _Advanced Geocoding_ below for more information about `Geocoder::Result` objects. Location-Aware Database Queries ------------------------------- @@ -210,15 +214,10 @@ You are not stuck with using the `latitude` and `longitude` database column names (with ActiveRecord) or the `coordinates` array (Mongo) for storing coordinates. For example: geocoded_by :address, :latitude => :lat, :longitude => :lon # ActiveRecord geocoded_by :address, :coordinates => :coords # MongoDB -This means you can geocode multiple addresses as well: - - geocoded_by :start_address, latitude: :start_latitude, longitude: :start_longitude - geocoded_by :end_address, latitude: :end_latitude, longitude: :end_longitude - The `address` method can return any string you'd use to search Google Maps. For example, any of the following are acceptable: * "714 Green St, Big Town, MO" * "Eiffel Tower, Paris, FR" * "Paris, TX, US" @@ -302,11 +301,11 @@ * `result.state_code` - string * `result.postal_code` - string * `result.country` - string * `result.country_code` - string -If you're familiar with the results returned by the geocoding service you're using you can access even more data, but you'll need to be familiar with the particular `Geocoder::Result` object you're using and the structure of your geocoding service's responses. (See below for links to geocoding service documentation.) +If you're familiar with the results returned by the geocoding service you're using you can access even more data (call the `#data` method of any Geocoder::Result object to get the full parsed response), but you'll need to be familiar with the particular `Geocoder::Result` object you're using and the structure of your geocoding service's responses. (See below for links to geocoding service documentation.) Geocoding Service ("Lookup") Configuration ------------------------------------------ @@ -651,22 +650,37 @@ * **Languages**: English * **Documentation**: http://www.telize.com/ * **Terms of Service**: ? * **Limitations**: ? -#### MaxMind Web Services (`:maxmind`) +#### MaxMind Legacy Web Services (`:maxmind`) * **API key**: required * **Quota**: Request Packs can be purchased * **Region**: world * **SSL support**: yes * **Languages**: English -* **Documentation**: http://www.maxmind.com/app/web_services +* **Documentation**: http://dev.maxmind.com/geoip/legacy/web-services/ * **Terms of Service**: ? * **Limitations**: ? * **Notes**: You must specify which MaxMind service you are using in your configuration. For example: `Geocoder.configure(:maxmind => {:service => :omni})`. +#### Baidu IP (`:baidu_ip`) + +* **API key**: required +* **Quota**: No quota limits for geocoding +* **Region**: China +* **SSL support**: no +* **Languages**: Chinese (Simplified) +* **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")`. + + +### 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. * **API key**: none (requires the GeoLite City database which can be downloaded from [MaxMind](http://dev.maxmind.com/geoip/legacy/geolite/)) @@ -695,27 +709,15 @@ # 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`) - -* **API key**: required -* **Quota**: No quota limits for geocoding -* **Region**: China -* **SSL support**: no -* **Languages**: Chinese (Simplified) -* **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/)) +* **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/)) * **Quota**: none * **Region**: world * **SSL support**: N/A * **Languages**: English * **Documentation**: http://www.maxmind.com/en/city @@ -975,11 +977,11 @@ Error Handling -------------- -By default Geocoder will rescue any exceptions raised by calls to a geocoding service and return an empty array (using warn() to inform you of the error). 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: +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]) You can also do this to raise all exceptions: @@ -991,12 +993,13 @@ TimeoutError Geocoder::OverQueryLimitError Geocoder::RequestDenied Geocoder::InvalidRequest Geocoder::InvalidApiKey + Geocoder::ServiceUnavailable -Note that not all lookups support all exceptions. +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. Troubleshooting --------------- @@ -1032,11 +1035,11 @@ Reporting Issues ---------------- When reporting an issue, please list the version of Geocoder you are using and any relevant information about your application (Rails version, database type and version, etc). Also avoid vague language like "it doesn't work." Please describe as specifically as you can what behavior your are actually seeing (eg: an error message? a nil return value?). -Please DO NOT use GitHub issues to ask questions about how to use Geocoder. Sites like StackOverflow are a better forum for such discussions. +Please DO NOT use GitHub issues to ask questions about how to use Geocoder. Sites like [StackOverflow](http://www.stackoverflow.com/) are a better forum for such discussions. ### Known Issue You cannot use the `near` scope with another scope that provides an `includes` option because the `SELECT` clause generated by `near` will overwrite it (or vice versa). @@ -1067,6 +1070,6 @@ * Remember: Geocoder needs to run outside of Rails. Don't assume things like ActiveSupport are available. * Be willing to accept criticism and work on improving your code; Geocoder is used by thousands of developers and care must be taken not to introduce bugs. * Be aware that the pull request review process is not immediate, and is generally proportional to the size of the pull request. -Copyright (c) 2009-12 Alex Reisner, released under the MIT license +Copyright (c) 2009-15 Alex Reisner, released under the MIT license