earth-ruby19 0.2.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (187) hide show
  1. data/Gemfile +5 -0
  2. data/Gemfile.lock +138 -0
  3. data/LICENSE +20 -0
  4. data/README.markdown +38 -0
  5. data/lib/earth.rb +146 -0
  6. data/lib/earth/active_record_ext.rb +9 -0
  7. data/lib/earth/air.rb +13 -0
  8. data/lib/earth/air/aircraft.rb +21 -0
  9. data/lib/earth/air/aircraft/data_miner.rb +184 -0
  10. data/lib/earth/air/aircraft_class.rb +10 -0
  11. data/lib/earth/air/aircraft_class/data_miner.rb +42 -0
  12. data/lib/earth/air/aircraft_manufacturer.rb +9 -0
  13. data/lib/earth/air/aircraft_manufacturer/data_miner.rb +20 -0
  14. data/lib/earth/air/airline.rb +16 -0
  15. data/lib/earth/air/airline/data_miner.rb +57 -0
  16. data/lib/earth/air/airport.rb +44 -0
  17. data/lib/earth/air/airport/data_miner.rb +80 -0
  18. data/lib/earth/air/data_miner.rb +15 -0
  19. data/lib/earth/air/flight_configuration.rb +7 -0
  20. data/lib/earth/air/flight_configuration/data_miner.rb +16 -0
  21. data/lib/earth/air/flight_distance_class.rb +7 -0
  22. data/lib/earth/air/flight_distance_class/data_miner.rb +16 -0
  23. data/lib/earth/air/flight_domesticity.rb +6 -0
  24. data/lib/earth/air/flight_domesticity/data_miner.rb +57 -0
  25. data/lib/earth/air/flight_fuel_type.rb +12 -0
  26. data/lib/earth/air/flight_fuel_type/data_miner.rb +12 -0
  27. data/lib/earth/air/flight_propulsion.rb +7 -0
  28. data/lib/earth/air/flight_propulsion/data_miner.rb +16 -0
  29. data/lib/earth/air/flight_seat_class.rb +12 -0
  30. data/lib/earth/air/flight_seat_class/data_miner.rb +36 -0
  31. data/lib/earth/air/flight_segment.rb +29 -0
  32. data/lib/earth/air/flight_segment/data_miner.rb +330 -0
  33. data/lib/earth/air/flight_service.rb +7 -0
  34. data/lib/earth/air/flight_service/data_miner.rb +16 -0
  35. data/lib/earth/all.rb +11 -0
  36. data/lib/earth/automobile.rb +8 -0
  37. data/lib/earth/automobile/automobile_fuel_type.rb +18 -0
  38. data/lib/earth/automobile/automobile_fuel_type/data_miner.rb +45 -0
  39. data/lib/earth/automobile/automobile_make.rb +14 -0
  40. data/lib/earth/automobile/automobile_make/data_miner.rb +68 -0
  41. data/lib/earth/automobile/automobile_make_fleet_year.rb +15 -0
  42. data/lib/earth/automobile/automobile_make_fleet_year/data_miner.rb +29 -0
  43. data/lib/earth/automobile/automobile_make_year.rb +14 -0
  44. data/lib/earth/automobile/automobile_make_year/data_miner.rb +45 -0
  45. data/lib/earth/automobile/automobile_model.rb +14 -0
  46. data/lib/earth/automobile/automobile_model/data_miner.rb +38 -0
  47. data/lib/earth/automobile/automobile_model_year.rb +15 -0
  48. data/lib/earth/automobile/automobile_model_year/data_miner.rb +51 -0
  49. data/lib/earth/automobile/automobile_size_class.rb +14 -0
  50. data/lib/earth/automobile/automobile_size_class/data_miner.rb +43 -0
  51. data/lib/earth/automobile/automobile_variant.rb +17 -0
  52. data/lib/earth/automobile/automobile_variant/data_miner.rb +460 -0
  53. data/lib/earth/automobile/data_miner.rb +8 -0
  54. data/lib/earth/base.rb +7 -0
  55. data/lib/earth/bus.rb +1 -0
  56. data/lib/earth/bus/bus_class.rb +19 -0
  57. data/lib/earth/bus/bus_class/data_miner.rb +41 -0
  58. data/lib/earth/bus/data_miner.rb +1 -0
  59. data/lib/earth/conversions_ext.rb +45 -0
  60. data/lib/earth/data_miner.rb +10 -0
  61. data/lib/earth/diet.rb +2 -0
  62. data/lib/earth/diet/data_miner.rb +2 -0
  63. data/lib/earth/diet/diet_class.rb +15 -0
  64. data/lib/earth/diet/diet_class/data_miner.rb +36 -0
  65. data/lib/earth/diet/food_group.rb +17 -0
  66. data/lib/earth/diet/food_group/data_miner.rb +26 -0
  67. data/lib/earth/fuel.rb +2 -0
  68. data/lib/earth/fuel/data_miner.rb +2 -0
  69. data/lib/earth/fuel/fuel_price.rb +13 -0
  70. data/lib/earth/fuel/fuel_price/data_miner.rb +20 -0
  71. data/lib/earth/fuel/fuel_type.rb +18 -0
  72. data/lib/earth/fuel/fuel_type/data_miner.rb +37 -0
  73. data/lib/earth/hospitality.rb +1 -0
  74. data/lib/earth/hospitality/data_miner.rb +1 -0
  75. data/lib/earth/hospitality/lodging_class.rb +9 -0
  76. data/lib/earth/hospitality/lodging_class/data_miner.rb +30 -0
  77. data/lib/earth/industry.rb +10 -0
  78. data/lib/earth/industry/industry.rb +23 -0
  79. data/lib/earth/industry/industry_product.rb +22 -0
  80. data/lib/earth/industry/industry_product_line.rb +20 -0
  81. data/lib/earth/industry/industry_sector.rb +20 -0
  82. data/lib/earth/industry/merchant.rb +18 -0
  83. data/lib/earth/industry/merchant_category.rb +22 -0
  84. data/lib/earth/industry/merchant_category_industry.rb +20 -0
  85. data/lib/earth/industry/product_line.rb +22 -0
  86. data/lib/earth/industry/product_line_industry_product.rb +20 -0
  87. data/lib/earth/industry/sector.rb +19 -0
  88. data/lib/earth/inflectors.rb +9 -0
  89. data/lib/earth/locality.rb +10 -0
  90. data/lib/earth/locality/census_division.rb +22 -0
  91. data/lib/earth/locality/census_division/data_miner.rb +64 -0
  92. data/lib/earth/locality/census_region.rb +13 -0
  93. data/lib/earth/locality/census_region/data_miner.rb +17 -0
  94. data/lib/earth/locality/climate_division.rb +17 -0
  95. data/lib/earth/locality/climate_division/data_miner.rb +20 -0
  96. data/lib/earth/locality/country.rb +13 -0
  97. data/lib/earth/locality/country/data_miner.rb +19 -0
  98. data/lib/earth/locality/data_miner.rb +10 -0
  99. data/lib/earth/locality/egrid_region.rb +15 -0
  100. data/lib/earth/locality/egrid_region/data_miner.rb +35 -0
  101. data/lib/earth/locality/egrid_subregion.rb +16 -0
  102. data/lib/earth/locality/egrid_subregion/data_miner.rb +65 -0
  103. data/lib/earth/locality/petroleum_administration_for_defense_district.rb +13 -0
  104. data/lib/earth/locality/petroleum_administration_for_defense_district/data_miner.rb +21 -0
  105. data/lib/earth/locality/state.rb +22 -0
  106. data/lib/earth/locality/state/data_miner.rb +37 -0
  107. data/lib/earth/locality/urbanity.rb +10 -0
  108. data/lib/earth/locality/urbanity/data_miner.rb +15 -0
  109. data/lib/earth/locality/zip_code.rb +23 -0
  110. data/lib/earth/locality/zip_code/data_miner.rb +43 -0
  111. data/lib/earth/pet.rb +4 -0
  112. data/lib/earth/pet/breed.rb +15 -0
  113. data/lib/earth/pet/breed/data_miner.rb +25 -0
  114. data/lib/earth/pet/breed_gender.rb +14 -0
  115. data/lib/earth/pet/breed_gender/data_miner.rb +21 -0
  116. data/lib/earth/pet/data_miner.rb +4 -0
  117. data/lib/earth/pet/gender.rb +10 -0
  118. data/lib/earth/pet/gender/data_miner.rb +13 -0
  119. data/lib/earth/pet/species.rb +40 -0
  120. data/lib/earth/pet/species/data_miner.rb +42 -0
  121. data/lib/earth/rail.rb +1 -0
  122. data/lib/earth/rail/data_miner.rb +1 -0
  123. data/lib/earth/rail/rail_class.rb +16 -0
  124. data/lib/earth/rail/rail_class/data_miner.rb +36 -0
  125. data/lib/earth/residence.rb +8 -0
  126. data/lib/earth/residence/air_conditioner_use.rb +13 -0
  127. data/lib/earth/residence/air_conditioner_use/data_miner.rb +22 -0
  128. data/lib/earth/residence/clothes_machine_use.rb +10 -0
  129. data/lib/earth/residence/clothes_machine_use/data_miner.rb +28 -0
  130. data/lib/earth/residence/data_miner.rb +8 -0
  131. data/lib/earth/residence/dishwasher_use.rb +10 -0
  132. data/lib/earth/residence/dishwasher_use/data_miner.rb +28 -0
  133. data/lib/earth/residence/residence_appliance.rb +16 -0
  134. data/lib/earth/residence/residence_appliance/data_miner.rb +20 -0
  135. data/lib/earth/residence/residence_class.rb +16 -0
  136. data/lib/earth/residence/residence_class/data_miner.rb +15 -0
  137. data/lib/earth/residence/residence_fuel_price.rb +18 -0
  138. data/lib/earth/residence/residence_fuel_price/data_miner.rb +200 -0
  139. data/lib/earth/residence/residence_fuel_type.rb +32 -0
  140. data/lib/earth/residence/residence_fuel_type/data_miner.rb +18 -0
  141. data/lib/earth/residence/residential_energy_consumption_survey_response.rb +39 -0
  142. data/lib/earth/residence/residential_energy_consumption_survey_response/data_miner.rb +283 -0
  143. data/spec/lib/earth_spec.rb +25 -0
  144. data/spec/spec_helper.rb +11 -0
  145. data/vendor/geokit-rails/CHANGELOG.rdoc +46 -0
  146. data/vendor/geokit-rails/MIT-LICENSE +20 -0
  147. data/vendor/geokit-rails/README.markdown +561 -0
  148. data/vendor/geokit-rails/Rakefile +18 -0
  149. data/vendor/geokit-rails/about.yml +9 -0
  150. data/vendor/geokit-rails/assets/api_keys_template +61 -0
  151. data/vendor/geokit-rails/init.rb +1 -0
  152. data/vendor/geokit-rails/install.rb +14 -0
  153. data/vendor/geokit-rails/lib/geokit-rails.rb +24 -0
  154. data/vendor/geokit-rails/lib/geokit-rails/acts_as_mappable.rb +456 -0
  155. data/vendor/geokit-rails/lib/geokit-rails/adapters/abstract.rb +31 -0
  156. data/vendor/geokit-rails/lib/geokit-rails/adapters/mysql.rb +22 -0
  157. data/vendor/geokit-rails/lib/geokit-rails/adapters/postgresql.rb +22 -0
  158. data/vendor/geokit-rails/lib/geokit-rails/adapters/sqlserver.rb +43 -0
  159. data/vendor/geokit-rails/lib/geokit-rails/defaults.rb +22 -0
  160. data/vendor/geokit-rails/lib/geokit-rails/geocoder_control.rb +16 -0
  161. data/vendor/geokit-rails/lib/geokit-rails/ip_geocode_lookup.rb +46 -0
  162. data/vendor/geokit-rails/test/acts_as_mappable_test.rb +474 -0
  163. data/vendor/geokit-rails/test/boot.rb +25 -0
  164. data/vendor/geokit-rails/test/database.yml +20 -0
  165. data/vendor/geokit-rails/test/fixtures/companies.yml +7 -0
  166. data/vendor/geokit-rails/test/fixtures/custom_locations.yml +54 -0
  167. data/vendor/geokit-rails/test/fixtures/locations.yml +54 -0
  168. data/vendor/geokit-rails/test/fixtures/mock_addresses.yml +17 -0
  169. data/vendor/geokit-rails/test/fixtures/mock_families.yml +2 -0
  170. data/vendor/geokit-rails/test/fixtures/mock_houses.yml +9 -0
  171. data/vendor/geokit-rails/test/fixtures/mock_organizations.yml +5 -0
  172. data/vendor/geokit-rails/test/fixtures/mock_people.yml +5 -0
  173. data/vendor/geokit-rails/test/fixtures/stores.yml +0 -0
  174. data/vendor/geokit-rails/test/ip_geocode_lookup_test.rb +77 -0
  175. data/vendor/geokit-rails/test/models/company.rb +3 -0
  176. data/vendor/geokit-rails/test/models/custom_location.rb +12 -0
  177. data/vendor/geokit-rails/test/models/location.rb +4 -0
  178. data/vendor/geokit-rails/test/models/mock_address.rb +4 -0
  179. data/vendor/geokit-rails/test/models/mock_family.rb +3 -0
  180. data/vendor/geokit-rails/test/models/mock_house.rb +3 -0
  181. data/vendor/geokit-rails/test/models/mock_organization.rb +4 -0
  182. data/vendor/geokit-rails/test/models/mock_person.rb +4 -0
  183. data/vendor/geokit-rails/test/models/store.rb +3 -0
  184. data/vendor/geokit-rails/test/schema.rb +60 -0
  185. data/vendor/geokit-rails/test/tasks.rake +31 -0
  186. data/vendor/geokit-rails/test/test_helper.rb +23 -0
  187. metadata +476 -0
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2007 Bill Eisenhauer & Andre Lewis
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,561 @@
1
+ ## INSTALLATION
2
+
3
+ Geokit consists of a Gem ([geokit-gem](http://github.com/andre/geokit-gem/tree/master)) and a Rails plugin ([geokit-rails](http://github.com/andre/geokit-rails/tree/master)).
4
+
5
+ #### 1. Install the Rails plugin:
6
+
7
+ cd [YOUR_RAILS_APP_ROOT]
8
+ script/plugin install git://github.com/andre/geokit-rails.git
9
+
10
+ #### 2. Add this line to your environment.rb
11
+ (inside the Rails::Initializer.run do |config| block)
12
+
13
+ config.gem "geokit"
14
+
15
+ This informs Rails of the gem dependency.
16
+
17
+ #### 3. Tell Rails to install the gem:
18
+
19
+ rake gems:install
20
+
21
+ And you're good to go! If you're running an older verion of Rails, just install the gem manually: `sudo gem install rails`
22
+
23
+ ## FEATURE SUMMARY
24
+
25
+ Geokit provides key functionality for location-oriented Rails applications:
26
+
27
+ - Distance calculations, for both flat and spherical environments. For example,
28
+ given the location of two points on the earth, you can calculate the miles/KM
29
+ between them.
30
+ - ActiveRecord distance-based finders. For example, you can find all the points
31
+ in your database within a 50-mile radius.
32
+ - IP-based location lookup utilizing hostip.info. Provide an IP address, and get
33
+ city name and latitude/longitude in return
34
+ - A before_filter helper to geocoder the user's location based on IP address,
35
+ and retain the location in a cookie.
36
+ - Geocoding from multiple providers. It provides a fail-over mechanism, in case
37
+ your input fails to geocode in one service. Geocoding is provided buy the Geokit
38
+ gem, which you must have installed
39
+
40
+ The goal of this plugin is to provide the common functionality for location-oriented
41
+ applications (geocoding, location lookup, distance calculation) in an easy-to-use
42
+ package.
43
+
44
+ ## A NOTE ON TERMINOLOGY
45
+
46
+ Throughout the code and API, latitude and longitude are referred to as lat
47
+ and lng. We've found over the long term the abbreviation saves lots of typing time.
48
+
49
+ ## LOCATION QUERIES
50
+
51
+ To get started, just specify an ActiveRecord class as `acts_as_mappale`:
52
+
53
+ class Location < ActiveRecord::Base
54
+ acts_as_mappable
55
+ end
56
+
57
+ There are some defaults you can override:
58
+
59
+ class Location < ActiveRecord::Base
60
+ acts_as_mappable :default_units => :miles,
61
+ :default_formula => :sphere,
62
+ :distance_field_name => :distance,
63
+ :lat_column_name => :lat,
64
+ :lng_column_name => :lng
65
+ end
66
+
67
+
68
+ The optional parameters are :units, :formula, and distance_field_name.
69
+ Values for :units can be :miles, :kms (kilometers), or :nms (nautical miles),
70
+ with :miles as the default. Values for :formula can be :sphere or :flat with
71
+ :sphere as the default. :sphere gives you Haversine calculations, while :flat
72
+ gives the Pythagoreum Theory. These defaults persist through out the plug-in.
73
+
74
+ The plug-in creates a calculated `distance` field on AR instances that have
75
+ been retrieved throw a Geokit location query. By default, these fields are
76
+ known as "distance" but this can be changed through the `:distance_field_name` key.
77
+
78
+ You can also define alternative column names for latitude and longitude using
79
+ the `:lat_column_name` and `:lng_column_name` keys. The defaults are 'lat' and
80
+ 'lng' respectively.
81
+
82
+ Once you've specified acts_as_mappable, a set of distance-based
83
+ finder methods are available:
84
+
85
+ Origin as a two-element array of latititude/longitude:
86
+
87
+ find(:all, :origin => [37.792,-122.393])
88
+
89
+ Origin as a geocodeable string:
90
+
91
+ find(:all, :origin => '100 Spear st, San Francisco, CA')
92
+
93
+ Origin as an object which responds to lat and lng methods,
94
+ or latitude and longitude methods, or whatever methods you have
95
+ specified for `lng_column_name` and `lat_column_name`:
96
+
97
+ find(:all, :origin=>my_store) # my_store.lat and my_store.lng methods exist
98
+
99
+ Often you will need to find within a certain distance. The prefered syntax is:
100
+
101
+ find(:all, :origin => @somewhere, :within => 5)
102
+
103
+ . . . however these syntaxes will also work:
104
+
105
+ find_within(5, :origin => @somewhere)
106
+ find(:all, :origin => @somewhere, :conditions => "distance < 5")
107
+
108
+ Note however that the third form should be avoided. With either of the first two,
109
+ Geokit automatically adds a bounding box to speed up the radial query in the database.
110
+ With the third form, it does not.
111
+
112
+ If you need to combine distance conditions with other conditions, you should do
113
+ so like this:
114
+
115
+ find(:all, :origin => @somewhere, :within => 5, :conditions=>['state=?',state])
116
+
117
+ If :origin is not provided in the finder call, the find method
118
+ works as normal. Further, the key is removed
119
+ from the :options hash prior to invoking the superclass behavior.
120
+
121
+ Other convenience methods work intuitively and are as follows:
122
+
123
+ find_within(distance, :origin => @somewhere)
124
+ find_beyond(distance, :origin => @somewhere)
125
+ find_closest(:origin => @somewhere)
126
+ find_farthest(:origin => @somewhere)
127
+
128
+ where the options respect the defaults, but can be overridden if
129
+ desired.
130
+
131
+ Lastly, if all that is desired is the raw SQL for distance
132
+ calculations, you can use the following:
133
+
134
+ distance_sql(origin, units=default_units, formula=default_formula)
135
+
136
+ Thereafter, you are free to use it in find_by_sql as you wish.
137
+
138
+ There are methods available to enable you to get the count based upon
139
+ the find condition that you have provided. These all work similarly to
140
+ the finders. So for instance:
141
+
142
+ count(:origin, :conditions => "distance < 5")
143
+ count_within(distance, :origin => @somewhere)
144
+ count_beyond(distance, :origin => @somewhere)
145
+
146
+ ## FINDING WITHIN A BOUNDING BOX
147
+
148
+ If you are displaying points on a map, you probably need to query for whatever falls within the rectangular bounds of the map:
149
+
150
+ Store.find :all, :bounds=>[sw_point,ne_point]
151
+
152
+ The input to :bounds can be array with the two points or a Bounds object. However you provide them, the order should always be the southwest corner, northeast corner of the rectangle. Typically, you will be getting the sw_point and ne_point from a map that is displayed on a web page.
153
+
154
+ If you need to calculate the bounding box from a point and radius, you can do that:
155
+
156
+ bounds=Bounds.from_point_and_radius(home,5)
157
+ Store.find :all, :bounds=>bounds
158
+
159
+ ## USING INCLUDES
160
+
161
+ You can use includes along with your distance finders:
162
+
163
+ stores=Store.find :all, :origin=>home, :include=>[:reviews,:cities] :within=>5, :order=>'distance'
164
+
165
+ *However*, ActiveRecord drops the calculated distance column when you use include. So, if you need to
166
+ use the distance column, you'll have to re-calculate it post-query in Ruby:
167
+
168
+ stores.sort_by_distance_from(home)
169
+
170
+ In this case, you may want to just use the bounding box
171
+ condition alone in your SQL (there's no use calculating the distance twice):
172
+
173
+ bounds=Bounds.from_point_and_radius(home,5)
174
+ stores=Store.find :all, :include=>[:reviews,:cities] :bounds=>bounds
175
+ stores.sort_by_distance_from(home)
176
+
177
+ ## USING :through
178
+
179
+ You can also specify a model as mappable "through" another associated model.
180
+ In other words, that associated model is the actual mappable model with
181
+ "lat" and "lng" attributes, but this "through" model can still utilize
182
+ all of the above find methods to search for records.
183
+
184
+ class Location < ActiveRecord::Base
185
+ belongs_to :locatable, :polymorphic => true
186
+ acts_as_mappable
187
+ end
188
+
189
+ class Company < ActiveRecord::Base
190
+ has_one :location, :as => :locatable # also works for belongs_to associations
191
+ acts_as_mappable :through => :location
192
+ end
193
+
194
+ Then you can still call:
195
+
196
+ Company.find_within(distance, :origin => @somewhere)
197
+
198
+ You can also give :through a hash if you location is nested deep. For example, given:
199
+
200
+ class House
201
+ acts_as_mappable
202
+ end
203
+
204
+ class Family
205
+ belongs_to :house
206
+ end
207
+
208
+ class Person
209
+ belongs_to :family
210
+ acts_as_mappable :through => { :family => :house }
211
+ end
212
+
213
+ Remember that the notes above about USING INCLUDES apply to the results from
214
+ this find, since an include is automatically used.
215
+
216
+ ## IP GEOCODING
217
+
218
+ You can obtain the location for an IP at any time using the geocoder
219
+ as in the following example:
220
+
221
+ location = IpGeocoder.geocode('12.215.42.19')
222
+
223
+ where Location is a GeoLoc instance containing the latitude,
224
+ longitude, city, state, and country code. Also, the success
225
+ value is true.
226
+
227
+ If the IP cannot be geocoded, a GeoLoc instance is returned with a
228
+ success value of false.
229
+
230
+ It should be noted that the IP address needs to be visible to the
231
+ Rails application. In other words, you need to ensure that the
232
+ requesting IP address is forwarded by any front-end servers that
233
+ are out in front of the Rails app. Otherwise, the IP will always
234
+ be that of the front-end server.
235
+
236
+ The Multi-Geocoder will also geocode IP addresses and provide
237
+ failover among multiple IP geocoders. Just pass in an IP address for the
238
+ parameter instead of a street address. Eg:
239
+
240
+ location = Geocoders::MultiGeocoder.geocode('12.215.42.19')
241
+
242
+ The MultiGeocoder class requires 2 configuration setting for the provider order.
243
+ Ordering is done through `Geokit::Geocoders::provider_order` and
244
+ `Geokit::Geocoders::ip_provider_order`, found in
245
+ `config/initializers/geokit_config.rb`. If you don't already have a
246
+ `geokit_config.rb` file, the plugin creates one when it is first installed.
247
+
248
+
249
+ ## IP GEOCODING HELPER
250
+
251
+ A class method called geocode_ip_address has been mixed into the
252
+ ActionController::Base. This enables before_filter style lookup of
253
+ the IP address. Since it is a filter, it can accept any of the
254
+ available filter options.
255
+
256
+ Usage is as below:
257
+
258
+ class LocationAwareController < ActionController::Base
259
+ geocode_ip_address
260
+ end
261
+
262
+ A first-time lookup will result in the GeoLoc class being stored
263
+ in the session as `:geo_location` as well as in a cookie called
264
+ `:geo_session`. Subsequent lookups will use the session value if it
265
+ exists or the cookie value if it doesn't exist. The last resort is
266
+ to make a call to the web service. Clients are free to manage the
267
+ cookie as they wish.
268
+
269
+ The intent of this feature is to be able to provide a good guess as
270
+ to a new visitor's location.
271
+
272
+ ## INTEGRATED FIND AND GEOCODING
273
+
274
+ Geocoding has been integrated with the finders enabling you to pass
275
+ a physical address or an IP address. This would look the following:
276
+
277
+ Location.find_farthest(:origin => '217.15.10.9')
278
+ Location.find_farthest(:origin => 'Irving, TX')
279
+
280
+ where the IP or physical address would be geocoded to a location and
281
+ then the resulting latitude and longitude coordinates would be used
282
+ in the find. This is not expected to be common usage, but it can be
283
+ done nevertheless.
284
+
285
+ ## ADDRESS GEOCODING
286
+
287
+ Geocoding is provided by the Geokit gem, which is required for this plugin.
288
+ See the top of this file for instructions on installing the Geokit gem.
289
+
290
+ Geokit can geocode addresses using multiple geocodeing web services.
291
+ Geokit supports services like Google, Yahoo, and Geocoder.us, and more --
292
+ see the Geokit gem API for a complete list.
293
+
294
+ These geocoder services are made available through the following classes:
295
+ GoogleGeocoder, YahooGeocoder, UsGeocoder, CaGeocoder, and GeonamesGeocoder.
296
+ Further, an additional geocoder class called MultiGeocoder incorporates an ordered failover
297
+ sequence to increase the probability of successful geocoding.
298
+
299
+ All classes are called using the following signature:
300
+
301
+ include Geokit::Geocoders
302
+ location = XxxGeocoder.geocode(address)
303
+
304
+ where you replace Xxx Geocoder with the appropriate class. A GeoLoc
305
+ instance is the result of the call. This class has a "success"
306
+ attribute which will be true if a successful geocoding occurred.
307
+ If successful, the lat and lng properties will be populated.
308
+
309
+ Geocoders are named with the convention NameGeocoder. This
310
+ naming convention enables Geocoder to auto-detect its sub-classes
311
+ in order to create methods called `name_geocoder(address)` so that
312
+ all geocoders can be called through the base class. This is done
313
+ purely for convenience; the individual geocoder classes are expected
314
+ to be used independently.
315
+
316
+ The MultiGeocoder class requires the configuration of a provider
317
+ order which dictates what order to use the various geocoders. Ordering
318
+ is done through `Geokit::Geocoders::provider_order`, found in
319
+ `config/initializers/geokit_config.rb`.
320
+
321
+ If you don't already have a `geokit_config.rb` file, the plugin creates one
322
+ when it is first installed.
323
+
324
+ Make sure your failover configuration matches the usage characteristics
325
+ of your application -- for example, if you routinely get bogus input to
326
+ geocode, your code will be much slower if you have to failover among
327
+ multiple geocoders before determining that the input was in fact bogus.
328
+
329
+ The Geocoder.geocode method returns a GeoLoc object. Basic usage:
330
+
331
+ loc=Geocoder.geocode('100 Spear St, San Francisco, CA')
332
+ if loc.success
333
+ puts loc.lat
334
+ puts loc.lng
335
+ puts loc.full_address
336
+ end
337
+
338
+ ## REVERSE GEOCODING
339
+
340
+ Currently, only the Google Geocoder supports reverse geocoding.
341
+ Pass the lat/lng as a string, array or LatLng instance:
342
+
343
+ res=Geokit::Geocoders::GoogleGeocoder.reverse_geocode "37.791821,-122.394679"
344
+ => #<Geokit::GeoLoc:0x558ed0 ...
345
+ res.full_address
346
+ "101-115 Main St, San Francisco, CA 94105, USA"
347
+
348
+ The address will usually appear as a range, as it does in the above example.
349
+
350
+
351
+ ## INTEGRATED FIND WITH ADDRESS GEOCODING
352
+
353
+ Just has you can pass an IP address directly into an ActiveRecord finder
354
+ as the origin, you can also pass a physical address as the origin:
355
+
356
+ Location.find_closest(:origin => '100 Spear st, San Francisco, CA')
357
+
358
+ where the physical address would be geocoded to a location and then the
359
+ resulting latitude and longitude coordinates would be used in the
360
+ find.
361
+
362
+ Note that if the address fails to geocode, the find method will raise an
363
+ ActiveRecord::GeocodeError you must be prepared to catch. Alternatively,
364
+ You can geocoder the address beforehand, and pass the resulting lat/lng
365
+ into the finder if successful.
366
+
367
+ ## Auto Geocoding
368
+
369
+ If your geocoding needs are simple, you can tell your model to automatically
370
+ geocode itself on create:
371
+
372
+ class Store < ActiveRecord::Base
373
+ acts_as_mappable :auto_geocode=>true
374
+ end
375
+
376
+ It takes two optional params:
377
+
378
+ class Store < ActiveRecord::Base
379
+ acts_as_mappable :auto_geocode=>{:field=>:address, :error_message=>'Could not geocode address'}
380
+ end
381
+
382
+ . . . which is equivilent to:
383
+
384
+ class Store << ActiveRecord::Base
385
+ acts_as_mappable
386
+ before_validation_on_create :geocode_address
387
+
388
+ private
389
+ def geocode_address
390
+ geo=Geokit::Geocoders::MultiGeocoder.geocode (address)
391
+ errors.add(:address, "Could not Geocode address") if !geo.success
392
+ self.lat, self.lng = geo.lat,geo.lng if geo.success
393
+ end
394
+ end
395
+
396
+ If you need any more complicated geocoding behavior for your model, you should roll your own
397
+ `before_validate` callback.
398
+
399
+
400
+ ## Distances, headings, endpoints, and midpoints
401
+
402
+ distance=home.distance_from(work, :units=>:miles)
403
+ heading=home.heading_to(work) # result is in degrees, 0 is north
404
+ endpoint=home.endpoint(90,2) # two miles due east
405
+ midpoing=home.midpoint_to(work)
406
+
407
+ ## Cool stuff you can do with bounds
408
+
409
+ bounds=Bounds.new(sw_point,ne_point)
410
+ bounds.contains?(home)
411
+ puts bounds.center
412
+
413
+
414
+ HOW TO . . .
415
+ =================================================================================
416
+
417
+ A few quick examples to get you started ....
418
+
419
+ ## How to install the Geokit Rails plugin
420
+ (See the very top of this file)
421
+
422
+ ## How to find all stores within a 10-mile radius of a given lat/lng
423
+ 1. ensure your stores table has lat and lng columns with numeric or float
424
+ datatypes to store your latitude/longitude
425
+
426
+ 3. use `acts_as_mappable` on your store model:
427
+
428
+ class Store < ActiveRecord::Base
429
+ acts_as_mappable
430
+ ...
431
+ end
432
+
433
+ 3. finders now have extra capabilities:
434
+
435
+ Store.find(:all, :origin =>[32.951613,-96.958444], :within=>10)
436
+
437
+ ## How to geocode an address
438
+
439
+ 1. configure your geocoder key(s) in `config/initializers/geokit_config.rb`
440
+
441
+ 2. also in `geokit_config.rb`, make sure that `Geokit::Geocoders::provider_order` reflects the
442
+ geocoder(s). If you only want to use one geocoder, there should
443
+ be only one symbol in the array. For example:
444
+
445
+ Geokit::Geocoders::provider_order=[:google]
446
+
447
+ 3. Test it out in script/console
448
+
449
+ include Geokit::Geocoders
450
+ res = MultiGeocoder.geocode('100 Spear St, San Francisco, CA')
451
+ puts res.lat
452
+ puts res.lng
453
+ puts res.full_address
454
+ ... etc. The return type is GeoLoc, see the API for
455
+ all the methods you can call on it.
456
+
457
+ ## How to find all stores within 10 miles of a given address
458
+
459
+ 1. as above, ensure your table has the lat/lng columns, and you've
460
+ applied `acts_as_mappable` to the Store model.
461
+
462
+ 2. configure and test out your geocoder, as above
463
+
464
+ 3. pass the address in under the :origin key
465
+
466
+ Store.find(:all, :origin=>'100 Spear st, San Francisco, CA',
467
+ :within=>10)
468
+
469
+ 4. you can also use a zipcode, or anything else that's geocodable:
470
+
471
+ Store.find(:all, :origin=>'94117',
472
+ :conditions=>'distance<10')
473
+
474
+ ## How to sort a query by distance from an origin
475
+
476
+ You now have access to a 'distance' column, and you can use it
477
+ as you would any other column. For example:
478
+ Store.find(:all, :origin=>'94117', :order=>'distance')
479
+
480
+ ## How to elements of an array according to distance from a common point
481
+
482
+ Usually, you can do your sorting in the database as part of your find call.
483
+ If you need to sort things post-query, you can do so:
484
+
485
+ stores=Store.find :all
486
+ stores.sort_by_distance_from(home)
487
+ puts stores.first.distance
488
+
489
+ Obviously, each of the items in the array must have a latitude/longitude so
490
+ they can be sorted by distance.
491
+
492
+ ## Database indexes
493
+
494
+ MySQL can't create indexes on a calculated field such as those Geokit uses to
495
+ calculate distance based on latitude/longitude values for a record. However,
496
+ indexing the lat and lng columns does improve Geokit distance calculation
497
+ performance since the lat and lng columns are used in a straight comparison
498
+ for distance calculation. Assuming a Page model that is incorporating the
499
+ Geokit plugin the migration would be as follows.
500
+
501
+ class AddIndexOPageLatAndLng < ActiveRecord::Migration
502
+
503
+ def self.up
504
+ add_index :pages, [:lat, :lng]
505
+ end
506
+
507
+ def self.down
508
+ remove_index :pages, [:lat, :lng]
509
+ end
510
+ end
511
+
512
+ ## Database Compatability
513
+
514
+ * Geokit works with MySQL (tested with version 5.0.41), PostgreSQL (tested with version 8.2.6) and Microsoft SQL Server (tested with 2000).
515
+ * Geokit does *not* work with SQLite, as it lacks the necessary geometry functions.
516
+ * Geokit is known to *not* work with Postgres versions under 8.1 -- it uses the least() funciton.
517
+
518
+
519
+ ## HIGH-LEVEL NOTES ON WHAT'S WHERE
520
+
521
+ `acts_as_mappable.rb`, as you'd expect, contains the ActsAsMappable
522
+ module which gets mixed into your models to provide the
523
+ location-based finder goodness.
524
+
525
+ `ip_geocode_lookup.rb` contains the before_filter helper method which
526
+ enables auto lookup of the requesting IP address.
527
+
528
+ ### The Geokit gem provides the building blocks of distance-based operations:
529
+
530
+ The Mappable module, which provides basic
531
+ distance calculation methods, i.e., calculating the distance
532
+ between two points.
533
+
534
+ The LatLng class is a simple container for latitude and longitude, but
535
+ it's made more powerful by mixing in the above-mentioned Mappable
536
+ module -- therefore, you can calculate easily the distance between two
537
+ LatLng ojbects with `distance = first.distance_to(other)`
538
+
539
+ GeoLoc represents an address or location which
540
+ has been geocoded. You can get the city, zipcode, street address, etc.
541
+ from a GeoLoc object. GeoLoc extends LatLng, so you also get lat/lng
542
+ AND the Mappable modeule goodness for free.
543
+
544
+ ## GOOGLE GROUP
545
+
546
+ Follow the Google Group for updates and discussion on Geokit: http://groups.google.com/group/geokit
547
+
548
+ ## IMPORTANT POST-INSTALLATION NOTES:
549
+
550
+ *1. The configuration file*: Geokit for Rails uses a configuration file in config/initializers.
551
+ You *must* add your own keys for the various geocoding services if you want to use geocoding.
552
+ If you need to refer to the original template again, see the `assets/api_keys_template` file.
553
+
554
+ *2. The gem dependency*: Geokit for Rails depends on the Geokit gem. Tell Rails about this
555
+ dependency in `config/environment.rb`, within the initializer block:
556
+ config.gem "geokit"
557
+
558
+ *If you're having trouble with dependencies ....*
559
+
560
+ Try installing the gem manually (sudo gem install geokit), then adding a `require 'geokit'` to the top of
561
+ `vendor/plugins/geokit-rails/init.rb` and/or `config/geokit_config.rb`.