geocoder 1.6.2 → 1.7.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (58) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +44 -0
  3. data/LICENSE +1 -1
  4. data/README.md +328 -231
  5. data/bin/console +6 -0
  6. data/lib/generators/geocoder/config/templates/initializer.rb +7 -1
  7. data/lib/geocoder/cache.rb +16 -33
  8. data/lib/geocoder/cache_stores/base.rb +40 -0
  9. data/lib/geocoder/cache_stores/generic.rb +35 -0
  10. data/lib/geocoder/cache_stores/redis.rb +34 -0
  11. data/lib/geocoder/configuration.rb +11 -4
  12. data/lib/geocoder/configuration_hash.rb +4 -4
  13. data/lib/geocoder/ip_address.rb +8 -1
  14. data/lib/geocoder/lookup.rb +16 -2
  15. data/lib/geocoder/lookups/abstract_api.rb +46 -0
  16. data/lib/geocoder/lookups/amazon_location_service.rb +54 -0
  17. data/lib/geocoder/lookups/ban_data_gouv_fr.rb +1 -1
  18. data/lib/geocoder/lookups/base.rb +8 -2
  19. data/lib/geocoder/lookups/bing.rb +1 -1
  20. data/lib/geocoder/lookups/esri.rb +6 -0
  21. data/lib/geocoder/lookups/geoapify.rb +72 -0
  22. data/lib/geocoder/lookups/geocodio.rb +1 -1
  23. data/lib/geocoder/lookups/geoip2.rb +4 -0
  24. data/lib/geocoder/lookups/google.rb +7 -2
  25. data/lib/geocoder/lookups/google_places_details.rb +8 -14
  26. data/lib/geocoder/lookups/google_places_search.rb +28 -2
  27. data/lib/geocoder/lookups/google_premier.rb +4 -0
  28. data/lib/geocoder/lookups/ip2location.rb +10 -6
  29. data/lib/geocoder/lookups/ipdata_co.rb +1 -1
  30. data/lib/geocoder/lookups/ipqualityscore.rb +50 -0
  31. data/lib/geocoder/lookups/latlon.rb +1 -2
  32. data/lib/geocoder/lookups/maxmind_local.rb +7 -1
  33. data/lib/geocoder/lookups/melissa_street.rb +41 -0
  34. data/lib/geocoder/lookups/photon.rb +89 -0
  35. data/lib/geocoder/lookups/smarty_streets.rb +6 -1
  36. data/lib/geocoder/lookups/telize.rb +1 -1
  37. data/lib/geocoder/lookups/test.rb +4 -0
  38. data/lib/geocoder/lookups/uk_ordnance_survey_names.rb +1 -1
  39. data/lib/geocoder/lookups/yandex.rb +1 -2
  40. data/lib/geocoder/results/abstract_api.rb +146 -0
  41. data/lib/geocoder/results/amazon_location_service.rb +57 -0
  42. data/lib/geocoder/results/ban_data_gouv_fr.rb +26 -1
  43. data/lib/geocoder/results/db_ip_com.rb +1 -1
  44. data/lib/geocoder/results/esri.rb +5 -2
  45. data/lib/geocoder/results/geoapify.rb +179 -0
  46. data/lib/geocoder/results/ipqualityscore.rb +54 -0
  47. data/lib/geocoder/results/ipregistry.rb +4 -8
  48. data/lib/geocoder/results/mapbox.rb +10 -4
  49. data/lib/geocoder/results/melissa_street.rb +46 -0
  50. data/lib/geocoder/results/nationaal_georegister_nl.rb +1 -1
  51. data/lib/geocoder/results/nominatim.rb +27 -15
  52. data/lib/geocoder/results/photon.rb +119 -0
  53. data/lib/geocoder/util.rb +29 -0
  54. data/lib/geocoder/version.rb +1 -1
  55. metadata +22 -10
  56. data/examples/autoexpire_cache_dalli.rb +0 -62
  57. data/examples/autoexpire_cache_redis.rb +0 -30
  58. data/lib/hash_recursive_merge.rb +0 -73
data/README.md CHANGED
@@ -5,7 +5,7 @@ Geocoder
5
5
 
6
6
  [![Gem Version](https://badge.fury.io/rb/geocoder.svg)](http://badge.fury.io/rb/geocoder)
7
7
  [![Code Climate](https://codeclimate.com/github/alexreisner/geocoder/badges/gpa.svg)](https://codeclimate.com/github/alexreisner/geocoder)
8
- [![Build Status](https://travis-ci.org/alexreisner/geocoder.svg?branch=master)](https://travis-ci.org/alexreisner/geocoder)
8
+ [![Build Status](https://travis-ci.com/alexreisner/geocoder.svg?branch=master)](https://travis-ci.com/alexreisner/geocoder)
9
9
 
10
10
  Key features:
11
11
 
@@ -18,9 +18,9 @@ Key features:
18
18
 
19
19
  Compatibility:
20
20
 
21
- * Ruby versions: 2.x, and JRuby.
21
+ * Ruby versions: 2.1+, and JRuby.
22
22
  * Databases: MySQL, PostgreSQL, SQLite, and MongoDB.
23
- * Rails: 4, 5, and 6.
23
+ * Rails: 5.x and 6.x.
24
24
  * Works outside of Rails with the `json` (for MRI) or `json_pure` (for JRuby) gem.
25
25
 
26
26
 
@@ -51,8 +51,8 @@ The Rest:
51
51
  * [Technical Discussions](#technical-discussions)
52
52
  * [Troubleshooting](#troubleshooting)
53
53
  * [Known Issues](#known-issues)
54
- * [Reporting Issues](#reporting-issues)
55
- * [Contributing](#contributing)
54
+ * [Reporting Issues](https://github.com/alexreisner/geocoder/blob/master/CONTRIBUTING.md#reporting-bugs)
55
+ * [Contributing](https://github.com/alexreisner/geocoder/blob/master/CONTRIBUTING.md#making-changes)
56
56
 
57
57
  See Also:
58
58
 
@@ -64,23 +64,29 @@ Basic Search
64
64
 
65
65
  In its simplest form, Geocoder takes an address and searches for its latitude/longitude coordinates:
66
66
 
67
- results = Geocoder.search("Paris")
68
- results.first.coordinates
69
- => [48.856614, 2.3522219] # latitude and longitude
67
+ ```ruby
68
+ results = Geocoder.search("Paris")
69
+ results.first.coordinates
70
+ # => [48.856614, 2.3522219] # latitude and longitude
71
+ ```
70
72
 
71
73
  The reverse is possible too. Given coordinates, it finds an address:
72
74
 
73
- results = Geocoder.search([48.856614, 2.3522219])
74
- results.first.address
75
- => "Hôtel de Ville, 75004 Paris, France"
75
+ ```ruby
76
+ results = Geocoder.search([48.856614, 2.3522219])
77
+ results.first.address
78
+ # => "Hôtel de Ville, 75004 Paris, France"
79
+ ```
76
80
 
77
81
  You can also look up the location of an IP addresses:
78
82
 
79
- results = Geocoder.search("172.56.21.89")
80
- results.first.coordinates
81
- => [30.267153, -97.7430608]
82
- results.first.country
83
- => "United States"
83
+ ```ruby
84
+ results = Geocoder.search("172.56.21.89")
85
+ results.first.coordinates
86
+ # => [30.267153, -97.7430608]
87
+ results.first.country
88
+ # => "United States"
89
+ ```
84
90
 
85
91
  **The success and accuracy of geocoding depends entirely on the API being used to do these lookups.** Most queries work fairly well with the default configuration, but every application has different needs and every API has its particular strengths and weaknesses. If you need better coverage for your application you'll want to get familiar with the large number of supported APIs, listed in the [API Guide](https://github.com/alexreisner/geocoder/blob/master/README_API_GUIDE.md).
86
92
 
@@ -92,30 +98,40 @@ To automatically geocode your objects:
92
98
 
93
99
  **1.** Your model must provide a method that returns an address to geocode. This can be a single attribute, but it can also be a method that returns a string assembled from different attributes (eg: `city`, `state`, and `country`). For example, if your model has `street`, `city`, `state`, and `country` attributes you might do something like this:
94
100
 
95
- def address
96
- [street, city, state, country].compact.join(', ')
97
- end
101
+ ```ruby
102
+ def address
103
+ [street, city, state, country].compact.join(', ')
104
+ end
105
+ ```
98
106
 
99
107
  **2.** Your model must have a way to store latitude/longitude coordinates. With ActiveRecord, add two attributes/columns (of type float or decimal) called `latitude` and `longitude`. For MongoDB, use a single field (of type Array) called `coordinates` (i.e., `field :coordinates, type: Array`). (See [Advanced Model Configuration](#advanced-model-configuration) for using different attribute names.)
100
108
 
101
109
  **3.** In your model, tell geocoder where to find the object's address:
102
110
 
103
- geocoded_by :address
111
+ ```ruby
112
+ geocoded_by :address
113
+ ```
104
114
 
105
115
  This adds a `geocode` method which you can invoke via callback:
106
116
 
107
- after_validation :geocode
117
+ ```ruby
118
+ after_validation :geocode
119
+ ```
108
120
 
109
121
  Reverse geocoding (given lat/lon coordinates, find an address) is similar:
110
122
 
111
- reverse_geocoded_by :latitude, :longitude
112
- after_validation :reverse_geocode
123
+ ```ruby
124
+ reverse_geocoded_by :latitude, :longitude
125
+ after_validation :reverse_geocode
126
+ ```
113
127
 
114
128
  With any geocoded objects, you can do the following:
115
129
 
116
- obj.distance_to([43.9,-98.6]) # distance from obj to point
117
- obj.bearing_to([43.9,-98.6]) # bearing from obj to point
118
- obj.bearing_from(obj2) # bearing from obj2 to obj
130
+ ```ruby
131
+ obj.distance_to([43.9,-98.6]) # distance from obj to point
132
+ obj.bearing_to([43.9,-98.6]) # bearing from obj to point
133
+ obj.bearing_from(obj2) # bearing from obj2 to obj
134
+ ```
119
135
 
120
136
  The `bearing_from/to` methods take a single argument which can be: a `[lat,lon]` array, a geocoded object, or a geocodable address (string). The `distance_from/to` methods also take a units argument (`:mi`, `:km`, or `:nm` for nautical miles). See [Distance and Bearing](#distance-and-bearing) below for more info.
121
137
 
@@ -123,18 +139,24 @@ The `bearing_from/to` methods take a single argument which can be: a `[lat,lon]`
123
139
 
124
140
  Before you can call `geocoded_by` you'll need to include the necessary module using one of the following:
125
141
 
126
- include Geocoder::Model::Mongoid
127
- include Geocoder::Model::MongoMapper
142
+ ```ruby
143
+ include Geocoder::Model::Mongoid
144
+ include Geocoder::Model::MongoMapper
145
+ ```
128
146
 
129
147
  ### Latitude/Longitude Order in MongoDB
130
148
 
131
149
  Everywhere coordinates are passed to methods as two-element arrays, Geocoder expects them to be in the order: `[lat, lon]`. However, as per [the GeoJSON spec](http://geojson.org/geojson-spec.html#positions), MongoDB requires that coordinates be stored longitude-first (`[lon, lat]`), so internally they are stored "backwards." Geocoder's methods attempt to hide this, so calling `obj.to_coordinates` (a method added to the object by Geocoder via `geocoded_by`) returns coordinates in the conventional order:
132
150
 
133
- obj.to_coordinates # => [37.7941013, -122.3951096] # [lat, lon]
151
+ ```ruby
152
+ obj.to_coordinates # => [37.7941013, -122.3951096] # [lat, lon]
153
+ ```
134
154
 
135
155
  whereas calling the object's coordinates attribute directly (`obj.coordinates` by default) returns the internal representation which is probably the reverse of what you want:
136
156
 
137
- obj.coordinates # => [-122.3951096, 37.7941013] # [lon, lat]
157
+ ```ruby
158
+ obj.coordinates # => [-122.3951096, 37.7941013] # [lon, lat]
159
+ ```
138
160
 
139
161
  So, be careful.
140
162
 
@@ -142,7 +164,9 @@ So, be careful.
142
164
 
143
165
  To use Geocoder with ActiveRecord and a framework other than Rails (like Sinatra or Padrino), you will need to add this in your model before calling Geocoder methods:
144
166
 
145
- extend Geocoder::Model::ActiveRecord
167
+ ```ruby
168
+ extend Geocoder::Model::ActiveRecord
169
+ ```
146
170
 
147
171
 
148
172
  Geospatial Database Queries
@@ -152,19 +176,23 @@ Geospatial Database Queries
152
176
 
153
177
  To find objects by location, use the following scopes:
154
178
 
155
- Venue.near('Omaha, NE, US') # venues within 20 miles of Omaha
156
- Venue.near([40.71, -100.23], 50) # venues within 50 miles of a point
157
- Venue.near([40.71, -100.23], 50, units: :km) # venues within 50 kilometres of a point
158
- Venue.geocoded # venues with coordinates
159
- Venue.not_geocoded # venues without coordinates
179
+ ```ruby
180
+ Venue.near('Omaha, NE, US') # venues within 20 miles of Omaha
181
+ Venue.near([40.71, -100.23], 50) # venues within 50 miles of a point
182
+ Venue.near([40.71, -100.23], 50, units: :km) # venues within 50 kilometres of a point
183
+ Venue.geocoded # venues with coordinates
184
+ Venue.not_geocoded # venues without coordinates
185
+ ```
160
186
 
161
187
  With geocoded objects you can do things like this:
162
188
 
163
- if obj.geocoded?
164
- obj.nearbys(30) # other objects within 30 miles
165
- obj.distance_from([40.714,-100.234]) # distance from arbitrary point to object
166
- obj.bearing_to("Paris, France") # direction from object to arbitrary point
167
- end
189
+ ```ruby
190
+ if obj.geocoded?
191
+ obj.nearbys(30) # other objects within 30 miles
192
+ obj.distance_from([40.714,-100.234]) # distance from arbitrary point to object
193
+ obj.bearing_to("Paris, France") # direction from object to arbitrary point
194
+ end
195
+ ```
168
196
 
169
197
  ### For MongoDB-backed models:
170
198
 
@@ -176,8 +204,10 @@ Geocoding HTTP Requests
176
204
 
177
205
  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:
178
206
 
179
- # returns Geocoder::Result object
180
- result = request.location
207
+ ```ruby
208
+ # returns Geocoder::Result object
209
+ result = request.location
210
+ ```
181
211
 
182
212
  **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).
183
213
 
@@ -191,71 +221,83 @@ Geocoder supports a variety of street and IP address geocoding services. The def
191
221
 
192
222
  To create a Rails initializer with sample configuration:
193
223
 
194
- rails generate geocoder:config
224
+ ```sh
225
+ rails generate geocoder:config
226
+ ```
195
227
 
196
228
  Some common options are:
197
229
 
198
- # config/initializers/geocoder.rb
199
- Geocoder.configure(
230
+ ```ruby
231
+ # config/initializers/geocoder.rb
232
+ Geocoder.configure(
233
+ # street address geocoding service (default :nominatim)
234
+ lookup: :yandex,
200
235
 
201
- # street address geocoding service (default :nominatim)
202
- lookup: :yandex,
236
+ # IP address geocoding service (default :ipinfo_io)
237
+ ip_lookup: :maxmind,
203
238
 
204
- # IP address geocoding service (default :ipinfo_io)
205
- ip_lookup: :maxmind,
239
+ # to use an API key:
240
+ api_key: "...",
206
241
 
207
- # to use an API key:
208
- api_key: "...",
242
+ # geocoding service request timeout, in seconds (default 3):
243
+ timeout: 5,
209
244
 
210
- # geocoding service request timeout, in seconds (default 3):
211
- timeout: 5,
245
+ # set default units to kilometers:
246
+ units: :km,
212
247
 
213
- # set default units to kilometers:
214
- units: :km,
215
-
216
- # caching (see [below](#caching) for details):
217
- cache: Redis.new,
218
- cache_prefix: "..."
219
-
220
- )
248
+ # caching (see Caching section below for details):
249
+ # warning: `cache_prefix` is deprecated, use `cache_options` instead
250
+ cache: Redis.new,
251
+ cache_options: {
252
+ expiration: 2.days, # Redis ttl
253
+ prefix: "..."
254
+ }
255
+ )
256
+ ```
221
257
 
222
258
  Please see [`lib/geocoder/configuration.rb`](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/configuration.rb) for a complete list of configuration options. Additionally, some lookups have their own special configuration options which are directly supported by Geocoder. For example, to specify a value for Google's `bounds` parameter:
223
259
 
224
- # with Google:
225
- Geocoder.search("Middletown", bounds: [[40.6,-77.9], [39.9,-75.9]])
260
+ ```ruby
261
+ # with Google:
262
+ Geocoder.search("Middletown", bounds: [[40.6,-77.9], [39.9,-75.9]])
263
+ ```
226
264
 
227
265
  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, which appends options to the query string of the geocoding request. For example:
228
266
 
229
- # Nominatim's `countrycodes` parameter:
230
- Geocoder.search("Rome", params: {countrycodes: "us,ca"})
267
+ ```ruby
268
+ # Nominatim's `countrycodes` parameter:
269
+ Geocoder.search("Rome", params: {countrycodes: "us,ca"})
231
270
 
232
- # Google's `region` parameter:
233
- Geocoder.search("Rome", params: {region: "..."})
271
+ # Google's `region` parameter:
272
+ Geocoder.search("Rome", params: {region: "..."})
273
+ ```
234
274
 
235
275
  ### Configuring Multiple Services
236
276
 
237
277
  You can configure multiple geocoding services at once by using the service's name as a key for a sub-configuration hash, like this:
238
278
 
239
- Geocoder.configure(
279
+ ```ruby
280
+ Geocoder.configure(
240
281
 
241
- timeout: 2,
242
- cache: Redis.new,
282
+ timeout: 2,
283
+ cache: Redis.new,
243
284
 
244
- yandex: {
245
- api_key: "...",
246
- timeout: 5
247
- },
285
+ yandex: {
286
+ api_key: "...",
287
+ timeout: 5
288
+ },
248
289
 
249
- baidu: {
250
- api_key: "..."
251
- },
290
+ baidu: {
291
+ api_key: "..."
292
+ },
252
293
 
253
- maxmind: {
254
- api_key: "...",
255
- service: :omni
256
- }
294
+ maxmind: {
295
+ api_key: "...",
296
+ service: :omni
297
+ }
257
298
 
258
- )
299
+ )
300
+ ```
259
301
 
260
302
  Lookup-specific settings override global settings so, in this example, the timeout for all lookups is 2 seconds, except for Yandex which is 5.
261
303
 
@@ -267,12 +309,16 @@ Performance and Optimization
267
309
 
268
310
  In MySQL and Postgres, queries use a bounding box to limit the number of points over which a more precise distance calculation needs to be done. To take advantage of this optimisation, you need to add a composite index on latitude and longitude. In your Rails migration:
269
311
 
270
- add_index :table, [:latitude, :longitude]
312
+ ```ruby
313
+ add_index :table, [:latitude, :longitude]
314
+ ```
271
315
 
272
316
  In MongoDB, by default, the methods `geocoded_by` and `reverse_geocoded_by` create a geospatial index. You can avoid index creation with the `:skip_index option`, for example:
273
317
 
274
- include Geocoder::Model::Mongoid
275
- geocoded_by :address, skip_index: true
318
+ ```ruby
319
+ include Geocoder::Model::Mongoid
320
+ geocoded_by :address, skip_index: true
321
+ ```
276
322
 
277
323
  ### Avoiding Unnecessary API Requests
278
324
 
@@ -283,13 +329,17 @@ Geocoding only needs to be performed under certain conditions. To avoid unnecess
283
329
 
284
330
  The exact code will vary depending on the method you use for your geocodable string, but it would be something like this:
285
331
 
286
- after_validation :geocode, if: ->(obj){ obj.address.present? and obj.address_changed? }
332
+ ```ruby
333
+ after_validation :geocode, if: ->(obj){ obj.address.present? and obj.address_changed? }
334
+ ```
287
335
 
288
336
  ### Caching
289
337
 
290
338
  When relying on any external service, it's always a good idea 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:
291
339
 
292
- Geocoder.configure(cache: Redis.new)
340
+ ```ruby
341
+ Geocoder.configure(cache: Redis.new)
342
+ ```
293
343
 
294
344
  This example uses Redis, but the cache store can be any object that supports these methods:
295
345
 
@@ -300,20 +350,30 @@ This example uses Redis, but the cache store can be any object that supports the
300
350
 
301
351
  Even a plain Ruby hash will work, though it's not a great choice (cleared out when app is restarted, not shared between app instances, etc).
302
352
 
353
+ When using Rails use the Generic cache store as an adapter around `Rails.cache`:
354
+
355
+ ```ruby
356
+ Geocoder.configure(cache: Geocoder::CacheStore::Generic.new(Rails.cache, {}))
357
+ ```
358
+
303
359
  You can also set a custom prefix to be used for cache keys:
304
360
 
305
- Geocoder.configure(cache_prefix: "...")
361
+ ```ruby
362
+ Geocoder.configure(cache_options: { prefix: "..." })
363
+ ```
306
364
 
307
365
  By default the prefix is `geocoder:`
308
366
 
309
367
  If you need to expire cached content:
310
368
 
311
- Geocoder::Lookup.get(Geocoder.config[:lookup]).cache.expire(:all) # expire cached results for current Lookup
312
- Geocoder::Lookup.get(:nominatim).cache.expire("http://...") # expire cached result for a specific URL
313
- Geocoder::Lookup.get(:nominatim).cache.expire(:all) # expire cached results for Google Lookup
314
- # expire all cached results for all Lookups.
315
- # Be aware that this methods spawns a new Lookup object for each Service
316
- Geocoder::Lookup.all_services.each{|service| Geocoder::Lookup.get(service).cache.expire(:all)}
369
+ ```ruby
370
+ Geocoder::Lookup.get(Geocoder.config[:lookup]).cache.expire(:all) # expire cached results for current Lookup
371
+ Geocoder::Lookup.get(:nominatim).cache.expire("http://...") # expire cached result for a specific URL
372
+ Geocoder::Lookup.get(:nominatim).cache.expire(:all) # expire cached results for Google Lookup
373
+ # expire all cached results for all Lookups.
374
+ # Be aware that this methods spawns a new Lookup object for each Service
375
+ Geocoder::Lookup.all_services.each{|service| Geocoder::Lookup.get(service).cache.expire(:all)}
376
+ ```
317
377
 
318
378
  Do *not* include the prefix when passing a URL to be expired. Expiring `:all` will only expire keys with the configured prefix -- it will *not* expire every entry in your key/value store.
319
379
 
@@ -327,44 +387,55 @@ Advanced Model Configuration
327
387
 
328
388
  You are not stuck with the `latitude` and `longitude` database column names (with ActiveRecord) or the `coordinates` array (Mongo) for storing coordinates. For example:
329
389
 
330
- geocoded_by :address, latitude: :lat, longitude: :lon # ActiveRecord
331
- geocoded_by :address, coordinates: :coords # MongoDB
390
+ ```ruby
391
+ geocoded_by :address, latitude: :lat, longitude: :lon # ActiveRecord
392
+ geocoded_by :address, coordinates: :coords # MongoDB
393
+ ```
332
394
 
333
395
  For reverse geocoding, you can specify the attribute where the address will be stored. For example:
334
396
 
335
- reverse_geocoded_by :latitude, :longitude, address: :loc # ActiveRecord
336
- reverse_geocoded_by :coordinates, address: :street_address # MongoDB
397
+ ```ruby
398
+ reverse_geocoded_by :latitude, :longitude, address: :loc # ActiveRecord
399
+ reverse_geocoded_by :coordinates, address: :street_address # MongoDB
400
+ ```
337
401
 
338
402
  To specify geocoding parameters in your model:
339
403
 
340
- geocoded_by :address, params: {region: "..."}
404
+ ```ruby
405
+ geocoded_by :address, params: {region: "..."}
406
+ ```
341
407
 
342
408
  Supported parameters: `:lookup`, `:ip_lookup`, `:language`, and `:params`. You can specify an anonymous function if you want to set these on a per-request basis. For example, to use different lookups for objects in different regions:
343
409
 
344
- geocoded_by :address, lookup: lambda{ |obj| obj.geocoder_lookup }
410
+ ```ruby
411
+ geocoded_by :address, lookup: lambda{ |obj| obj.geocoder_lookup }
345
412
 
346
- def geocoder_lookup
347
- if country_code == "RU"
348
- :yandex
349
- elsif country_code == "CN"
350
- :baidu
351
- else
352
- :nominatim
353
- end
354
- end
413
+ def geocoder_lookup
414
+ if country_code == "RU"
415
+ :yandex
416
+ elsif country_code == "CN"
417
+ :baidu
418
+ else
419
+ :nominatim
420
+ end
421
+ end
422
+ ```
355
423
 
356
424
  ### Custom Result Handling
357
425
 
358
426
  So far we have seen examples where geocoding results are assigned automatically to predefined object attributes. However, you can skip the auto-assignment by providing a block which handles the parsed geocoding results any way you like, for example:
359
427
 
360
- reverse_geocoded_by :latitude, :longitude do |obj,results|
361
- if geo = results.first
362
- obj.city = geo.city
363
- obj.zipcode = geo.postal_code
364
- obj.country = geo.country_code
365
- end
366
- end
367
- after_validation :reverse_geocode
428
+ ```ruby
429
+ reverse_geocoded_by :latitude, :longitude do |obj,results|
430
+ if geo = results.first
431
+ obj.city = geo.city
432
+ obj.zipcode = geo.postal_code
433
+ obj.country = geo.country_code
434
+ end
435
+ end
436
+
437
+ after_validation :reverse_geocode
438
+ ```
368
439
 
369
440
  Every `Geocoder::Result` object, `result`, provides the following data:
370
441
 
@@ -390,23 +461,26 @@ You can apply both forward and reverse geocoding to the same model (i.e. users c
390
461
 
391
462
  For example:
392
463
 
393
- class Venue
394
-
395
- # build an address from street, city, and state attributes
396
- geocoded_by :address_from_components
464
+ ```ruby
465
+ class Venue
466
+ # build an address from street, city, and state attributes
467
+ geocoded_by :address_from_components
397
468
 
398
- # store the fetched address in the full_address attribute
399
- reverse_geocoded_by :latitude, :longitude, address: :full_address
400
- end
469
+ # store the fetched address in the full_address attribute
470
+ reverse_geocoded_by :latitude, :longitude, address: :full_address
471
+ end
472
+ ```
401
473
 
402
474
  The same goes for latitude/longitude. However, for purposes of querying the database, there can be only one authoritative set of latitude/longitude attributes for use in database queries. This is whichever you specify last. For example, here the attributes *without* the `fetched_` prefix will be authoritative:
403
475
 
404
- class Venue
405
- geocoded_by :address,
406
- latitude: :fetched_latitude,
407
- longitude: :fetched_longitude
408
- reverse_geocoded_by :latitude, :longitude
409
- end
476
+ ```ruby
477
+ class Venue
478
+ geocoded_by :address,
479
+ latitude: :fetched_latitude,
480
+ longitude: :fetched_longitude
481
+ reverse_geocoded_by :latitude, :longitude
482
+ end
483
+ ```
410
484
 
411
485
 
412
486
  Advanced Database Queries
@@ -416,21 +490,29 @@ Advanced Database Queries
416
490
 
417
491
  The default `near` search looks for objects within a circle. To search within a doughnut or ring use the `:min_radius` option:
418
492
 
419
- Venue.near("Austin, TX", 200, min_radius: 40)
493
+ ```ruby
494
+ Venue.near("Austin, TX", 200, min_radius: 40)
495
+ ```
420
496
 
421
497
  To search within a rectangle (note that results will *not* include `distance` and `bearing` attributes):
422
498
 
423
- sw_corner = [40.71, 100.23]
424
- ne_corner = [36.12, 88.65]
425
- Venue.within_bounding_box(sw_corner, ne_corner)
499
+ ```ruby
500
+ sw_corner = [40.71, 100.23]
501
+ ne_corner = [36.12, 88.65]
502
+ Venue.within_bounding_box(sw_corner, ne_corner)
503
+ ```
426
504
 
427
505
  To search for objects near a certain point where each object has a different distance requirement (which is defined in the database), you can pass a column name for the radius:
428
506
 
429
- Venue.near([40.71, 99.23], :effective_radius)
507
+ ```ruby
508
+ Venue.near([40.71, 99.23], :effective_radius)
509
+ ```
430
510
 
431
511
  If you store multiple sets of coordinates for each object, you can specify latitude and longitude columns to use for a search:
432
512
 
433
- Venue.near("Paris", 50, latitude: :secondary_latitude, longitude: :secondary_longitude)
513
+ ```ruby
514
+ Venue.near("Paris", 50, latitude: :secondary_latitude, longitude: :secondary_longitude)
515
+ ```
434
516
 
435
517
  ### Distance and Bearing
436
518
 
@@ -450,9 +532,11 @@ Results are automatically sorted by distance from the search point, closest to f
450
532
 
451
533
  You can convert these to compass point names via provided method:
452
534
 
453
- Geocoder::Calculations.compass_point(355) # => "N"
454
- Geocoder::Calculations.compass_point(45) # => "NE"
455
- Geocoder::Calculations.compass_point(208) # => "SW"
535
+ ```ruby
536
+ Geocoder::Calculations.compass_point(355) # => "N"
537
+ Geocoder::Calculations.compass_point(45) # => "NE"
538
+ Geocoder::Calculations.compass_point(208) # => "SW"
539
+ ```
456
540
 
457
541
  _Note: when running queries on SQLite, `distance` and `bearing` are provided for consistency only. They are not very accurate._
458
542
 
@@ -464,13 +548,15 @@ Geospatial Calculations
464
548
 
465
549
  The `Geocoder::Calculations` module contains some useful methods:
466
550
 
467
- # find the distance between two arbitrary points
468
- Geocoder::Calculations.distance_between([47.858205,2.294359], [40.748433,-73.985655])
469
- => 3619.77359999382 # in configured units (default miles)
551
+ ```ruby
552
+ # find the distance between two arbitrary points
553
+ Geocoder::Calculations.distance_between([47.858205,2.294359], [40.748433,-73.985655])
554
+ => 3619.77359999382 # in configured units (default miles)
470
555
 
471
- # find the geographic center (aka center of gravity) of objects or points
472
- Geocoder::Calculations.geographic_center([city1, city2, [40.22,-73.99], city4])
473
- => [35.14968, -90.048929]
556
+ # find the geographic center (aka center of gravity) of objects or points
557
+ Geocoder::Calculations.geographic_center([city1, city2, [40.22,-73.99], city4])
558
+ => [35.14968, -90.048929]
559
+ ```
474
560
 
475
561
  See [the code](https://github.com/alexreisner/geocoder/blob/master/lib/geocoder/calculations.rb) for more!
476
562
 
@@ -480,19 +566,27 @@ Batch Geocoding
480
566
 
481
567
  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:
482
568
 
483
- rake geocode:all CLASS=YourModel
569
+ ```sh
570
+ rake geocode:all CLASS=YourModel
571
+ ```
484
572
 
485
573
  If you need reverse geocoding instead, call the task with REVERSE=true:
486
574
 
487
- rake geocode:all CLASS=YourModel REVERSE=true
575
+ ```sh
576
+ rake geocode:all CLASS=YourModel REVERSE=true
577
+ ```
488
578
 
489
579
  In either case, it won't try to geocode objects that are already geocoded. The task will print warnings if you exceed the rate limit for your geocoding service. Some services 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:
490
580
 
491
- rake geocode:all CLASS=YourModel SLEEP=0.25 BATCH=100
581
+ ```sh
582
+ rake geocode:all CLASS=YourModel SLEEP=0.25 BATCH=100
583
+ ```
492
584
 
493
585
  To avoid exceeding per-day limits you can add a `LIMIT` option. However, this will ignore the `BATCH` value, if provided.
494
586
 
495
- rake geocode:all CLASS=YourModel LIMIT=1000
587
+ ```sh
588
+ rake geocode:all CLASS=YourModel LIMIT=1000
589
+ ```
496
590
 
497
591
 
498
592
  Testing
@@ -500,42 +594,54 @@ Testing
500
594
 
501
595
  When writing tests for an app that uses Geocoder it may be useful to avoid network calls and have Geocoder return consistent, configurable results. To do this, configure the `:test` lookup and/or `:ip_lookup`
502
596
 
503
- Geocoder.configure(lookup: :test, ip_lookup: :test)
597
+ ```ruby
598
+ Geocoder.configure(lookup: :test, ip_lookup: :test)
599
+ ```
504
600
 
505
601
  Add stubs to define the results that will be returned:
506
602
 
507
- Geocoder::Lookup::Test.add_stub(
508
- "New York, NY", [
509
- {
510
- 'coordinates' => [40.7143528, -74.0059731],
511
- 'address' => 'New York, NY, USA',
512
- 'state' => 'New York',
513
- 'state_code' => 'NY',
514
- 'country' => 'United States',
515
- 'country_code' => 'US'
516
- }
517
- ]
518
- )
603
+ ```ruby
604
+ Geocoder::Lookup::Test.add_stub(
605
+ "New York, NY", [
606
+ {
607
+ 'coordinates' => [40.7143528, -74.0059731],
608
+ 'address' => 'New York, NY, USA',
609
+ 'state' => 'New York',
610
+ 'state_code' => 'NY',
611
+ 'country' => 'United States',
612
+ 'country_code' => 'US'
613
+ }
614
+ ]
615
+ )
616
+ ```
519
617
 
520
618
  With the above stub defined, any query for "New York, NY" will return the results array that follows. You can also set a default stub, to be returned when no other stub matches a given query:
521
619
 
522
- Geocoder::Lookup::Test.set_default_stub(
523
- [
524
- {
525
- 'coordinates' => [40.7143528, -74.0059731],
526
- 'address' => 'New York, NY, USA',
527
- 'state' => 'New York',
528
- 'state_code' => 'NY',
529
- 'country' => 'United States',
530
- 'country_code' => 'US'
531
- }
532
- ]
533
- )
620
+ ```ruby
621
+ Geocoder::Lookup::Test.set_default_stub(
622
+ [
623
+ {
624
+ 'coordinates' => [40.7143528, -74.0059731],
625
+ 'address' => 'New York, NY, USA',
626
+ 'state' => 'New York',
627
+ 'state_code' => 'NY',
628
+ 'country' => 'United States',
629
+ 'country_code' => 'US'
630
+ }
631
+ ]
632
+ )
633
+ ```
634
+
635
+ You may also delete a single stub, or reset all stubs _including the default stub_:
636
+
637
+ ```ruby
638
+ Geocoder::Lookup::Test.delete_stub('New York, NY')
639
+ Geocoder::Lookup::Test.reset
640
+ ```
534
641
 
535
642
  Notes:
536
643
 
537
644
  - Keys must be strings (not symbols) when calling `add_stub` or `set_default_stub`. For example `'country' =>` not `:country =>`.
538
- - To clear stubs (e.g. prior to another spec), use `Geocoder::Lookup::Test.reset`. This will clear all stubs _including the default stub_.
539
645
  - The stubbed result objects returned by the Test lookup do not support all the methods real result objects do. If you need to test interaction with real results it may be better to use an external stubbing tool and something like WebMock or VCR to prevent network calls.
540
646
 
541
647
 
@@ -544,21 +650,27 @@ Error Handling
544
650
 
545
651
  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:
546
652
 
547
- Geocoder.configure(always_raise: [SocketError, Timeout::Error])
653
+ ```ruby
654
+ Geocoder.configure(always_raise: [SocketError, Timeout::Error])
655
+ ```
548
656
 
549
657
  You can also do this to raise all exceptions:
550
658
 
551
- Geocoder.configure(always_raise: :all)
659
+ ```ruby
660
+ Geocoder.configure(always_raise: :all)
661
+ ```
552
662
 
553
663
  The raise-able exceptions are:
554
664
 
555
- SocketError
556
- Timeout::Error
557
- Geocoder::OverQueryLimitError
558
- Geocoder::RequestDenied
559
- Geocoder::InvalidRequest
560
- Geocoder::InvalidApiKey
561
- Geocoder::ServiceUnavailable
665
+ ```ruby
666
+ SocketError
667
+ Timeout::Error
668
+ Geocoder::OverQueryLimitError
669
+ Geocoder::RequestDenied
670
+ Geocoder::InvalidRequest
671
+ Geocoder::InvalidApiKey
672
+ Geocoder::ServiceUnavailable
673
+ ```
562
674
 
563
675
  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.
564
676
 
@@ -568,15 +680,17 @@ Command Line Interface
568
680
 
569
681
  When you install the Geocoder gem it adds a `geocode` command to your shell. You can search for a street address, IP address, postal code, coordinates, etc just like you can with the Geocoder.search method for example:
570
682
 
571
- $ geocode 29.951,-90.081
572
- Latitude: 29.952211
573
- Longitude: -90.080563
574
- Full address: 1500 Sugar Bowl Dr, New Orleans, LA 70112, USA
575
- City: New Orleans
576
- State/province: Louisiana
577
- Postal code: 70112
578
- Country: United States
579
- Map: http://maps.google.com/maps?q=29.952211,-90.080563
683
+ ```sh
684
+ $ geocode 29.951,-90.081
685
+ Latitude: 29.952211
686
+ Longitude: -90.080563
687
+ Full address: 1500 Sugar Bowl Dr, New Orleans, LA 70112, USA
688
+ City: New Orleans
689
+ State/province: Louisiana
690
+ Postal code: 70112
691
+ Country: United States
692
+ Map: http://maps.google.com/maps?q=29.952211,-90.080563
693
+ ```
580
694
 
581
695
  There are also a number of options for setting the geocoding API, key, and language, viewing the raw JSON response, and more. Please run `geocode -h` for details.
582
696
 
@@ -612,8 +726,10 @@ Troubleshooting
612
726
 
613
727
  If you get one of these errors:
614
728
 
615
- uninitialized constant Geocoder::Model::Mongoid
616
- uninitialized constant Geocoder::Model::Mongoid::Mongo
729
+ ```ruby
730
+ uninitialized constant Geocoder::Model::Mongoid
731
+ uninitialized constant Geocoder::Model::Mongoid::Mongo
732
+ ```
617
733
 
618
734
  you should check your Gemfile to make sure the Mongoid gem is listed _before_ Geocoder. If Mongoid isn't loaded when Geocoder is initialized, Geocoder will not load support for Mongoid.
619
735
 
@@ -638,13 +754,17 @@ For the most part, the speed of geocoding requests has little to do with the Geo
638
754
 
639
755
  Take a look at the server's raw response. You can do this by getting the request URL in an app console:
640
756
 
641
- Geocoder::Lookup.get(:nominatim).query_url(Geocoder::Query.new("..."))
757
+ ```ruby
758
+ Geocoder::Lookup.get(:nominatim).query_url(Geocoder::Query.new("..."))
759
+ ```
642
760
 
643
761
  Replace `:nominatim` 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.
644
762
 
645
763
  You can also fetch the response in the console:
646
764
 
647
- Geocoder::Lookup.get(:nominatim).send(:fetch_raw_data, Geocoder::Query.new("..."))
765
+ ```ruby
766
+ Geocoder::Lookup.get(:nominatim).send(:fetch_raw_data, Geocoder::Query.new("..."))
767
+ ```
648
768
 
649
769
 
650
770
  Known Issues
@@ -660,14 +780,16 @@ You cannot use the `near` scope with another scope that provides an `includes` o
660
780
 
661
781
  Instead of using `includes` to reduce the number of database queries, try using `joins` with either the `:select` option or a call to `preload`. For example:
662
782
 
663
- # Pass a :select option to the near scope to get the columns you want.
664
- # Instead of City.near(...).includes(:venues), try:
665
- City.near("Omaha, NE", 20, select: "cities.*, venues.*").joins(:venues)
783
+ ```ruby
784
+ # Pass a :select option to the near scope to get the columns you want.
785
+ # Instead of City.near(...).includes(:venues), try:
786
+ City.near("Omaha, NE", 20, select: "cities.*, venues.*").joins(:venues)
666
787
 
667
- # This preload call will normally trigger two queries regardless of the
668
- # number of results; one query on hotels, and one query on administrators.
669
- # Instead of Hotel.near(...).includes(:administrator), try:
670
- Hotel.near("London, UK", 50).joins(:administrator).preload(:administrator)
788
+ # This preload call will normally trigger two queries regardless of the
789
+ # number of results; one query on hotels, and one query on administrators.
790
+ # Instead of Hotel.near(...).includes(:administrator), try:
791
+ Hotel.near("London, UK", 50).joins(:administrator).preload(:administrator)
792
+ ```
671
793
 
672
794
  If anyone has a more elegant solution to this problem I am very interested in seeing it.
673
795
 
@@ -676,29 +798,4 @@ If anyone has a more elegant solution to this problem I am very interested in se
676
798
  The `near` method will not look across the 180th meridian to find objects close to a given point. In practice this is rarely an issue outside of New Zealand and certain surrounding islands. This problem does not exist with the zero-meridian. The problem is due to a shortcoming of the Haversine formula which Geocoder uses to calculate distances.
677
799
 
678
800
 
679
- Reporting Issues
680
- ----------------
681
-
682
- 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). Please describe as specifically as you can what behavior you are seeing (eg: an error message? a nil return value?).
683
-
684
- 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.
685
-
686
-
687
- Contributing
688
- ------------
689
-
690
- Contributions are welcome via Github pull requests. If you are new to the project and looking for a way to get involved, try picking up an issue with a "beginner-task" label. Hints about what needs to be done are usually provided.
691
-
692
- For all contributions, please respect the following guidelines:
693
-
694
- * Each pull request should implement ONE feature or bugfix. If you want to add or fix more than one thing, submit more than one pull request.
695
- * Do not commit changes to files that are irrelevant to your feature or bugfix (eg: `.gitignore`).
696
- * Do not add dependencies on other gems.
697
- * Do not add unnecessary `require` statements which could cause LoadErrors on certain systems.
698
- * Remember: Geocoder needs to run outside of Rails. Don't assume things like ActiveSupport are available.
699
- * 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.
700
- * Be aware that the pull request review process is not immediate, and is generally proportional to the size of the pull request.
701
- * If your pull request is merged, please do not ask for an immediate release of the gem. There are many factors contributing to when releases occur (remember that they affect thousands of apps with Geocoder in their Gemfiles). If necessary, please install from the Github source until the next official release.
702
-
703
-
704
- Copyright :copyright: 2009-2020 Alex Reisner, released under the MIT license.
801
+ Copyright :copyright: 2009-2021 Alex Reisner, released under the MIT license.