README.md in geocoder-1.1.9 vs README.md in geocoder-1.2.0

- old
+ new

@@ -5,16 +5,22 @@ Compatibility ------------- -* Supports multiple Ruby versions: Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0, and JRuby. +* Supports multiple Ruby versions: Ruby 1.9.2, 1.9.3, 2.0.0, 2.1.0, JRuby and Rubinius. * Supports multiple databases: MySQL, PostgreSQL, SQLite, and MongoDB (1.7.0 and higher). * Supports Rails 3 and 4. If you need to use it with Rails 2 please see the `rails2` branch (no longer maintained, limited feature set). * Works very well outside of Rails, you just need to install either the `json` (for MRI) or `json_pure` (for JRuby) gem. +Rails 4.1 Note +-------------- + +Due to [a change in ActiveRecord's `count` method](https://github.com/rails/rails/pull/10710) you will need to use `count(:all)` to explicitly count all columns ("*") when using a `near` scope. Using `near` and calling `count` with no argument will cause exceptions in many cases. + + Installation ------------ Install Geocoder like any other Ruby gem: @@ -96,15 +102,26 @@ If you have just added geocoding to an existing application with a lot of objects you can use this Rake task to geocode them all: rake geocode:all CLASS=YourModel -Geocoder will print warnings if you exceed the rate limit for your geocoding service. Some services — Google notably — enforce a per-second limit in addition to a per-day limit. To avoid exceeding the per-second limit, you can add a `sleep` option to the rake task, like so: +Geocoder will print warnings if you exceed the rate limit for your geocoding service. Some services — Google notably — enforce a per-second limit in addition to a per-day limit. To avoid exceeding the per-second limit, you can add a `SLEEP` option to pause between requests for a given amount of time. You can also load objects in batches to save memory, for example: - rake geocode:all CLASS=YourModel sleep=0.25 + rake geocode:all CLASS=YourModel SLEEP=0.25 BATCH=100 +### Avoiding Unnecessary API Requests +Geocoding only needs to be performed under certain conditions. To avoid unnecessary work (and quota usage) you will probably want to geocode an object only when: + +* an address is present +* the address has been changed since last save (or it has never been saved) + +The exact code will vary depending on the method you use for your geocodable string, but it would be something like this: + + after_validation :geocode, if: ->(obj){ obj.address.present? and obj.address_changed? } + + 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: @@ -193,10 +210,15 @@ 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" @@ -212,11 +234,29 @@ For reverse geocoding you can also specify an alternate name attribute where the address will be stored, for example: reverse_geocoded_by :latitude, :longitude, :address => :location # ActiveRecord reverse_geocoded_by :coordinates, :address => :loc # MongoDB +You can also configure a specific lookup for your model which will override the globally-configured lookup, for example: + geocoded_by :address, :lookup => :yandex + +You can also specify a proc if you want to choose a lookup based on a specific property of an object, for example you can use specialized lookups for different regions: + + geocoded_by :address, :lookup => lambda{ |obj| obj.geocoder_lookup } + + def geocoder_lookup + if country_code == "RU" + :yandex + elsif country_code == "CN" + :baidu + else + :google + end + end + + Advanced Querying ----------------- When querying for objects (if you're using ActiveRecord) you can also look within a square rather than a radius (circle) by using the `within_bounding_box` scope: @@ -225,11 +265,16 @@ box = Geocoder::Calculations.bounding_box(center_point, distance) Venue.within_bounding_box(box) This can also dramatically improve query performance, especially when used in conjunction with indexes on the latitude/longitude columns. Note, however, that returned results do not include `distance` and `bearing` attributes. Note that `#near` performs both bounding box and radius queries for speed. +You can also specify a minimum radius (if you're using ActiveRecord and not Sqlite) to constrain the +lower bound (ie. think of a donut, or ring) by using the `:min_radius` option: + box = Geocoder::Calculations.bounding_box(center_point, distance, :min_radius => 10.5) + + Advanced Geocoding ------------------ So far we have looked at shortcuts for assigning geocoding results to object attributes. However, if you need to do something fancy you can skip the auto-assignment by providing a block (takes the object to be geocoded and an array of `Geocoder::Result` objects) in which you handle the parsed geocoding result any way you like, for example: @@ -256,21 +301,24 @@ * `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.) -Geocoding Services ------------------- +Geocoding Service ("Lookup") Configuration +------------------------------------------ -By default Geocoder uses Google's geocoding API to fetch coordinates and street addresses (FreeGeoIP is the default for IP address info). However there are several other APIs supported, as well as a variety of settings. Please see the listing and comparison below for details on specific geocoding services (not all settings are supported by all services). Some common configuration options are: +Geocoder supports a variety of street and IP address geocoding services. The default lookups are `:google` for street addresses and `:freegeoip` for IP addresses. Please see the listing and comparison below for details on specific geocoding services (not all settings are supported by all services). Some common configuration options are: # config/initializers/geocoder.rb Geocoder.configure( # geocoding service (see below for supported options): :lookup => :yandex, + # IP address geocoding service (see below for supported options): + :ip_lookup => :maxmind, + # to use an API key: :api_key => "...", # geocoding service request timeout, in seconds (default 3): :timeout => 5, @@ -292,13 +340,38 @@ Please see the [source code for each lookup](https://github.com/alexreisner/geocoder/tree/master/lib/geocoder/lookups) to learn about directly supported parameters. Parameters which are not directly supported can be specified using the `:params` option, by which you can pass arbitrary parameters to any geocoding service. For example, to use Nominatim's `countrycodes` parameter: # with Nominatim: Geocoder.search("Paris", :params => {:countrycodes => "gb,de,fr,es,us"}) +You can also configure multiple geocoding services at once, like this: -### Listing and Comparison + Geocoder.configure( + :timeout => 2, + :cache => Redis.new, + + :yandex => { + :api_key => "...", + :timeout => 5 + }, + + :baidu => { + :api_key => "..." + }, + + :maxmind => { + :api_key => "...", + :service => :omni + } + + ) + +The above combines global and service-specific options and could be useful if you specify different geocoding services for different models or under different conditions. Lookup-specific settings override global settings so, for example, in the above the timeout for all lookups would be 2 seconds, except for Yandex which would be 5. + + +### Street Address Services + 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) @@ -409,19 +482,30 @@ * **Languages**: English * **Documentation**: http://api.maps.ovi.com/devguide/overview.html * **Terms of Service**: http://www.developer.nokia.com/Develop/Maps/TC.html * **Limitations**: ? +#### Here/Nokia (`:here`) + +* **API key**: required +* **Quota**: Depending on the API key +* **Region**: world +* **SSL support**: yes +* **Languages**: The preferred language of address elements in the result. Language code must be provided according to RFC 4647 standard. +* **Documentation**: http://developer.here.com/rest-apis/documentation/geocoder +* **Terms of Service**: http://developer.here.com/faqs#l&t +* **Limitations**: ? + #### ESRI (`:esri`) * **API key**: none * **Quota**: Required for some scenarios (see Terms of Service) * **Region**: world * **SSL support**: yes * **Languages**: English * **Documentation**: http://resources.arcgis.com/en/help/arcgis-online-geocoding-rest-api/ -* **Terms of Service**: http://www.esri.com/software/arcgis/arcgisonline/services/geoservices +* **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})`. #### Data Science Toolkit (`:dstk`) @@ -435,10 +519,57 @@ * **Documentation**: http://www.datasciencetoolkit.org/developerdocs * **Terms of Service**: http://www.datasciencetoolkit.org/developerdocs#googlestylegeocoder * **Limitations**: No reverse geocoding. * **Notes**: If you are hosting your own DSTK server you will need to configure the host name, eg: `Geocoder.configure(:lookup => :dstk, :host => "localhost:4567")`. +#### Baidu (`:baidu`) + +* **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, :api_key => "your_api_key")`. + +#### CloudMade (`:cloudmade`) + +* **API key**: required +* **Quota**: 100,000 free requests, then purchase 100,000 more for $15 +* **Region**: world +* **SSL support**: yes ($5 per 100,000 requests) +* **Languages**: en +* **Documentation**: http://cloudmade.com/documentation/geocoding +* **Terms of Service**: http://cloudmade.com/api-terms-of-service +* **Limitations**: ? + +#### Geocodio (`:geocodio`) + +* **API key**: required +* **Quota**: 2,500 free requests/day then purchase $.001 for each +* **Region**: US +* **SSL support**: no +* **Languages**: en +* **Documentation**: http://geocod.io/docs +* **Terms of Service**: http://geocod.io/terms-of-use +* **Limitations**: ? + +#### SmartyStreets (`:smarty_streets`) + +* **API key**: required +* **Quota**: 10,000 free, 250/month then purchase at sliding scale. Unlimited free for nonprofits & startups +* **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. + +### IP Address Services + #### FreeGeoIP (`:freegeoip`) * **API key**: none * **Quota**: 10000 requests per hour. After reaching the hourly quota, all of your requests will result in HTTP 403 (Forbidden) until it clears up on the next roll over. * **Region**: world @@ -458,20 +589,54 @@ * **Documentation**: http://www.maxmind.com/app/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 (`:baidu`) +#### 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/)) +* **Quota**: none +* **Region**: world +* **SSL support**: N/A +* **Languages**: English +* **Documentation**: http://www.maxmind.com/en/city +* **Terms of Service**: ? +* **Limitations**: ? +* **Notes**: There are two supported formats for MaxMind local data: binary file, and CSV file imported into an SQL database. **You must download a database from MaxMind and set either the `:file` or `:package` configuration option for local lookups to work.** + +**To use a binary file** you must add the *geoip* (or *jgeoip* for JRuby) gem to your Gemfile or have it installed in your system, and specify the path of the MaxMind database in your configuration. For example: + + Geocoder.configure(ip_lookup: :maxmind_local, maxmind_local: {file: File.join('folder', 'GeoLiteCity.dat')}) + +**To use a CSV file** you must import it into an SQL database. The GeoLite *City* and *Country* packages are supported. Configure like so: + + Geocoder.configure(ip_lookup: :maxmind_local, maxmind_local: {package: :city}) + +You can generate ActiveRecord migrations and download and import data via provided rake tasks: + + rails generate geocoder:maxmind:geolite_city + + rake geocoder:maxmind:geolite_city:download + rake geocoder:maxmind:geolite_city:extract + rake geocoder:maxmind:geolite_city:insert + rake geocoder:maxmind:geolite_city:load # runs the above three in sequence + +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, :api_key => "your_api_key")`. +* **Notes**: To use Baidu set `Geocoder.configure(:lookup => :baidu_ip, :api_key => "your_api_key")`. + 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: