what3words 2.2.0 → 3.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (11) hide show
  1. checksums.yaml +5 -5
  2. data/Gemfile +2 -0
  3. data/README.md +105 -70
  4. data/Rakefile +2 -0
  5. data/lib/what3words/api.rb +145 -76
  6. data/lib/what3words/version.rb +4 -1
  7. data/lib/what3words.rb +3 -1
  8. data/spec/lib/what3words/what3words_api_spec.rb +214 -67
  9. data/spec/spec_helper.rb +2 -0
  10. data/what3words.gemspec +13 -10
  11. metadata +13 -14
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: a4eb28d2cfd8ec8b5374248bbd07d5d4527e83c4
4
- data.tar.gz: 6b380be53a4cf8460aa7514e73012fb92111b37b
2
+ SHA256:
3
+ metadata.gz: a4a3183f709f4e5dedca75618f0a486d62f6e4d99f1e2d8709a1cc16837fefa8
4
+ data.tar.gz: 0700e12fafc5949b57f03bb750f2c01efc86a2df198eca6dc71b36472957f561
5
5
  SHA512:
6
- metadata.gz: 683d51f88b0b65dccdf86474c3e8c3259841cf204ac6b8f60f75c95bf63cf3a27db8097039cec2038fb96522604df7fcb2b5bd62359b46e23742930ccdee58de
7
- data.tar.gz: 93b0d139348a8a738a36ee4a00256a2723a92dfc290f1e31faf04dd8584157a3d9038227c9baa377edbf792af31b5d5f66918824430d069cae3537f940d6bda6
6
+ metadata.gz: 05f7639c6f66e11eb961629696cea9b6f79ea2d1df3ccf4eaf0fb061b2e247ce806d5cf9e0abe94f92ce04b3acefc83ee4179c91c54a1fc3f171fd37fa22c1d0
7
+ data.tar.gz: 1559cbe46257ab28cf6a97b08c52a4ffc47544e3e71a6215e845d36246b79845e08afcb783478a8ba08cf399cabc9e2abba995f9b410380cc2a34a2820a765da
data/Gemfile CHANGED
@@ -1,2 +1,4 @@
1
+ # frozen_string_literal: true
2
+
1
3
  source 'https://rubygems.org'
2
4
  gemspec
data/README.md CHANGED
@@ -1,14 +1,21 @@
1
1
  # <img src="https://what3words.com/assets/images/w3w_square_red.png" width="32" height="32" alt="what3words">&nbsp;what3words Ruby wrapper
2
- ![Build Status](https://travis-ci.org/what3words/w3w-ruby-wrapper.svg?branch=master)
3
2
 
4
- Use the what3words API in your Ruby app (see http://developer.what3words.com/api)
3
+ [![Build Status](https://travis-ci.org/what3words/w3w-ruby-wrapper.svg?branch=master)](https://travis-ci.org/what3words/w3w-ruby-wrapper)
4
+
5
+ The Ruby wrapper is useful for Ruby developers who wish to seamlessly integrate the [what3words Public API](https://developer.what3words.com/public-api) into their Ruby applications, without the hassle of having to manage the low level API calls themselves.
6
+
7
+ The what3words API is a fast, simple interface which allows you to convert 3 word addresses such as `///index.home.raft` to latitude and longitude coordinates such as `-0.203586, 51.521251` and vice versa. It features a powerful autosuggest function, which can validate and autocorrect user input and limit it to certain geographic areas (this powers the search box on our map site). It allows you to request a section of the what3words grid (which can be requested as GeoJSON for easy display on online maps), and to request the list of all languages supported by what3words. For advanced users, autosuggest can be used to post-process voice output.
8
+
9
+ All coordinates are latitude,longitude pairs in standard `WGS-84` (as commonly used worldwide in GPS systems). All latitudes must be in the range of `-90 to 90 (inclusive)`.
5
10
 
6
11
  ## Installation
7
12
 
8
- Add this line to your application's Gemfile:
13
+ The library is available through [RubyGems](https://rubygems.org/gems/what3words).
9
14
 
10
- ```shell
11
- gem 'what3words', '~> 2.1'
15
+ You can simply add this line to your application's Gemfile:
16
+
17
+ ```
18
+ gem 'what3words', '~> 3.0'
12
19
  ```
13
20
 
14
21
  And then execute:
@@ -25,10 +32,9 @@ Or install it yourself as:
25
32
 
26
33
  ## Usage
27
34
 
28
- Sign up for an API key at http://developer.what3words.com
35
+ Sign up for an API key at [https://developer.what3words.com](https://developer.what3words.com)
29
36
 
30
- See https://docs.what3words.com/api/v2/ for all parameters that can be
31
- passed to the API calls
37
+ See [https://developer.what3words.com/public-api/docs](https://developer.what3words.com/public-api/docs) for all parameters that can be passed to the API calls.
32
38
 
33
39
  If not using Bundler, require it:
34
40
 
@@ -42,47 +48,47 @@ Then:
42
48
  what3words = What3Words::API.new(:key => "YOURAPIKEY")
43
49
  ```
44
50
 
45
- Forward Geocode : convert a 3 word address into GPS coordinates (WGS-84)
51
+ Convert to Coordinates: convert a 3 word address into GPS coordinates (WGS84)
46
52
 
47
53
  ```ruby
48
- what3words.forward 'prom.cape.pump'
49
- # => {:crs=>{:properties=>{:type=>"ogcwkt", :href=>"http://spatialreference.org/ref/epsg/4326/ogcwkt/"}, :type=>"link"}, :bounds=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :words=>"prom.cape.pump", :map=>"http://w3w.co/prom.cape.pump", :language=>"en", :geometry=>{:lng=>-0.195405, :lat=>51.484463}, :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
54
+ what3words.convert_to_coordinates 'prom.cape.pump'
55
+ # => {:country=>"GB", :square=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :nearestPlace=>"Kensington, London", :coordinates=>{:lng=>-0.195405, :lat=>51.484463}, :words=>"prom.cape.pump", :language=>"en", :map=>"https://w3w.co/prom.cape.pump"}
50
56
  ```
51
57
 
52
58
  ## API
53
- ### Forward Geocoding
54
- Convert a 3 word address into GPS coordinates and return 3 words for the same position in a different language
59
+ ### Convert to Coordinates
60
+ Convert a 3 word address into GPS coordinates and return 3 words for the same position.
55
61
 
56
62
  ```ruby
57
- what3words.forward "prom.cape.pump", :lang => "fr"
58
- # => {:crs=>{:properties=>{:type=>"ogcwkt", :href=>"http://spatialreference.org/ref/epsg/4326/ogcwkt/"}, :type=>"link"}, :bounds=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :words=>"concevoir.époque.amasser", :map=>"http://w3w.co/concevoir.époque.amasser", :language=>"fr", :geometry=>{:lng=>-0.195405, :lat=>51.484463}, :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
63
+ what3words.convert_to_coordinates "prom.cape.pump"
64
+ # => {:country=>"GB", :square=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :nearestPlace=>"Kensington, London", :coordinates=>{:lng=>-0.195405, :lat=>51.484463}, :words=>"prom.cape.pump", :language=>"en", :map=>"https://w3w.co/prom.cape.pump"}
59
65
  ```
60
- Supported keyword params for `forward` call:
66
+ Supported keyword params for `convert_to_coordinates` call:
61
67
 
62
- * `lang` (defaults to language of 3 words) - optional language code (only use this if you want to return 3 words in a different language to the language submitted)
63
- * `format` Return data format type; can be one of json (the default), geojson or xml
64
- * `display` Return display type; can be one of full (the default) or terse
68
+ * `words` A 3 word address as a string
69
+ * `format` Return data format type. It can be one of json (the default) or geojson
65
70
 
66
- ### Reverse Geocoding
67
- Reverse Geocode : Convert position(latitude) information to a 3 word address
71
+
72
+ ### Convert to 3WA
73
+ Convert position information, latitude and longitude coordinates, into a 3 word address.
68
74
 
69
75
  ```ruby
70
- what3words.reverse [51.484463, -0.195405]
71
- # => {:crs=>{:properties=>{:type=>"ogcwkt", :href=>"http://spatialreference.org/ref/epsg/4326/ogcwkt/"}, :type=>"link"}, :bounds=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :words=>"prom.cape.pump", :map=>"http://w3w.co/prom.cape.pump", :language=>"en", :geometry=>{:lng=>-0.195405, :lat=>51.484463}, :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
72
- ```
76
+ what3words.convert_to_3wa [29.567041, 106.587875]
77
+ # => {:country=>"CN", :square=>{:southwest=>{:lng=>106.58786, :lat=>29.567028}, :northeast=>{:lng=>106.587891, :lat=>29.567055}}, :nearestPlace=>"Chongqing", :coordinates=>{:lng=>106.587875, :lat=>29.567041}, :words=>"disclose.strain.redefined", :language=>"en", :map=>"https://w3w.co/disclose.strain.redefined"}
78
+ ```
73
79
 
74
80
  Convert position information to a 3 word address in a specific language
75
81
 
76
82
  ```ruby
77
- what3words.reverse [51.484463, -0.195405], :lang => :fr
78
- # => {:crs=>{:properties=>{:type=>"ogcwkt", :href=>"http://spatialreference.org/ref/epsg/4326/ogcwkt/"}, :type=>"link"}, :bounds=>{:southwest=>{:lng=>-0.195426, :lat=>51.484449}, :northeast=>{:lng=>-0.195383, :lat=>51.484476}}, :words=>"concevoir.époque.amasser", :map=>"http://w3w.co/concevoir.époque.amasser", :language=>"fr", :geometry=>{:lng=>-0.195405, :lat=>51.484463}, :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
83
+ what3words.convert_to_3wa [29.567041, 106.587875], language: 'fr'
84
+ # => :country=>"CN", :square=>{:southwest=>{:lng=>106.58786, :lat=>29.567028}, :northeast=>{:lng=>106.587891, :lat=>29.567055}}, :nearestPlace=>"Chongqing", :coordinates=>{:lng=>106.587875, :lat=>29.567041}, :words=>"courgette.rabotons.infrason", :language=>"fr", :map=>"https://w3w.co/courgette.rabotons.infrason"}
79
85
  ```
80
86
 
81
- Supported keyword params for `reverse` call:
87
+ Supported keyword params for `convert_to_3wa` call:
82
88
 
83
- * `lang` (defaults to en) - optional language code
84
- * `format` Return data format type; can be one of json (the default), geojson or xml
85
- * `display` Return display type; can be one of full (the default) or terse
89
+ * `coordinates` The coordinates of the location to convert to 3 word address
90
+ * `language` (defaults to en) - A supported 3 word address language as an ISO 639-1 2 letter code
91
+ * `format` Return data format type. It can be one of json (the default) or geojson
86
92
 
87
93
  ### Autosuggest
88
94
  Returns a list of 3 word addresses based on user input and other parameters.
@@ -95,92 +101,115 @@ This resource provides corrections for the following types of input error:
95
101
 
96
102
  The autosuggest resource determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. This resource can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.
97
103
 
98
- *Single and Multilingual Variants*
104
+ See [https://developer.what3words.com/public-api/docs#autosuggest](https://developer.what3words.com/public-api/docs#autosuggest) for detailed information
99
105
 
100
- AutoSuggest is provided via 2 variant resources; single language and multilingual.
106
+ Gets suggestions in french for this address:
101
107
 
102
- The single language `autosuggest` method requires a language to be specified.
108
+ ```ruby
109
+ what3words.autosuggest 'trop.caler.perdre', language: 'fr'
110
+ # => {:suggestions=>[{:country=>"FR", :nearestPlace=>"Saint-Lary-Soulan, Hautes-Pyrénées", :words=>"trier.caler.perdre", :rank=>1, :language=>"fr"}, {:country=>"ET", :nearestPlace=>"Asbe Teferi, Oromiya", :words=>"trôler.caler.perdre", :rank=>2, :language=>"fr"}, {:country=>"CN", :nearestPlace=>"Ulanhot, Inner Mongolia", :words=>"froc.caler.perdre", :rank=>3, :language=>"fr"}]}
111
+ ```
103
112
 
104
- The multilingual `autosuggest_ml` method requires a language to be specified. This will ensure that the autosuggest-ml resource will look for suggestions in this language, in addition to any other languages that yield relevant suggestions.
113
+ Gets suggestions for a different number of suggestions, i.e. 10 for this address:
105
114
 
106
- see https://docs.what3words.com/api/v2/#autosuggest for detailed information
115
+ ```ruby
116
+ what3words.autosuggest 'disclose.strain.redefin', language: 'en', 'n-results': 10
117
+ # => {:suggestions=>[{:country=>"SO", :nearestPlace=>"Jamaame, Lower Juba", :words=>"disclose.strain.redefine", :rank=>1, :language=>"en"}, {:country=>"ZW", :nearestPlace=>"Mutoko, Mashonaland East", :words=>"discloses.strain.redefine", :rank=>2, :language=>"en"}, {:country=>"MM", :nearestPlace=>"Mogok, Mandalay", :words=>"disclose.strains.redefine", :rank=>3, :language=>"en"}, {:country=>"CN", :nearestPlace=>"Chongqing", :words=>"disclose.strain.redefined", :rank=>4, :language=>"en"}, {:country=>"ZM", :nearestPlace=>"Binga, Matabeleland North", :words=>"disclosing.strain.redefine", :rank=>5, :language=>"en"}, {:country=>"XH", :nearestPlace=>"Leh, Ladakh", :words=>"disclose.straining.redefine", :rank=>6, :language=>"en"}, {:country=>"US", :nearestPlace=>"Kamas, Utah", :words=>"disclose.strain.redefining", :rank=>7, :language=>"en"}, {:country=>"GN", :nearestPlace=>"Boké", :words=>"disclose.strained.redefine", :rank=>8, :language=>"en"}, {:country=>"BO", :nearestPlace=>"Pailón, Santa Cruz", :words=>"discloses.strains.redefine", :rank=>9, :language=>"en"}, {:country=>"US", :nearestPlace=>"McGrath, Alaska", :words=>"discloses.strain.redefined", :rank=>10, :language=>"en"}]}
118
+ ```
107
119
 
108
- Gets suggestions in italian for this address
120
+ Gets suggestions for a different number of focus results for this address:
109
121
 
110
122
  ```ruby
111
- what3words.autosuggest "trovò.calore.perder", "it"
112
- # => {:suggestions=>[{:score=>12, :country=>"ma", :words=>"trovò.calore.perdere", :rank=>1, :geometry=>{:lng=>-6.665638, :lat=>34.318065}, :place=>"Kenitra, Gharb-Chrarda-Beni Hssen"}, {:score=>12, :country=>"ca", :words=>"trovò.calore.perderò", :rank=>2, :geometry=>{:lng=>-65.036149, :lat=>45.846472}, :place=>"Salisbury, New Brunswick"}, {:score=>17, :country=>"ve", :words=>"trovò.calore.prede", :rank=>3, :geometry=>{:lng=>-70.280645, :lat=>7.24527}, :place=>"Guasdualito, Apure"}], :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
123
+ what3words.autosuggest 'disclose.strain.redefin', language: 'en', 'n-focus-results': 3
124
+ # => {:suggestions=>[{:country=>"SO", :nearestPlace=>"Jamaame, Lower Juba", :words=>"disclose.strain.redefine", :rank=>1, :language=>"en"}, {:country=>"ZW", :nearestPlace=>"Mutoko, Mashonaland East", :words=>"discloses.strain.redefine", :rank=>2, :language=>"en"}, {:country=>"MM", :nearestPlace=>"Mogok, Mandalay", :words=>"disclose.strains.redefine", :rank=>3, :language=>"en"}]}
113
125
  ```
114
126
 
127
+ Gets suggestions for a voice input type mode, i.e. generic-voice, for this address:
128
+
115
129
  ```ruby
116
- what3words.autosuggest_ml "trovò.calore.perder", "it"
130
+ what3words.autosuggest 'fun with code', 'input-type': 'generic-voice', language: 'en'
131
+ # => {:suggestions=>[{:country=>"US", :nearestPlace=>"Homer, Alaska", :words=>"fund.with.code", :rank=>1, :language=>"en"}, {:country=>"AU", :nearestPlace=>"Kumpupintil, Western Australia", :words=>"funk.with.code", :rank=>2, :language=>"en"}, {:country=>"US", :nearestPlace=>"Charleston, West Virginia", :words=>"fund.with.cove", :rank=>3, :language=>"en"}]}
117
132
  ```
118
133
 
119
- Supported keyword params for `autosuggest` and `autosuggest_ml` call:
120
- * `format` Return data format type; can be one of json (the default), geojson or xml
121
- * `display` Return display type; can be one of full (the default) or terse
122
-
123
- ### Standardblend
124
- Returns a blend of the three most relevant 3 word address candidates for a given location, based on a full or partial 3 word address.
134
+ Gets suggestions for a restricted area by clipping to conutry for this address:
125
135
 
126
- The specified 3 word address may either be a full 3 word address or a partial 3 word address containing the first 2 words in full and at least 1 character of the 3rd word. The standardblend resource provides the search logic that powers the search box on map.what3words.com and in the what3words mobile apps.
136
+ ```ruby
137
+ what3words.autosuggest 'disclose.strain.redefin', 'clip-to-country': 'GB,BE'
138
+ # => {:suggestions=>[{:country=>"GB", :nearestPlace=>"Nether Stowey, Somerset", :words=>"disclose.retrain.redefined", :rank=>1, :language=>"en"}, {:country=>"BE", :nearestPlace=>"Zemst, Flanders", :words=>"disclose.strain.reckon", :rank=>2, :language=>"en"}, {:country=>"GB", :nearestPlace=>"Waddington, Lincolnshire", :words=>"discloses.trains.redefined", :rank=>3, :language=>"en"}]}
139
+ ```
127
140
 
128
- *Single and Multilingual Variants*
141
+ Gets suggestions for a restricted area by clipping to a bounding-box for this address:
129
142
 
130
- AutoSuggest is provided via 2 variant resources; single language and multilingual.
143
+ ```ruby
144
+ what3words.autosuggest 'disclose.strain.redefin', 'clip-to-bounding-box': [51.521, -0.343, 52.6, 2.3324]
145
+ # => {:suggestions=>[{:country=>"GB", :nearestPlace=>"Saxmundham, Suffolk", :words=>"discloses.strain.reddish", :rank=>1, :language=>"en"}]}
146
+ ```
131
147
 
132
- The single language `standardblend` method requires a language to be specified.
133
148
 
134
- The multilingual `standardblend_ml` method requires a language to be specified. This will ensure that the standardblend-ml resource will look for suggestions in this language, in addition to any other languages that yield relevant suggestions.
149
+ Gets suggestions for a restricted area by clipping to a circle in km for this address:
135
150
 
136
- see https://docs.what3words.com/api/v2/#standardblend for detailed information
151
+ ```ruby
152
+ what3words.autosuggest 'disclose.strain.redefin', 'clip-to-circle': [51.521, -0.343, 142]
153
+ # => {:suggestions=>[{:country=>"GB", :nearestPlace=>"Market Harborough, Leicestershire", :words=>"discloses.strain.reduce", :rank=>1, :language=>"en"}]}
154
+ ```
137
155
 
138
- Gets blends in italian for this address
156
+ Gets suggestions for a restricted area by clipping to a polygon for this address:
139
157
 
140
158
  ```ruby
141
- what3words.standardblend "trovò.calore.perder", "it"
142
- # => {:blends=>[{:country=>"ma", :words=>"trovò.calore.perdere", :rank=>1, :language=>"it", :geometry=>{:lng=>-6.665638, :lat=>34.318065}, :place=>"Kenitra, Gharb-Chrarda-Beni Hssen"}, {:country=>"ca", :words=>"trovò.calore.perderò", :rank=>2, :language=>"it", :geometry=>{:lng=>-65.036149, :lat=>45.846472}, :place=>"Salisbury, New Brunswick"}, {:country=>"ve", :words=>"trovò.calore.prede", :rank=>3, :language=>"it", :geometry=>{:lng=>-70.280645, :lat=>7.24527}, :place=>"Guasdualito, Apure"}], :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
159
+ what3words.autosuggest 'disclose.strain.redefin', 'clip-to-polygon': [51.521, -0.343, 52.6, 2.3324, 54.234, 8.343, 51.521, -0.343]
160
+ # => {:suggestions=>[{:country=>"GB", :nearestPlace=>"Saxmundham, Suffolk", :words=>"discloses.strain.reddish", :rank=>1, :language=>"en"}]}
143
161
  ```
144
162
 
163
+ Gets suggestions for a restricted area by clipping to a polygon for this address:
164
+
145
165
  ```ruby
146
- what3words.standardblend_ml "trovò.calore.perder", "it"
166
+ what3words.w3w.autosuggest 'disclose.strain.redefin', 'prefer-land': false, 'n-results': 10
167
+ # => {:suggestions=>[{:country=>"SO", :nearestPlace=>"Jamaame, Lower Juba", :words=>"disclose.strain.redefine", :rank=>1, :language=>"en"}, {:country=>"ZW", :nearestPlace=>"Mutoko, Mashonaland East", :words=>"discloses.strain.redefine", :rank=>2, :language=>"en"}, {:country=>"MM", :nearestPlace=>"Mogok, Mandalay", :words=>"disclose.strains.redefine", :rank=>3, :language=>"en"}, {:country=>"CN", :nearestPlace=>"Chongqing", :words=>"disclose.strain.redefined", :rank=>4, :language=>"en"}, {:country=>"ZM", :nearestPlace=>"Binga, Matabeleland North", :words=>"disclosing.strain.redefine", :rank=>5, :language=>"en"}, {:country=>"XH", :nearestPlace=>"Leh, Ladakh", :words=>"disclose.straining.redefine", :rank=>6, :language=>"en"}, {:country=>"US", :nearestPlace=>"Kamas, Utah", :words=>"disclose.strain.redefining", :rank=>7, :language=>"en"}, {:country=>"GN", :nearestPlace=>"Boké", :words=>"disclose.strained.redefine", :rank=>8, :language=>"en"}, {:country=>"BO", :nearestPlace=>"Pailón, Santa Cruz", :words=>"discloses.strains.redefine", :rank=>9, :language=>"en"}, {:country=>"US", :nearestPlace=>"McGrath, Alaska", :words=>"discloses.strain.redefined", :rank=>10, :language=>"en"}]}
147
168
  ```
148
169
 
149
- Supported keyword params for `standardblend` and `standardblend_ml` call:
150
- * `format` Return data format type; can be one of json (the default), geojson or xml
151
- * `display` Return display type; can be one of full (the default) or terse
170
+ Supported keyword params for `autosuggest` call:
171
+ * `input` The full or partial 3 word address to obtain suggestions for. At minimum this must be the first two complete words plus at least one character from the third word.
172
+ * `language` A supported 3 word address language as an ISO 639-1 2 letter code. This setting is on by default. Use false to disable this setting and receive more suggestions in the sea.
173
+ * `n_results` The number of AutoSuggest results to return. A maximum of 100 results can be specified, if a number greater than this is requested, this will be truncated to the maximum. The default is 3.
174
+ * `n_focus_results` Specifies the number of results (must be <= n_results) within the results set which will have a focus. Defaults to n_results. This allows you to run autosuggest with a mix of focussed and unfocussed results, to give you a "blend" of the two.
175
+ * `clip-to-country` Restricts autosuggest to only return results inside the countries specified by comma-separated list of uppercase ISO 3166-1 alpha-2 country codes (for example, to restrict to Belgium and the UK, use clip_to_country="GB,BE").
176
+ * `clip-to-bounding-box` Restrict autosuggest results to a bounding box, specified by coordinates.
177
+ * `clip-to-circle` Restrict autosuggest results to a circle, specified by the center of the circle, latitude and longitude, and a distance in kilometres which represents the radius. For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179.
178
+ * `clip-to-polygon` Restrict autosuggest results to a polygon, specified by a list of coordinates. The polygon should be closed, i.e. the first element should be repeated as the last element; also the list should contain at least 4 entries. The API is currently limited to accepting up to 25 pairs.
179
+ * `input-type` For power users, used to specify voice input mode. Can be text (default), vocon-hybrid, nmdp-asr or generic-voice.
180
+ * `prefer-land` Makes autosuggest prefer results on land to those in the sea.
152
181
 
153
182
  ### Grid
154
183
  Returns a section of the 3m x 3m what3words grid for a given area.
155
184
 
156
- see https://docs.what3words.com/api/v2/#grid for detailed information
185
+ See [https://developer.what3words.com/public-api/docs#grid-section](https://developer.what3words.com/public-api/docs#grid-section) for detailed information.
157
186
 
158
- Gets grid for these bounding box northeast 52.208867,0.117540, southwest 52.207988,0.116126
187
+ Gets grid for these bounding box northeast 52.208867,0.117540,52.207988,0.116126.
159
188
 
160
189
  ```ruby
161
- what3words.grid "52.208867,0.117540,52.207988,0.116126"
162
- # => {:lines=>[{:start=>{:lng=>0.11612600000001, :lat=>52.208009918068}, :end=>{:lng=>0.11753999999999, :lat=>52.208009918068}}, ___...___ , :end=>{:lng=>0.11752023935234, :lat=>52.208867}}], :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
190
+ what3words.grid_section '52.208867,0.117540,52.207988,0.116126'
191
+ # => {:lines=>[{:start=>{:lng=>0.116126, :lat=>52.20801}, :end=>{:lng=>0.11754, :lat=>52.20801}}, {:start=>{:lng=>0.116126, :lat=>52.208037}, :end=>{:lng=>0.11754, :lat=>52.208037}}, {:start=>{:lng=>0.116126, :lat=>52.208064}, :end=>{:lng=>0.11754, :lat=>52.208064}}, ___...___ ]}
163
192
  ```
164
193
 
165
- Supported keyword params for `grid` call:
166
- * `format` Return data format type; can be one of json (the default), geojson or xml
167
- * `display` Return display type; can be one of full (the default) or terse
194
+ Supported keyword params for `grid_section` call:
195
+ * `bounding-box` The bounding box is specified by the northeast and southwest corner coordinates, for which the grid should be returned
196
+ * `format` Return data format type. It can be one of json (the default) or geojson
168
197
 
169
198
  ### Get Languages
170
- Get list of available 3 word languages
199
+ Retrieve a list of available 3 word languages.
171
200
 
172
201
  ```ruby
173
- what3words.languages
174
- # => {{:languages=>[{:code=>"de", :name=>"German", :native_name=>"Deutsch"}, {:code=>"mn", :name=>"Mongolian", :native_name=>"Mонгол"}, {:code=>"fi", :name=>"Finnish", :native_name=>"Suomi"}, {:code=>"ru", :name=>"Russian", :native_name=>"Русский"}, {:code=>"sv", :name=>"Swedish", :native_name=>"Svenska"}, {:code=>"pt", :name=>"Portuguese", :native_name=>"Português"}, {:code=>"sw", :name=>"Swahili", :native_name=>"Kiswahili"}, {:code=>"en", :name=>"English", :native_name=>"English"}, {:code=>"it", :name=>"Italian", :native_name=>"Italiano"}, {:code=>"fr", :name=>"French", :native_name=>"Français"}, {:code=>"es", :name=>"Spanish", :native_name=>"Español"}, {:code=>"ar", :name=>"Arabic", :native_name=>"العربية"}, {:code=>"pl", :name=>"Polish", :native_name=>"Polski"}, {:code=>"tr", :name=>"Turkish", :native_name=>"Türkçe"}], :status=>{:status=>200, :reason=>"OK"}, :thanks=>"Thanks from all of us at index.home.raft for using a what3words API"}
202
+ what3words.available_languages
203
+ # => {:languages=>[{:nativeName=>"Deutsch", :code=>"de", :name=>"German"}, {:nativeName=>"हिन्दी", :code=>"hi", :name=>"Hindi"}, {:nativeName=>"Português", :code=>"pt", :name=>"Portuguese"}, {:nativeName=>"Magyar", :code=>"hu", :name=>"Hungarian"}, {:nativeName=>"Українська", :code=>"uk", :name=>"Ukrainian"}, {:nativeName=>"Bahasa Indonesia", :code=>"id", :name=>"Bahasa Indonesia"}, {:nativeName=>"اردو", :code=>"ur", :name=>"Urdu"}, ___...___]}
175
204
  ```
176
205
 
177
- See http://developer.what3words.com for the original API call documentation
206
+ See [https://developer.what3words.com/public-api/docs#available-languages](https://developer.what3words.com/public-api/docs#available-languages) for the original API call documentation.
178
207
 
179
208
  ## Testing
180
209
 
181
210
  * Prerequisite : we are using [bundler](https://rubygems.org/gems/bundler) `$ gem install bundler`
182
211
 
183
- * W3W-API-KEY : For safe storage of your API key on your computer, you can define that API key using your system’s environment variables.
212
+ * W3W-API-KEY: For safe storage of your API key on your computer, you can define that API key using your system’s environment variables.
184
213
  ```bash
185
214
  $ export W3W_API_KEY=<Secret API Key>
186
215
  ```
@@ -190,6 +219,11 @@ $ export W3W_API_KEY=<Secret API Key>
190
219
  1. `$ bundle update`
191
220
  1. `$ rake rubocop spec`
192
221
 
222
+ To run the tests, type on your terminal:
223
+ ```bash
224
+ $ bundle exec rspec
225
+ ```
226
+
193
227
  ## Issues
194
228
 
195
229
  Find a bug or want to request a new feature? Please let us know by submitting an issue.
@@ -206,6 +240,7 @@ Anyone and everyone is welcome to contribute.
206
240
 
207
241
  # Revision History
208
242
 
243
+ * `v3.0.0` 12/05/22 - Update endpoints and tests to API v3, added HTTP headers
209
244
  * `v2.2.0` 03/01/18 - Enforce Ruby 2.4 Support - Thanks to PR from Dimitrios Zorbas [@Zorbash](https://github.com/zorbash)
210
245
  * `v2.1.1` 22/05/17 - Update gemspec to use rubocop 0.48.1, and fixes spec accordingly
211
246
  * `v2.1.0` 28/03/17 - Added multilingual version of `autosuggest` and `standardblend`
data/Rakefile CHANGED
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'bundler/gem_tasks'
2
4
 
3
5
  begin
data/lib/what3words/api.rb CHANGED
@@ -1,153 +1,223 @@
1
- # encoding: utf-8
1
+ # frozen_string_literal: true
2
2
 
3
3
  require 'rest-client'
4
+ require File.expand_path('../version', __FILE__)
5
+ require 'what3words/version'
4
6
 
5
7
  module What3Words
6
- # Document the responsibility of the class
7
- #
8
+ # What3Words v3 API wrapper
8
9
  class API # rubocop:disable Metrics/ClassLength
10
+ # This class provides an interface to the what3words API
11
+ # at https://developer.what3words.com/public-api/docs
9
12
  class Error < RuntimeError; end
10
13
  class ResponseError < Error; end
11
14
  class WordError < Error; end
12
15
 
13
- REGEX_3_WORD_ADDRESS = /^\p{L}+\.\p{L}+\.\p{L}+$/u
14
- REGEX_STRICT = /^\p{L}{3,}+\.\p{L}{3,}+\.\p{L}{3,}+$/u
16
+ REGEX_3_WORD_ADDRESS = /^\p{L}+\.\p{L}+\.\p{L}+$/u.freeze
17
+ REGEX_STRICT = /^\p{L}{3,}+\.\p{L}{3,}+\.\p{L}{3,}+$/u.freeze
15
18
 
16
- BASE_URL = 'https://api.what3words.com/v2/'.freeze
19
+ BASE_URL = 'https://api.what3words.com/v3/'
17
20
 
18
21
  ENDPOINTS = {
19
- forward: 'forward',
20
- reverse: 'reverse',
21
- languages: 'languages',
22
+ convert_to_coordinates: 'convert-to-coordinates',
23
+ convert_to_3wa: 'convert-to-3wa',
24
+ available_languages: 'available-languages',
22
25
  autosuggest: 'autosuggest',
23
- standardblend: 'standardblend',
24
- autosuggest_ml: 'autosuggest-ml',
25
- standardblend_ml: 'standardblend-ml',
26
- grid: 'grid'
26
+ grid_section: 'grid-section'
27
27
  }.freeze
28
28
 
29
+ WRAPPER_VERSION = What3Words::VERSION
30
+
29
31
  def initialize(params)
30
32
  @key = params.fetch(:key)
31
33
  end
32
34
 
33
35
  attr_reader :key
34
36
 
35
- def forward(words, params = {})
37
+ def convert_to_coordinates(words, params = {})
38
+ # Take a 3 word address and turn it into a pair of coordinates.
39
+ # @:param string words: A 3 word address as a string
40
+ # @:param string format: Return data format type; can be one of json (the default), geojson
41
+ # API Reference: https://docs.what3words.com/api/v3/#convert-to-coordinates
36
42
  words_string = get_words_string words
37
- request_params = assemble_forward_request_params(words_string, params)
38
- response = request! :forward, request_params
43
+ request_params = assemble_convert_to_coordinates_request_params(words_string, params)
44
+ response = request! :convert_to_coordinates, request_params
39
45
  response
40
46
  end
41
47
 
42
- def reverse(position, params = {})
43
- request_params = assemble_reverse_request_params(position, params)
44
- response = request! :reverse, request_params
48
+ def convert_to_3wa(position, params = {})
49
+ # Take latitude and longitude coordinates and turn them into a 3 word address.
50
+ # @:param coordinates: the coordinates of the location to convert to 3 word address
51
+ # @:param string format: Return data format type; can be one of json (the default), geojson
52
+ # @:param string language: A supported 3 word address language as an ISO 639-1 2 letter code.
53
+ # API Reference: https://docs.what3words.com/api/v3/#convert-to-3wa
54
+ request_params = assemble_convert_to_3wa_request_params(position, params)
55
+ response = request! :convert_to_3wa, request_params
45
56
  response
46
57
  end
47
58
 
48
- def grid(bbox, params = {})
59
+ def grid_section(bbox, params = {})
60
+ # Returns a section of the 3m x 3m what3words grid for a given area.
61
+ # @:param bounding-box: Bounding box, specified by the northeast and southwest corner coordinates,
62
+ # for which the grid should be returned.
63
+ # @:param string format: Return data format type; can be one of json (the default), geojson
64
+ # API Reference: https://docs.what3words.com/api/v3/#grid-section
49
65
  request_params = assemble_grid_request_params(bbox, params)
50
- response = request! :grid, request_params
66
+ response = request! :grid_section, request_params
51
67
  response
52
68
  end
53
69
 
54
- def languages
70
+ def available_languages
71
+ # Retrieve a list of available 3 word languages.
72
+ # API Reference: https://docs.what3words.com/api/v3/#available-languages
55
73
  request_params = assemble_common_request_params({})
56
- response = request! :languages, request_params
74
+ response = request! :available_languages, request_params
57
75
  response
58
76
  end
59
77
 
60
- def autosuggest(addr, lang, focus = {}, clip = {}, params = {})
61
- request_params = assemble_autosuggest_request_params(addr, lang, focus,
62
- clip, params)
63
- response = request! :autosuggest, request_params
64
- response
65
- end
78
+ def autosuggest(input, params = {})
79
+ # Returns a list of 3 word addresses based on user input and other parameters.
80
+ # @:param string input: The full or partial 3 word address to obtain suggestions for.
81
+ # At minimum this must be the first two complete words plus at least one character
82
+ # from the third word.
83
+ # @:param int n_results: The number of AutoSuggest results to return.
84
+ # A maximum of 100 results can be specified, if a number greater than this is requested,
85
+ # this will be truncated to the maximum. The default is 3.
86
+ # @:param int n_focus_results: Specifies the number of results (must be <= n_results)
87
+ # within the results set which will have a focus. Defaults to n_results.
88
+ # This allows you to run autosuggest with a mix of focussed and unfocussed results,
89
+ # to give you a "blend" of the two.
90
+ # @:param string clip-to-country: Restricts autosuggest to only return results inside
91
+ # the countries specified by comma-separated list of uppercase ISO 3166-1
92
+ # alpha-2 country codes (for example, to restrict to Belgium and the UK,
93
+ # use clip_to_country="GB,BE").
94
+ # @:param clip-to-bounding-box: Restrict autosuggest results to a bounding box, specified by coordinates.
95
+ # @:param clip-to-circle: Restrict autosuggest results to a circle, specified by
96
+ # the center of the circle, latitude and longitude, and a distance in kilometres which represents the radius.
97
+ # For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179.
98
+ # @:param clip-to-polygon: Restrict autosuggest results to a polygon, specified by a list of coordinates.
99
+ # The polygon should be closed, i.e. the first element should be repeated as the
100
+ # last element; also the list should contain at least 4 entries.
101
+ # The API is currently limited to accepting up to 25 pairs.
102
+ # @:param string input-type: For power users, used to specify voice input mode.
103
+ # Can be text (default), vocon-hybrid, nmdp-asr or generic-voice.
104
+ # @:param string prefer-land: Makes autosuggest prefer results on land to those in the sea.
105
+ # @:param string language: A supported 3 word address language as an ISO 639-1 2 letter code.
106
+ # This setting is on by default. Use false to disable this setting and receive more suggestions in the sea.
66
107
 
67
- def autosuggest_ml(addr, lang, focus = {}, clip = {}, params = {})
68
- request_params = assemble_autosuggest_request_params(addr, lang, focus,
69
- clip, params)
70
- response = request! :autosuggest_ml, request_params
71
- response
72
- end
73
-
74
- def standardblend(addr, lang, focus = {}, params = {})
75
- request_params = assemble_standardblend_request_params(addr, lang, focus,
76
- params)
77
- response = request! :standardblend, request_params
78
- response
79
- end
80
-
81
- def standardblend_ml(addr, lang, focus = {}, params = {})
82
- request_params = assemble_standardblend_request_params(addr, lang, focus,
83
- params)
84
- response = request! :standardblend_ml, request_params
108
+ # API Reference: https://docs.what3words.com/api/v3/#autosuggest
109
+ request_params = assemble_autosuggest_request_params(input, params)
110
+ response = request! :autosuggest, request_params
85
111
  response
86
112
  end
87
113
 
88
114
  def assemble_common_request_params(params)
115
+ # Return common request params
116
+ # @:param api_key: A valid API key
117
+ # @:param string language: A supported 3 word address language as an ISO 639-1 2 letter code.
118
+ # @:param string format: Return data format type; can be one of json (the default), geojson
89
119
  h = { key: key }
90
- h[:lang] = params[:lang] if params[:lang]
120
+ h[:language] = params[:language] if params[:language]
91
121
  h[:format] = params[:format] if params[:format]
92
- h[:display] = params[:display] if params[:display]
93
122
  h
94
123
  end
95
124
  private :assemble_common_request_params
96
125
 
97
- def assemble_forward_request_params(words_string, params)
98
- h = { addr: words_string }
126
+ def assemble_convert_to_coordinates_request_params(words_string, params)
127
+ # Returns request params for the convert to coordinates function
128
+ # @:param string words: A 3 word address as a string
129
+ h = { words: words_string }
99
130
  h.merge(assemble_common_request_params(params))
100
131
  end
101
- private :assemble_forward_request_params
132
+ private :assemble_convert_to_coordinates_request_params
102
133
 
103
- def assemble_grid_request_params(bbox, params)
104
- h = { bbox: bbox }
134
+ def assemble_convert_to_3wa_request_params(position, params)
135
+ # Return request params for the convert to 3wa function
136
+ # @:param coordinates: the coordinates of the location to convert to 3 word address
137
+ h = { coordinates: position.join(',') }
105
138
  h.merge(assemble_common_request_params(params))
106
139
  end
107
- private :assemble_grid_request_params
140
+ private :assemble_convert_to_3wa_request_params
108
141
 
109
- def assemble_reverse_request_params(position, params)
110
- h = { coords: position.join(',') }
142
+ def assemble_grid_request_params(bbox, params)
143
+ # Returns the request params for the grid_section function
144
+ # @:param bounding-box: Bounding box, specified by the northeast and
145
+ # southwest corner coordinates, for which the grid should be returned.
146
+ h = { 'bounding-box': bbox }
111
147
  h.merge(assemble_common_request_params(params))
112
148
  end
113
- private :assemble_reverse_request_params
149
+ private :assemble_grid_request_params
114
150
 
115
- def assemble_autosuggest_request_params(addr, lang, focus, clip, params)
116
- h = { addr: addr }
117
- h[:lang] = lang
118
- h[:focus] = focus.join(',') if focus.respond_to? :join
119
- h[:clip] = clip if clip.respond_to? :to_str
151
+ def assemble_autosuggest_request_params(input, params)
152
+ # Returns the request params for the autosuggest function
153
+ # @:param string input: The full or partial 3 word address to obtain suggestions for.
154
+ # At minimum this must be the first two complete words plus
155
+ # at least one character from the third word.
156
+ # @:param int n_results: The number of AutoSuggest results to return.
157
+ # A maximum of 100 results can be specified, if a number greater than this is requested,
158
+ # this will be truncated to the maximum. The default is 3.
159
+ # @:param int n_focus_results: Specifies the number of results (must be <= n_results)
160
+ # within the results set which will have a focus. Defaults to n_results.
161
+ # This allows you to run autosuggest with a mix of
162
+ # focussed and unfocussed results, to give you a "blend" of the two.
163
+ # @:param string clip-to-country: Restricts autosuggest to only return results inside
164
+ # the countries specified by comma-separated list of uppercase ISO 3166-1
165
+ # alpha-2 country codes (for example, to restrict to Belgium and the UK,
166
+ # use clip_to_country="GB,BE").
167
+ # @:param clip-to-bounding-box: Restrict autosuggest results to a bounding box, specified by coordinates.
168
+ # @:param clip-to-circle: Restrict autosuggest results to a circle, specified by
169
+ # the center of the circle, latitude and longitude, and a distance in kilometres
170
+ # which represents the radius. For convenience, longitude
171
+ # is allowed to wrap around 180 degrees. For example 181 is equivalent to -179.
172
+ # @:param clip-to-polygon: Restrict autosuggest results to a polygon, specified by a list of coordinates.
173
+ # The polygon should be closed, i.e. the first element should be repeated as the
174
+ # last element; also the list should contain at least 4 entries.
175
+ # The API is currently limited to accepting up to 25 pairs.
176
+ # @:param string input-type: For power users, used to specify voice input mode.
177
+ # Can be text (default), vocon-hybrid, nmdp-asr or generic-voice.
178
+ # @:param string prefer-land: Makes autosuggest prefer results on land to those in the sea.
179
+ h = { input: input }
180
+ h[:'n-results'] = params[:'n-results'].to_i if params[:'n-results']
181
+ h[:focus] = params[:focus].join(',') if params[:focus].respond_to? :join
182
+ h[:'n-focus-results'] = params[:'n-focus-results'].to_i if params[:'n-focus-results']
183
+ h[:'clip-to-country'] = params[:'clip-to-country'] if params[:'clip-to-country'].respond_to? :to_str
184
+ h[:'clip-to-bounding-box'] = params[:'clip-to-bounding-box'].join(',') if params[:'clip-to-bounding-box'].respond_to? :join
185
+ h[:'clip-to-circle'] = params[:'clip-to-circle'].join(',') if params[:'clip-to-circle'].respond_to? :join
186
+ h[:'clip-to-polygon'] = params[:'clip-to-polygon'].join(',') if params[:'clip-to-polygon'].respond_to? :join
187
+ h[:'input-type'] = params[:'input-type'] if params[:'input-type'].respond_to? :to_str
188
+ h[:'prefer-land'] = params[:'prefer-land'] if params[:'prefer-land']
120
189
  h.merge(assemble_common_request_params(params))
121
190
  end
122
191
  private :assemble_autosuggest_request_params
123
192
 
124
- def assemble_standardblend_request_params(addr, lang, focus, params)
125
- h = { addr: addr }
126
- h[:lang] = lang
127
- h[:focus] = focus.join(',') if focus.respond_to? :join
128
- h.merge(assemble_common_request_params(params))
129
- end
130
- private :assemble_standardblend_request_params
131
-
132
193
  def request!(endpoint_name, params)
133
- # puts endpoint_name.inspect
194
+ # Defines HTTP request methods
195
+ # puts endpoint(endpoint_name).inspect
134
196
  # puts params.inspect
135
197
  begin
136
- response = RestClient.get endpoint(endpoint_name), params: params
198
+ headers = { "X-W3W-Wrapper": "what3words-Ruby/#{WRAPPER_VERSION}" }
199
+ response = RestClient.get endpoint(endpoint_name), params: params, headers: headers
137
200
  rescue => e
201
+ # puts e.inspect
202
+ # puts e.methods.sort
138
203
  response = e.response
139
204
  end
140
205
  # puts '#{response.to_str}'
141
206
  # puts 'Response status: #{response.code}'
142
207
  response = JSON.parse(response.body)
143
- if response['code'].to_s.strip != ''
208
+ # puts response.inspect
209
+
210
+ if response['error'].to_s.strip != ''
144
211
  raise ResponseError, "#{response['code']}: #{response['message']}"
145
212
  end
213
+
146
214
  deep_symbolize_keys(response)
215
+
147
216
  end
148
217
  private :request!
149
218
 
150
219
  def get_words_string(words)
220
+ # Returns words in string otherwise raise an issue
151
221
  if words.respond_to? :to_str
152
222
  w = words
153
223
  elsif words.respond_to? :join
@@ -163,6 +233,7 @@ module What3Words
163
233
  unless REGEX_3_WORD_ADDRESS.match(words)
164
234
  raise WordError, "#{words} is not a valid 3 word address"
165
235
  end
236
+
166
237
  words
167
238
  end
168
239
  private :check_words
@@ -170,9 +241,7 @@ module What3Words
170
241
  def deep_symbolize_keys(i)
171
242
  if i.is_a? Hash
172
243
  ni = {}
173
- # rubocop:disable Metrics/LineLength
174
244
  i.each { |k, v| ni[k.respond_to?(:to_sym) ? k.to_sym : k] = deep_symbolize_keys(v) }
175
- # rubocop:enable Metrics/LineLength
176
245
  elsif i.is_a? Array
177
246
  ni = i.map(&method(:deep_symbolize_keys))
178
247
  else
data/lib/what3words/version.rb CHANGED
@@ -1,3 +1,6 @@
1
+ # frozen_string_literal: true
2
+
3
+ # What3Words v3 API wrapper
1
4
  module What3Words
2
- VERSION = '2.2.0'.freeze
5
+ VERSION = '3.0.0' unless defined?(::What3Words::VERSION)
3
6
  end
data/lib/what3words.rb CHANGED
@@ -1,4 +1,6 @@
1
- module What3Words #:nodoc: don't document this
1
+ # frozen_string_literal: true
2
+
3
+ module What3Words # :nodoc: don't document this
2
4
  end
3
5
 
4
6
  require 'what3words/api'
data/spec/lib/what3words/what3words_api_spec.rb CHANGED
@@ -1,143 +1,290 @@
1
- # encoding: utf-8
1
+ # frozen_string_literal: true
2
2
 
3
3
  require 'spec_helper'
4
- # rubocop:disable Metrics/LineLength
5
- describe What3Words::API, 'integration', integration: true do # rubocop:disable Metrics/BlockLength
6
- # rubocop:enable Metrics/LineLength
4
+
5
+ # to run the test type on terminal --> bundle exec rspec
6
+
7
+ describe What3Words::API, 'integration', integration: true do
7
8
  before(:all) do
8
9
  WebMock.allow_net_connect!
9
10
  end
10
11
 
11
12
  let(:api_key) { ENV['W3W_API_KEY'] }
12
-
13
13
  let(:w3w) { described_class.new(key: api_key) }
14
14
 
15
15
  it 'returns errors from API' do
16
- badw3w = described_class.new(key: '')
17
- expect { badw3w.forward 'prom.cape.pump' }
16
+ badw3w = described_class.new(key: 'BADKEY')
17
+ expect { badw3w.convert_to_coordinates 'prom.cape.pump' }
18
18
  .to raise_error described_class::ResponseError
19
19
  end
20
20
 
21
21
  describe 'getting position' do
22
+ # @:param string words: A 3 word address as a string
23
+ # @:param string format: Return data format type; can be one of json (the default), geojson
22
24
  it 'works with string of 3 words separated by \'.\'' do
23
- result = w3w.forward 'prom.cape.pump'
25
+ result = w3w.convert_to_coordinates 'prom.cape.pump'
24
26
  expect(result).to include(
25
27
  words: 'prom.cape.pump',
26
28
  language: 'en'
27
29
  )
28
- expect(result[:geometry]).to include(
30
+ expect(result[:coordinates]).to include(
29
31
  lat: 51.484463,
30
32
  lng: -0.195405
31
33
  )
32
34
  end
33
35
 
34
- it 'sends lang parameter for 3 words' do
35
- result = w3w.forward 'prom.cape.pump', lang: 'fr'
36
+ it 'sends language parameter for 3 words' do
37
+ result = w3w.convert_to_coordinates 'prom.cape.pump'
36
38
  expect(result).to include(
37
- words: 'concevoir.époque.amasser',
38
- language: 'fr'
39
+ words: 'prom.cape.pump',
40
+ language: 'en'
39
41
  )
40
42
  end
41
43
 
42
44
  it 'checks 3 words format matches standard regex' do
43
- expect { w3w.forward '1.cape.pump' }
45
+ expect { w3w.convert_to_coordinates '1.cape.pump' }
44
46
  .to raise_error described_class::WordError
45
47
  end
48
+
49
+ it 'sends json parameter for 3 words' do
50
+ result = w3w.convert_to_coordinates 'prom.cape.pump', format: 'json'
51
+ expect(result).to include(
52
+ words: 'prom.cape.pump',
53
+ language: 'en',
54
+ country: 'GB',
55
+ square: {
56
+ 'southwest': {
57
+ 'lng': -0.195426,
58
+ 'lat': 51.484449
59
+ },
60
+ 'northeast': {
61
+ 'lng': -0.195383,
62
+ 'lat': 51.484476
63
+ }
64
+ },
65
+ nearestPlace: 'Kensington, London',
66
+ coordinates: {
67
+ 'lng': -0.195405,
68
+ 'lat': 51.484463
69
+ },
70
+ map: 'https://w3w.co/prom.cape.pump'
71
+ )
72
+ end
46
73
  end
47
74
 
48
75
  describe 'gets 3 words' do
76
+ # @:param coordinates: the coordinates of the location to convert to 3 word address
49
77
  it 'from position' do
50
- result = w3w.reverse [29.567041, 106.587875]
78
+ result = w3w.convert_to_3wa [29.567041, 106.587875], format: 'json'
51
79
  expect(result).to include(
52
80
  words: 'disclose.strain.redefined',
53
81
  language: 'en'
54
82
  )
83
+ expect(result[:coordinates]).to include(
84
+ lat: 29.567041,
85
+ lng: 106.587875
86
+ )
55
87
  end
56
88
 
57
89
  it 'from position in fr' do
58
- result = w3w.reverse [29.567041, 106.587875], lang: 'fr'
90
+ result = w3w.convert_to_3wa [29.567041, 106.587875], language: 'fr', format: 'json'
59
91
  expect(result).to include(
60
92
  words: 'courgette.rabotons.infrason',
61
93
  language: 'fr'
62
94
  )
63
95
  end
64
96
  end
97
+
65
98
  describe 'autosuggest' do
66
- it 'simple addr' do
67
- # result =
68
- w3w.autosuggest 'trop.caler.perdre', 'fr'
99
+ it 'single input returns suggestions' do
100
+ # @:param string input: The full or partial 3 word address to obtain
101
+ # suggestions for. At minimum this must be the first two complete words
102
+ # plus at least one character from the third word.
103
+ result = w3w.autosuggest 'disclose.strain.redefin'
104
+ expect(result).not_to be_empty
69
105
  end
70
106
 
71
- it 'with focus' do
72
- # result =
73
- w3w.autosuggest 'disclose.strain.redefin', 'en', [29.567041, 106.587875]
107
+ it 'simple input will return 3 suggestions' do
108
+ # @:param string input: The full or partial 3 word address to obtain
109
+ # suggestions for. At minimum this must be the first two complete words
110
+ # plus at least one character from the third word.
111
+ result = w3w.autosuggest 'disclose.strain.redefin', language: 'en'
112
+ n_default_results = result[:suggestions].count
113
+ expect(n_default_results).to eq(3)
74
114
  end
75
115
 
76
- it 'with clipping radius around focus' do
77
- # result =
78
- w3w.autosuggest 'disclose.strain.redefin', 'en', [29.567041, 106.587875],
79
- 'focus(10)'
116
+ it 'sends language parameter to an input in a different language' do
117
+ # @:param string language: A supported 3 word address language as an
118
+ # ISO 639-1 2 letter code.
119
+ result = w3w.autosuggest 'trop.caler.perdre', language: 'fr'
120
+ language = result[:suggestions]
121
+ language.each do |item|
122
+ item.each do |k, v|
123
+ if k == 'language'
124
+ expect(v).to eq('fr')
125
+ end
126
+ end
127
+ end
80
128
  end
81
129
 
82
- it 'arabic addr' do
83
- # result =
84
- w3w.autosuggest 'مربية.الصباح.المده', 'ar'
130
+ it 'sends arabic language as a different input' do
131
+ result = w3w.autosuggest 'مربية.الصباح.المده', language: 'ar'
132
+ expect(result).not_to be_empty
85
133
  end
86
- end
87
134
 
88
- describe 'autosuggest-ml' do
89
- it '3 langs (result prefered de)' do
90
- # result =
91
- w3w.autosuggest_ml 'geschaft.planter.carciofi', 'de'
135
+ it 'with n-results' do
136
+ # @:param int n_results: The number of AutoSuggest results to return.
137
+ # A maximum of 100 results can be specified, if a number greater than this is
138
+ # requested, this will be truncated to the maximum. The default is 3.
139
+ result = w3w.autosuggest 'disclose.strain.redefin', language: 'en', 'n-results': 10
140
+ # puts result[:suggestions].count
141
+ n_results = result[:suggestions].count
142
+ expect(n_results).to be >= 10
92
143
  end
93
- it '3 langs (result prefered fr)' do
94
- # result =
95
- w3w.autosuggest_ml 'geschaft.planter.carciofi', 'fr'
144
+
145
+ it 'with n-focus-results' do
146
+ # @:param int n_focus_results: Specifies the number of results (must be <= n_results)
147
+ # within the results set which will have a focus. Defaults to
148
+ # n_results. This allows you to run autosuggest with a mix of
149
+ # focussed and unfocussed results, to give you a "blend" of the two.
150
+ result = w3w.autosuggest 'disclose.strain.redefin', language: 'en', 'n-focus-results': 3
151
+ # puts result[:suggestions].count
152
+ n_focus_results = result[:suggestions].count
153
+ expect(n_focus_results).to be >= 3
96
154
  end
97
- it '3 langs (result prefered it)' do
98
- # result =
99
- w3w.autosuggest_ml 'geschaft.planter.carciofi', 'it'
155
+
156
+ it 'with input-type chenged to generic-voice' do
157
+ # @:param string input-type: For power users, used to specify voice input mode. Can be
158
+ # text (default), vocon-hybrid, nmdp-asr or generic-voice.
159
+ result = w3w.autosuggest 'fun with code', 'input-type': 'generic-voice', language: 'en'
160
+ suggestions = result[:suggestions]
161
+ output = ['fund.with.code', 'funk.with.code', 'fund.with.cove']
162
+ suggestions.each_with_index do |item, index|
163
+ # puts item[:words]
164
+ expect(item[:words]).to eq(output[index])
165
+ end
166
+
167
+ expect(result).not_to be_empty
100
168
  end
101
- end
102
169
 
103
- describe 'standardblend' do
104
- it 'simple addr' do
105
- # result =
106
- w3w.standardblend 'trop.caler.perdre', 'fr'
170
+ xit 'with prefer-land' do
171
+ # @:param string prefer-land: Makes autosuggest prefer results on land to those in the sea.
172
+ # This setting is on by default. Use false to disable this setting and receive more suggestions in the sea.
173
+ result_sea = w3w.autosuggest 'disclose.strain.redefin', 'prefer-land': false, 'n-results': 10
174
+ result_sea_suggestions = result_sea[:suggestions]
175
+
176
+ result_land = w3w.autosuggest 'disclose.strain.redefin', 'prefer-land': true, 'n-results': 10
177
+ result_land_suggestions = result_land[:suggestions]
178
+
179
+ expect(result_sea_suggestions).not_to eq(result_land_suggestions)
107
180
  end
108
181
 
109
- it 'with focus' do
110
- # result =
111
- w3w.standardblend 'disclose.strain.redefin', 'en', [29.567041, 106.587875]
182
+ it 'with clip_to_country' do
183
+ # @:param string clip-to-country: Restricts autosuggest to only return results inside the
184
+ # countries specified by comma-separated list of uppercase ISO 3166-1
185
+ # alpha-2 country codes (for example, to restrict to Belgium and the
186
+ # UK, use clip_to_country="GB,BE")
187
+ result = w3w.autosuggest 'disclose.strain.redefin', 'clip-to-country': 'GB,BE'
188
+ country = result[:suggestions]
189
+ country.each do |item|
190
+ item.each do |k, v|
191
+ if k == 'country'
192
+ if v == 'GB'
193
+ expect(v).to eq('GB')
194
+ else
195
+ expect(v).to eq('BE')
196
+ end
197
+ end
198
+ end
199
+ end
112
200
  end
113
- end
114
201
 
115
- describe 'standardblend-ml' do
116
- it '3 langs (result prefered de)' do
117
- # result =
118
- w3w.standardblend_ml 'geschaft.planter.carciofi', 'de'
202
+ it 'with clip-to-bounding-box' do
203
+ # @:param clip-to-bounding-box: Restrict autosuggest results to a bounding
204
+ # box, specified by coordinates.
205
+ result = w3w.autosuggest 'disclose.strain.redefin', 'clip-to-bounding-box': [51.521, -0.343, 52.6, 2.3324]
206
+ suggestions = result[:suggestions]
207
+ expect(suggestions).to include(
208
+ country: 'GB',
209
+ nearestPlace: 'Saxmundham, Suffolk',
210
+ words: 'discloses.strain.reddish',
211
+ rank: 1,
212
+ language: 'en'
213
+ )
119
214
  end
120
- it '3 langs (result prefered fr)' do
121
- # result =
122
- w3w.standardblend_ml 'geschaft.planter.carciofi', 'fr'
215
+
216
+ it 'with clip-to-bounding-box raise BadClipToBoundingBox error with 3 coordinates' do
217
+ # @:param clip-to-bounding-box: Restrict autosuggest results to a bounding
218
+ # box, specified by coordinates.
219
+ expect { w3w.autosuggest 'disclose.strain.redefin', 'clip-to-bounding-box': [51.521, -0.343, 52.6] }
220
+ .to raise_error described_class::ResponseError
123
221
  end
124
- it '3 langs (result prefered it)' do
125
- # result =
126
- w3w.standardblend_ml 'geschaft.planter.carciofi', 'it'
222
+
223
+ it 'with clip-to-bounding-box raise 2nd BadClipToBoundingBox error' do
224
+ # @:param clip-to-bounding-box: Restrictautosuggest results to a bounding
225
+ # box, specified by coordinates.
226
+ expect { w3w.autosuggest 'disclose.strain.redefin', 'clip-to-bounding-box': [51.521, -0.343, 55.521, -5.343] }
227
+ .to raise_error described_class::ResponseError
228
+ end
229
+
230
+ it 'with clip-to-circle' do
231
+ # @:param clip-to-circle: Restrict autosuggest results to a circle, specified by
232
+ # the center of the circle, latitude and longitude, and a distance in
233
+ # kilometres which represents the radius. For convenience, longitude
234
+ # is allowed to wrap around 180 degrees. For example 181 is equivalent
235
+ # to -179.
236
+ result = w3w.autosuggest 'disclose.strain.redefin', 'clip-to-circle': [51.521, -0.343, 142]
237
+ suggestions = result[:suggestions]
238
+ expect(suggestions).to include(
239
+ country: 'GB',
240
+ nearestPlace: 'Market Harborough, Leicestershire',
241
+ words: 'discloses.strain.reduce',
242
+ rank: 1,
243
+ language: 'en'
244
+ )
245
+ end
246
+
247
+ it 'with clip-to-polygon' do
248
+ # @:param clip-to-polygon: Restrict autosuggest results to a polygon,
249
+ # specified by a list of coordinates. The polygon
250
+ # should be closed, i.e. the first element should be repeated as the
251
+ # last element; also the list should contain at least 4 entries.
252
+ # The API is currently limited to accepting up to 25 pairs.
253
+ result = w3w.autosuggest 'disclose.strain.redefin', 'clip-to-polygon': [51.521, -0.343, 52.6, 2.3324, 54.234, 8.343, 51.521, -0.343]
254
+ suggestions = result[:suggestions]
255
+ expect(suggestions).to include(
256
+ country: 'GB',
257
+ nearestPlace: 'Saxmundham, Suffolk',
258
+ words: 'discloses.strain.reddish',
259
+ rank: 1,
260
+ language: 'en'
261
+ )
127
262
  end
128
263
  end
129
264
 
130
- describe 'grid' do
131
- it 'string input' do
132
- # result =
133
- w3w.grid '52.208867,0.117540,52.207988,0.116126'
265
+ describe 'grid_section' do
266
+ # @:param bounding-box: Bounding box, specified by the northeast and
267
+ # southwest corner coordinates, for which the grid
268
+ # should be returned.
269
+ it 'string input not empty' do
270
+ result = w3w.grid_section '52.208867,0.117540,52.207988,0.116126'
271
+ expect(result).not_to be_empty
272
+ end
273
+ it 'bad bounding box error if the bbox is greater 4km' do
274
+ expect { w3w.grid_section '50.0,178,50.01,180.0005' }
275
+ .to raise_error described_class::ResponseError
134
276
  end
135
277
  end
136
278
 
137
- describe 'languages' do
138
- it 'gets all languages' do
139
- # result =
140
- w3w.languages
279
+ describe 'available_languages' do
280
+ it 'gets all available languages' do
281
+ result = w3w.available_languages
282
+ all_languages = result[:languages].count
283
+ expect(all_languages).to be >= 51
284
+ end
285
+ it 'it does not return an empty list' do
286
+ result = w3w.available_languages
287
+ expect(result).not_to be_empty
141
288
  end
142
289
  end
143
290
 
data/spec/spec_helper.rb CHANGED
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'bundler/setup'
2
4
 
3
5
  Bundler.setup
data/what3words.gemspec CHANGED
@@ -1,28 +1,31 @@
1
- # encoding: utf-8
1
+ # frozen_string_literal: true
2
2
 
3
- lib = File.expand_path('../lib', __FILE__)
3
+ lib = File.expand_path('lib', __dir__)
4
4
  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
5
5
  require 'what3words/version'
6
6
 
7
7
  Gem::Specification.new do |spec|
8
- spec.name = 'what3words'
9
- spec.version = What3Words::VERSION
10
- spec.authors = ['what3words']
11
- spec.email = ['development@what3words.com']
12
- spec.summary = 'what3words API wrapper in Ruby'
13
- spec.homepage = 'http://rubygems.org/gems/what3words'
14
- spec.license = 'MIT'
8
+ spec.name = 'what3words'
9
+ spec.version = What3Words::VERSION
10
+ spec.authors = ['what3words']
11
+ spec.email = ['development@what3words.com']
12
+ spec.description = 'A Ruby wrapper fo the what3words API'
13
+ spec.summary = 'Ruby wrapper for the what3words API'
14
+ spec.homepage = 'http://rubygems.org/gems/what3words'
15
+ spec.license = 'MIT'
15
16
 
16
17
  spec.files = `git ls-files -z`.split("\x0")
17
18
  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
18
19
  spec.test_files = spec.files.grep(%r{^spec/})
19
20
  spec.require_paths = ['lib']
21
+ spec.platform = Gem::Platform::RUBY
22
+ spec.required_ruby_version = '~> 2.6'
20
23
 
21
24
  spec.add_dependency('rest-client', '>= 1.8', '< 3.0')
22
25
 
23
26
  spec.add_development_dependency 'bundler', '>= 1.7.9'
24
27
  spec.add_development_dependency 'rake', '~> 11.1'
25
28
  spec.add_development_dependency 'rspec', '~> 3.4'
26
- spec.add_development_dependency 'webmock', '~> 2.0'
27
29
  spec.add_development_dependency 'rubocop', '~> 0.48.1'
30
+ spec.add_development_dependency 'webmock', '~> 3.0'
28
31
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: what3words
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.2.0
4
+ version: 3.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - what3words
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2018-01-03 00:00:00.000000000 Z
11
+ date: 2022-06-17 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: rest-client
@@ -73,34 +73,34 @@ dependencies:
73
73
  - !ruby/object:Gem::Version
74
74
  version: '3.4'
75
75
  - !ruby/object:Gem::Dependency
76
- name: webmock
76
+ name: rubocop
77
77
  requirement: !ruby/object:Gem::Requirement
78
78
  requirements:
79
79
  - - "~>"
80
80
  - !ruby/object:Gem::Version
81
- version: '2.0'
81
+ version: 0.48.1
82
82
  type: :development
83
83
  prerelease: false
84
84
  version_requirements: !ruby/object:Gem::Requirement
85
85
  requirements:
86
86
  - - "~>"
87
87
  - !ruby/object:Gem::Version
88
- version: '2.0'
88
+ version: 0.48.1
89
89
  - !ruby/object:Gem::Dependency
90
- name: rubocop
90
+ name: webmock
91
91
  requirement: !ruby/object:Gem::Requirement
92
92
  requirements:
93
93
  - - "~>"
94
94
  - !ruby/object:Gem::Version
95
- version: 0.48.1
95
+ version: '3.0'
96
96
  type: :development
97
97
  prerelease: false
98
98
  version_requirements: !ruby/object:Gem::Requirement
99
99
  requirements:
100
100
  - - "~>"
101
101
  - !ruby/object:Gem::Version
102
- version: 0.48.1
103
- description:
102
+ version: '3.0'
103
+ description: A Ruby wrapper fo the what3words API
104
104
  email:
105
105
  - development@what3words.com
106
106
  executables: []
@@ -131,20 +131,19 @@ require_paths:
131
131
  - lib
132
132
  required_ruby_version: !ruby/object:Gem::Requirement
133
133
  requirements:
134
- - - ">="
134
+ - - "~>"
135
135
  - !ruby/object:Gem::Version
136
- version: '0'
136
+ version: '2.6'
137
137
  required_rubygems_version: !ruby/object:Gem::Requirement
138
138
  requirements:
139
139
  - - ">="
140
140
  - !ruby/object:Gem::Version
141
141
  version: '0'
142
142
  requirements: []
143
- rubyforge_project:
144
- rubygems_version: 2.5.2
143
+ rubygems_version: 3.0.3
145
144
  signing_key:
146
145
  specification_version: 4
147
- summary: what3words API wrapper in Ruby
146
+ summary: Ruby wrapper for the what3words API
148
147
  test_files:
149
148
  - spec/config.sample.yaml
150
149
  - spec/lib/what3words/what3words_api_spec.rb