what3words 3.0.0 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +244 -45
- data/lib/what3words/api.rb +175 -190
- data/lib/what3words/version.rb +1 -1
- metadata +9 -20
- data/.editorconfig +0 -17
- data/.gitignore +0 -17
- data/.travis.yml +0 -7
- data/Gemfile +0 -4
- data/LICENSE.txt +0 -22
- data/Rakefile +0 -14
- data/spec/config.sample.yaml +0 -1
- data/spec/lib/what3words/what3words_api_spec.rb +0 -297
- data/spec/spec_helper.rb +0 -9
- data/what3words.gemspec +0 -31
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 80544ac9c1c8a40237f2172b461ce36232980fb005ce91859e0214956e69141d
|
|
4
|
+
data.tar.gz: f98a92b21dbb2950bf1464cb297f5adff151aa315f891ff8d7fd563e54b790fa
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 1bf3e7792855a1c0f187bcd92afee0c4a3455d36159a9a65a542b3a7e75fd74bb6a96ff417c2ef84b67377132868b3df38ecb7656184a716cb9ef9137c50c080
|
|
7
|
+
data.tar.gz: 2fd293b19039de12b6b52d33bb71588d9e90372723f65f928ccef1a6b6ed56dfc3d909d2aea42b37d5859418d22eb7058b905dc7b13367a318dabb0ac415402d
|
data/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
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
6
|
|
|
7
|
-
The what3words API is a fast, simple interface which allows you to convert
|
|
7
|
+
The what3words API is a fast, simple interface which allows you to convert what3words 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
8
|
|
|
9
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)`.
|
|
10
10
|
|
|
@@ -15,7 +15,7 @@ The library is available through [RubyGems](https://rubygems.org/gems/what3words
|
|
|
15
15
|
You can simply add this line to your application's Gemfile:
|
|
16
16
|
|
|
17
17
|
```
|
|
18
|
-
gem 'what3words', '~> 3.
|
|
18
|
+
gem 'what3words', '~> 3.1'
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
And then execute:
|
|
@@ -48,50 +48,66 @@ Then:
|
|
|
48
48
|
what3words = What3Words::API.new(:key => "YOURAPIKEY")
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
Convert to Coordinates: convert a
|
|
51
|
+
Convert to Coordinates: convert a what3words address into GPS coordinates (WGS84)
|
|
52
52
|
|
|
53
53
|
```ruby
|
|
54
|
-
|
|
55
|
-
|
|
54
|
+
what3words.convert_to_coordinates 'prom.cape.pump'
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
**Expected Output**
|
|
58
|
+
```
|
|
59
|
+
# => {: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"}
|
|
56
60
|
```
|
|
57
61
|
|
|
58
62
|
## API
|
|
59
63
|
### Convert to Coordinates
|
|
60
|
-
Convert a
|
|
64
|
+
Convert a what3words address into GPS coordinates and return what3words for the same position.
|
|
61
65
|
|
|
62
66
|
```ruby
|
|
63
|
-
|
|
64
|
-
|
|
67
|
+
what3words.convert_to_coordinates "prom.cape.pump"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Expected Output**
|
|
71
|
+
```
|
|
72
|
+
# => {: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"}
|
|
65
73
|
```
|
|
66
74
|
Supported keyword params for `convert_to_coordinates` call:
|
|
67
75
|
|
|
68
|
-
* `words` A
|
|
76
|
+
* `words` A what3words address as a string
|
|
69
77
|
* `format` Return data format type. It can be one of json (the default) or geojson
|
|
70
78
|
|
|
71
79
|
|
|
72
80
|
### Convert to 3WA
|
|
73
|
-
Convert position information, latitude and longitude coordinates, into a
|
|
81
|
+
Convert position information, latitude and longitude coordinates, into a what3words address.
|
|
74
82
|
|
|
75
83
|
```ruby
|
|
76
|
-
|
|
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"}
|
|
84
|
+
what3words.convert_to_3wa [29.567041, 106.587875]
|
|
78
85
|
```
|
|
79
86
|
|
|
80
|
-
|
|
87
|
+
**Expected Output**
|
|
88
|
+
```
|
|
89
|
+
# => {: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"}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Convert position information to a what3words address in a specific language
|
|
81
93
|
|
|
82
94
|
```ruby
|
|
83
|
-
|
|
84
|
-
|
|
95
|
+
what3words.convert_to_3wa [29.567041, 106.587875], language: 'fr'
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
**Expected Output**
|
|
99
|
+
```
|
|
100
|
+
# => :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"}
|
|
85
101
|
```
|
|
86
102
|
|
|
87
103
|
Supported keyword params for `convert_to_3wa` call:
|
|
88
104
|
|
|
89
|
-
* `coordinates` The coordinates of the location to convert to
|
|
90
|
-
* `language` (defaults to en) - A supported
|
|
105
|
+
* `coordinates` The coordinates of the location to convert to what3words address
|
|
106
|
+
* `language` (defaults to en) - A supported what3words address language as an ISO 639-1 2 letter code
|
|
91
107
|
* `format` Return data format type. It can be one of json (the default) or geojson
|
|
92
108
|
|
|
93
109
|
### Autosuggest
|
|
94
|
-
Returns a list of
|
|
110
|
+
Returns a list of what3words addresses based on user input and other parameters.
|
|
95
111
|
|
|
96
112
|
This resource provides corrections for the following types of input error:
|
|
97
113
|
- typing errors
|
|
@@ -99,77 +115,124 @@ This resource provides corrections for the following types of input error:
|
|
|
99
115
|
- misremembered words (e.g. singular vs. plural)
|
|
100
116
|
- words in the wrong order
|
|
101
117
|
|
|
102
|
-
The autosuggest resource determines possible corrections to the supplied
|
|
118
|
+
The autosuggest resource determines possible corrections to the supplied what3words 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.
|
|
103
119
|
|
|
104
120
|
See [https://developer.what3words.com/public-api/docs#autosuggest](https://developer.what3words.com/public-api/docs#autosuggest) for detailed information
|
|
105
121
|
|
|
106
122
|
Gets suggestions in french for this address:
|
|
107
123
|
|
|
108
124
|
```ruby
|
|
109
|
-
|
|
110
|
-
|
|
125
|
+
what3words.autosuggest 'trop.caler.perdre', language: 'fr'
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Expected Output**
|
|
129
|
+
```
|
|
130
|
+
# => {: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
131
|
```
|
|
112
132
|
|
|
113
133
|
Gets suggestions for a different number of suggestions, i.e. 10 for this address:
|
|
114
134
|
|
|
115
135
|
```ruby
|
|
116
|
-
|
|
117
|
-
|
|
136
|
+
what3words.autosuggest 'disclose.strain.redefin', language: 'en', 'n-results': 10
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
**Expected Output**
|
|
140
|
+
```
|
|
141
|
+
# => {: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"}]}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Gets suggestions when the coordinates for focus has been provided for this address:
|
|
145
|
+
|
|
146
|
+
```ruby
|
|
147
|
+
what3words.autosuggest 'filled.count.soap', focus: [51.4243877,-0.34745]
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
**Expected Output**
|
|
151
|
+
```
|
|
152
|
+
# => {: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"}]}
|
|
118
153
|
```
|
|
119
154
|
|
|
120
155
|
Gets suggestions for a different number of focus results for this address:
|
|
121
156
|
|
|
122
157
|
```ruby
|
|
123
|
-
|
|
124
|
-
|
|
158
|
+
what3words.autosuggest 'disclose.strain.redefin', language: 'en', 'n-focus-results': 3
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**Expected Output**
|
|
162
|
+
```
|
|
163
|
+
# => {: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"}]}
|
|
125
164
|
```
|
|
126
165
|
|
|
127
166
|
Gets suggestions for a voice input type mode, i.e. generic-voice, for this address:
|
|
128
167
|
|
|
129
168
|
```ruby
|
|
130
|
-
|
|
131
|
-
|
|
169
|
+
what3words.autosuggest 'fun with code', 'input-type': 'generic-voice', language: 'en'
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
**Expected Output**
|
|
173
|
+
```
|
|
174
|
+
# => {: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"}]}
|
|
132
175
|
```
|
|
133
176
|
|
|
134
|
-
Gets suggestions for a restricted area by clipping to
|
|
177
|
+
Gets suggestions for a restricted area by clipping to country for this address:
|
|
135
178
|
|
|
136
179
|
```ruby
|
|
137
|
-
|
|
138
|
-
|
|
180
|
+
what3words.autosuggest 'disclose.strain.redefin', 'clip-to-country': 'GB,BE'
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
**Expected Output**
|
|
184
|
+
```
|
|
185
|
+
# => {: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
186
|
```
|
|
140
187
|
|
|
141
188
|
Gets suggestions for a restricted area by clipping to a bounding-box for this address:
|
|
142
189
|
|
|
143
190
|
```ruby
|
|
144
|
-
|
|
145
|
-
|
|
191
|
+
what3words.autosuggest 'disclose.strain.redefin', 'clip-to-bounding-box': [51.521, -0.343, 52.6, 2.3324]
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
**Expected Output**
|
|
195
|
+
```
|
|
196
|
+
# => {:suggestions=>[{:country=>"GB", :nearestPlace=>"Saxmundham, Suffolk", :words=>"discloses.strain.reddish", :rank=>1, :language=>"en"}]}
|
|
146
197
|
```
|
|
147
198
|
|
|
148
199
|
|
|
149
200
|
Gets suggestions for a restricted area by clipping to a circle in km for this address:
|
|
150
201
|
|
|
151
202
|
```ruby
|
|
152
|
-
|
|
153
|
-
|
|
203
|
+
what3words.autosuggest 'disclose.strain.redefin', 'clip-to-circle': [51.521, -0.343, 142]
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
**Expected Output**
|
|
207
|
+
```
|
|
208
|
+
# => {:suggestions=>[{:country=>"GB", :nearestPlace=>"Market Harborough, Leicestershire", :words=>"discloses.strain.reduce", :rank=>1, :language=>"en"}]}
|
|
154
209
|
```
|
|
155
210
|
|
|
156
211
|
Gets suggestions for a restricted area by clipping to a polygon for this address:
|
|
157
212
|
|
|
158
213
|
```ruby
|
|
159
|
-
|
|
160
|
-
|
|
214
|
+
what3words.autosuggest 'disclose.strain.redefin', 'clip-to-polygon': [51.521, -0.343, 52.6, 2.3324, 54.234, 8.343, 51.521, -0.343]
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
**Expected Output**
|
|
218
|
+
```
|
|
219
|
+
# => {:suggestions=>[{:country=>"GB", :nearestPlace=>"Saxmundham, Suffolk", :words=>"discloses.strain.reddish", :rank=>1, :language=>"en"}]}
|
|
161
220
|
```
|
|
162
221
|
|
|
163
222
|
Gets suggestions for a restricted area by clipping to a polygon for this address:
|
|
164
223
|
|
|
165
224
|
```ruby
|
|
166
|
-
|
|
167
|
-
|
|
225
|
+
what3words.w3w.autosuggest 'disclose.strain.redefin', 'prefer-land': false, 'n-results': 10
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
**Expected Output**
|
|
229
|
+
```
|
|
230
|
+
# => {: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"}]}
|
|
168
231
|
```
|
|
169
232
|
|
|
170
233
|
Supported keyword params for `autosuggest` call:
|
|
171
|
-
* `input` The full or partial
|
|
172
|
-
* `language` A supported
|
|
234
|
+
* `input` The full or partial what3words address to obtain suggestions for. At minimum this must be the first two complete words plus at least one character from the third word.
|
|
235
|
+
* `language` A supported what3words 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
236
|
* `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
237
|
* `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
238
|
* `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").
|
|
@@ -187,8 +250,12 @@ See [https://developer.what3words.com/public-api/docs#grid-section](https://deve
|
|
|
187
250
|
Gets grid for these bounding box northeast 52.208867,0.117540,52.207988,0.116126.
|
|
188
251
|
|
|
189
252
|
```ruby
|
|
190
|
-
|
|
191
|
-
|
|
253
|
+
what3words.grid_section '52.208867,0.117540,52.207988,0.116126'
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
**Expected Output**
|
|
257
|
+
```
|
|
258
|
+
# => {: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}}, ___...___ ]}
|
|
192
259
|
```
|
|
193
260
|
|
|
194
261
|
Supported keyword params for `grid_section` call:
|
|
@@ -196,15 +263,146 @@ Supported keyword params for `grid_section` call:
|
|
|
196
263
|
* `format` Return data format type. It can be one of json (the default) or geojson
|
|
197
264
|
|
|
198
265
|
### Get Languages
|
|
199
|
-
Retrieve a list of available
|
|
266
|
+
Retrieve a list of available what3words languages.
|
|
200
267
|
|
|
201
268
|
```ruby
|
|
202
|
-
|
|
203
|
-
|
|
269
|
+
what3words.available_languages
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
**Expected Output**
|
|
273
|
+
```
|
|
274
|
+
# => {: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"}, ___...___]}
|
|
204
275
|
```
|
|
205
276
|
|
|
206
277
|
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.
|
|
207
278
|
|
|
279
|
+
### RegEx functions
|
|
280
|
+
|
|
281
|
+
This section introduces RegEx functions that can assist with checking and finding possible what3words addresses in strings. The three main functions covered are:
|
|
282
|
+
|
|
283
|
+
`isPossible3wa` – Match what3words address format;
|
|
284
|
+
`findPossible3wa` – Find what3words address in Text;
|
|
285
|
+
`isValid3wa` – Verify a what3words address with the API;
|
|
286
|
+
|
|
287
|
+
#### isPossible3wa
|
|
288
|
+
|
|
289
|
+
Our API wrapper RegEx function `isPossible3wa` can be used used to detect if a text string (like `filled.count.soap`) in the format of a what3words address without having to ask the API. This functionality checks if a given string could be a what3words address. It returns true if it could be, otherwise false.
|
|
290
|
+
|
|
291
|
+
**Note**: This function checks the text format but not the validity of a what3words address. Use `isValid3wa` to verify validity.
|
|
292
|
+
|
|
293
|
+
```ruby
|
|
294
|
+
require 'what3words'
|
|
295
|
+
|
|
296
|
+
def main
|
|
297
|
+
# Initialize the What3Words API with your API key
|
|
298
|
+
api_key = 'YOUR_API_KEY'
|
|
299
|
+
w3w = What3Words::API.new(:key => api_key)
|
|
300
|
+
|
|
301
|
+
# Example what3words addresses
|
|
302
|
+
addresses = ["filled.count.soap", "not a 3wa", "not.3wa address"]
|
|
303
|
+
|
|
304
|
+
# Check if the addresses are possible what3words addresses
|
|
305
|
+
addresses.each do |address|
|
|
306
|
+
is_possible = w3w.isPossible3wa(address)
|
|
307
|
+
puts "Is '#{address}' a possible what3words address? #{is_possible}"
|
|
308
|
+
end
|
|
309
|
+
end
|
|
310
|
+
|
|
311
|
+
if __FILE__ == $0
|
|
312
|
+
main
|
|
313
|
+
end
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
**Expected Output**
|
|
317
|
+
|
|
318
|
+
isPossible3wa(“filled.count.soap”) returns true
|
|
319
|
+
isPossible3wa(“not a 3wa”) returns false
|
|
320
|
+
isPossible3wa(“not.3wa address”)returns false
|
|
321
|
+
|
|
322
|
+
#### findPossible3wa
|
|
323
|
+
|
|
324
|
+
Our API wrapper RegEx function `findPossible3wa` can be used to detect a what3words address within a block of text, useful for finding a what3words address in fields like Delivery Notes. For example, it can locate a what3words address in a note like “Leave at my front door ///filled.count.soap”. The function will match if there is a what3words address within the text. If no possible addresses are found, it returns an empty list.
|
|
325
|
+
|
|
326
|
+
**Note**:
|
|
327
|
+
|
|
328
|
+
- This function checks the text format but not the validity of a what3words address. Use `isValid3wa` to verify validity.
|
|
329
|
+
- This function is designed to work across languages but do not work for `Vietnamese (VI)` due to spaces within words.
|
|
330
|
+
|
|
331
|
+
```ruby
|
|
332
|
+
require 'what3words'
|
|
333
|
+
|
|
334
|
+
def main
|
|
335
|
+
# Initialize the what3words API with your API key
|
|
336
|
+
api_key = 'YOUR_API_KEY'
|
|
337
|
+
w3w = What3Words::API.new(:key => api_key)
|
|
338
|
+
|
|
339
|
+
# Example texts
|
|
340
|
+
texts = [
|
|
341
|
+
"Please leave by my porch at filled.count.soap",
|
|
342
|
+
"Please leave by my porch at filled.count.soap or deed.tulip.judge",
|
|
343
|
+
"Please leave by my porch at"
|
|
344
|
+
]
|
|
345
|
+
|
|
346
|
+
# Check if the texts contain possible what3words addresses
|
|
347
|
+
texts.each do |text|
|
|
348
|
+
possible_addresses = w3w.findPossible3wa(text)
|
|
349
|
+
puts "Possible what3words addresses in '#{text}': #{possible_addresses}"
|
|
350
|
+
end
|
|
351
|
+
end
|
|
352
|
+
|
|
353
|
+
if __FILE__ == $0
|
|
354
|
+
main
|
|
355
|
+
end
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
**Expected Output**
|
|
359
|
+
|
|
360
|
+
findPossible3wa(“Please leave by my porch at filled.count.soap”) returns ['filled.count.soap']
|
|
361
|
+
findPossible3wa(“Please leave by my porch at filled.count.soap or deed.tulip.judge”) returns ['filled.count.soap', 'deed.tulip.judge']
|
|
362
|
+
findPossible3wa(“Please leave by my porch at”) returns []
|
|
363
|
+
|
|
364
|
+
#### isValid3wa
|
|
365
|
+
|
|
366
|
+
Our API wrapper RegEx function `isValid3wa` can be used to determine if a string is a valid what3words address by checking it against the what3words RegEx filter and verifying it with the what3words API.
|
|
367
|
+
|
|
368
|
+
```ruby
|
|
369
|
+
require 'what3words'
|
|
370
|
+
|
|
371
|
+
def main
|
|
372
|
+
# Initialize the what3words API with your API key
|
|
373
|
+
api_key = 'YOUR_API_KEY'
|
|
374
|
+
w3w = What3Words::API.new(:key => api_key)
|
|
375
|
+
|
|
376
|
+
# Example addresses
|
|
377
|
+
addresses = [
|
|
378
|
+
"filled.count.soap",
|
|
379
|
+
"filled.count.",
|
|
380
|
+
"coding.is.cool"
|
|
381
|
+
]
|
|
382
|
+
|
|
383
|
+
# Check if the addresses are valid what3words addresses
|
|
384
|
+
addresses.each do |address|
|
|
385
|
+
is_valid = w3w.isValid3wa(address)
|
|
386
|
+
puts "Is '#{address}' a valid what3words address? #{is_valid}"
|
|
387
|
+
end
|
|
388
|
+
end
|
|
389
|
+
|
|
390
|
+
if __FILE__ == $0
|
|
391
|
+
main
|
|
392
|
+
end
|
|
393
|
+
```
|
|
394
|
+
**Expected Outputs**
|
|
395
|
+
|
|
396
|
+
isValid3wa(“filled.count.soap”) returns True
|
|
397
|
+
isValid3wa(“filled.count.”) returns False
|
|
398
|
+
isValid3wa(“coding.is.cool”) returns False
|
|
399
|
+
|
|
400
|
+
Also make sure to replace `<YOUR_API_KEY>` with your actual API key. These functionalities provide different levels of validation for what3words addresses, from simply identifying potential addresses to verifying their existence on Earth.
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
See [https://developer.what3words.com/tutorial/ruby#regex-functions](https://developer.what3words.com/tutorial/ruby#regex-functions) for further documentation.
|
|
404
|
+
|
|
405
|
+
|
|
208
406
|
## Testing
|
|
209
407
|
|
|
210
408
|
* Prerequisite : we are using [bundler](https://rubygems.org/gems/bundler) `$ gem install bundler`
|
|
@@ -240,6 +438,7 @@ Anyone and everyone is welcome to contribute.
|
|
|
240
438
|
|
|
241
439
|
# Revision History
|
|
242
440
|
|
|
441
|
+
* `v3.1.0` 16/07/24 - Update tests and code to host the regex functions
|
|
243
442
|
* `v3.0.0` 12/05/22 - Update endpoints and tests to API v3, added HTTP headers
|
|
244
443
|
* `v2.2.0` 03/01/18 - Enforce Ruby 2.4 Support - Thanks to PR from Dimitrios Zorbas [@Zorbash](https://github.com/zorbash)
|
|
245
444
|
* `v2.1.1` 22/05/17 - Update gemspec to use rubocop 0.48.1, and fixes spec accordingly
|