You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A swift library to use the what3words [REST API](https://docs.what3words.com/api/v3/), and the what3words [VoiceAPI](https://developer.what3words.com/voice-api).
5
+
A Swift library for interacting with the what3words [REST API](https://docs.what3words.com/api/v3/) and [VoiceAPI](https://developer.what3words.com/voice-api).
6
6
7
7
# Overview
8
8
@@ -17,13 +17,13 @@ The what3words Swift API wrapper gives you programmatic access to
17
17
18
18
The main API swift wrapper object is `What3WordsV3` and provides the above functionality. There is also a higher level `W3WAutosuggestHelper` that does a lot of the work of calling the API for text field autosuggest functionality. This is particularly helpful if you want to add what3words to your existing autocomplete code. A tutorial can be found [here](Documentation/tutorial-as-helper.md).
19
19
20
-
Even higher level UI functionality can be found in our UI components library, [w3w-swift-components](https://github.com/what3words/w3w-swift-components), found on GitHub. Notably our `W3WAutosuggestTextField`inherits `UITextField`and adds threeword address autocomplete functionality.
20
+
For even higher-level UI components, check out our [w3w-swift-components](https://github.com/what3words/w3w-swift-components) library on GitHub, including `W3WAutosuggestTextField`which extends `UITextField`to add three-word address autocomplete functionality.
21
21
22
-
#### TLDR:
22
+
#### Quick Start:
23
23
24
-
You can find a short tutorial [here](Documentation/tutorial.md)that will show you how to get minimally set up and running.
24
+
You can find a quick-start tutorial [here](Documentation/tutorial.md)to help you get set up and running with the basics.
25
25
26
-
#### Objective-C
26
+
#### Objective-C Compatibility
27
27
28
28
This package also contains an Objective-C compatible version, `What3WordsObjC` - see the `ObjectiveC` project in [Examples/ObjectiveC/ObjectiveC.xcodeproj](./Examples/ObjectiveC/ObjectiveC.xcodeproj)
29
29
@@ -43,7 +43,7 @@ To use this library you’ll need a what3words API key, which can be signed up f
43
43
44
44
# Examples
45
45
46
-
Examples for this package can be ofund in our exmaples repository:
46
+
Examples of this package can be found in our examples repository:
You can use CocoaPods to install w3w-swift-wrapper by adding it to the target in your Podfile:
61
+
You can use CocoaPods to install the `w3w-swift-wrapper` by adding it to the target in your Podfile:
62
62
63
63
```
64
64
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
65
+
```
66
+
or, if you would like to use both the W3WSwiftApi and W3WSwiftVoiceApi libraries:
67
+
68
+
```
69
+
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
70
+
pod 'W3WSwiftVoiceApi', :git => 'https://github.com/what3words/w3w-swift-voice-api.git'
71
+
65
72
```
66
73
67
74
## Usage
68
75
69
76
### Import
70
77
71
-
In any file you use the what3words API in, import the following:
78
+
In any file where you use the What3words API, import the following:
72
79
73
-
```swift
80
+
```
74
81
import W3WSwiftApi
82
+
import W3WSwiftVoiceApi
75
83
import CoreLocation
76
84
```
77
85
78
86
##### Note:
79
87
80
-
* If you are using CocoaPods use `import what3words` instead.
81
-
* If you are using this package's Voice API features on device, you should include Microphone permissions:
88
+
* If you are using this package's Voice API features on your device, you should include Microphone permissions:
82
89
83
90
<imgsrc="Documentation/plist2.png"width="75%">
84
91
@@ -104,7 +111,7 @@ let api = What3WordsV3(apiKey: "YourApiKey", apiUrl: "https://api.yourserver.com
104
111
105
112
# Functions
106
113
107
-
Each call takes a completion block as the last parameter. This allows Swift's trailing closure syntax to be used. The closure's parameters contain the results. If there was a problem with any call, it will be indicated by the [error object](#errors).
114
+
Each call takes a completion block as the last parameter. This allows Swift's trailing closure syntax to be used. The closure's parameters contain the results. If there is a problem with any call, it will be indicated by the [error object](#errors).
Convert a 3 word address to a position, expressed as coordinates of latitude and longitude. This function takes the words parameter as a string of 3 words `'table.book.chair'`. The values returned from the `convertToCoordinates` method are described in the [API documentation](https://docs.what3words.com/api/v3/#convert-to-coords).
132
+
Convert a 3 word address into geographic coordinates, represented by latitude and longitude. This function takes the words parameter as a string of 3 words `'table.book.chair'`. The values returned from the `convertToCoordinates` method are described in the [API documentation](https://docs.what3words.com/api/v3/#convert-to-coords).
126
133
127
134
##### Code Example:
128
135
```swift
@@ -135,7 +142,7 @@ api.convertToCoordinates(words: "filled.count.soap") { square, error in
135
142
136
143
Returns a list of 3 word addresses based on user input and other parameters.
137
144
138
-
This method provides corrections for the following types of input error:
145
+
This method provides corrections for the following types of input errors:
139
146
140
147
* typing errors
141
148
* spelling errors
@@ -144,17 +151,16 @@ This method provides corrections for the following types of input error:
144
151
145
152
The `autosuggest` method 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 method can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.
146
153
147
-
*voice
154
+
*Voice
148
155
149
-
If you have a VoiceAPIenabled account, you may also call `autosuggest` with audio data for voice recognition. In order for this to work, you must add a Voice API plan to [your account](https://accounts.what3words.com/billing).
156
+
If you have a VoiceAPI-enabled account, you may also call `autosuggest` with audio data for voice recognition. For this to work, you must add a Voice API plan to [your account](https://accounts.what3words.com/billing).
150
157
There is a minimal [example of this below](#voice-example), but detailed information can be found [here](Documentation/README.voiceAPI.md)
151
158
152
159
### Input 3 word address
153
160
154
161
You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.
155
162
156
-
To check if your address string meets this criteria, we provide a simple function that employs our regex to help you recognise the three word addresses. It is called `isPossible3wa`, but please note that it only indicates if the input is three potential words separated by two w3w separators. It WILL NOT tell you if it is a real three word address in world. The following `if` evaluates to `true`.
157
-
163
+
To verify if your address string meets the required format, we offer a simple function called `isPossible3wa`. This function uses our regex to identify potential three word addresses, confirming only if the input consists of three words separated by two what3words separators. Please note that it does not validate whether the input is an actual three word address in the world. The following `if` statement will return `true.`
158
164
```
159
165
if api.isPossible3wa(text: "xxx.xxx.x") {
160
166
print("Input is in the form of a three word address")
@@ -168,7 +174,7 @@ Or if you prefer, you can simply use our regex. Example code can be found in our
168
174
169
175
### Clipping
170
176
171
-
We provide various `clip` policies to allow you to filter by a geographic area. We recommend that you use the clipping to give a more targeted set of results to your user. You can clip by country, or by geographical box, circle or polygon. Do this via the `W3WOptions` and pass it into the autosuggest call (see example below).
177
+
We provide various `clip` policies to allow you to filter by a geographic area. We recommend that you use the clipping options to give a more targeted set of results to your user. You can clip by country, or by geographical box, circle or polygon. Do this via the `W3WOptions` and pass it into the autosuggest call (see example below).
172
178
173
179
### Focus
174
180
@@ -179,7 +185,7 @@ The values returned from the `autosuggest` method are described in the [what3wor
179
185
180
186
### Usage
181
187
182
-
The first parameter is the partial three words, or voice data. The second optional parameter is the options for the autosuggest function. The last parameter is the completion block.
188
+
The first parameter is the partial three words or voice data. The second optional parameter is the options for the autosuggest function. The last parameter is the completion block.
Also, `W3WMicrophone` has a callback closure `W3WMicrophone.volumeUpdate: (Double) -> ()` that provides amplitude information useful for animating user feedback. See the the [Voice API example](./Examples/VoiceAPI/VoiceAPI.xcodeproj), and more information is avialable in the [VoiceAPI README](Documentation/README.voiceAPI.md).
243
+
Also, `W3WMicrophone` has a callback closure `W3WMicrophone.volumeUpdate: (Double) -> ()` that provides amplitude information useful for animating user feedback. See the [Voice API example](./Examples/VoiceAPI/VoiceAPI.xcodeproj), and more information is available in the [VoiceAPI README](Documentation/README.voiceAPI.md).
238
244
239
245
## Available Languages
240
246
@@ -255,7 +261,7 @@ For the available Voice API languages call `api.availableVoiceLanguages(completi
255
261
256
262
## Grid Section
257
263
258
-
Returns a section of the 3m x 3m what3words grid for a given area. The requested box must not exceed 4km from corner to corner, or a BadBoundingBoxTooBig error will be returned. Latitudes must be >= -90 and <= 90, but longitudes are allowed to wrap around 180. To specify a bounding-box that crosses the anti-meridian, use longitude greater than 180. Example value: 50.0, 179.995, 50.01, 180.0005.
264
+
Returns a section of the 3m x 3m what3words grid for a given area. The requested box must not exceed 4km from corner to corner, or a BadBoundingBoxTooBig error will be returned. Latitudes must be >= -90 and <= 90, but longitudes are allowed to wrap around 180. To specify a boundingbox that crosses the anti-meridian, use a longitude greater than 180. Example value: 50.0, 179.995, 50.01, 180.0005.
259
265
260
266
The grid is returned as `[W3WLine]?` and each `W3WLine` contains a `start` and `end` variable, both of type `CLLocationCoordinate2D`.
261
267
@@ -279,7 +285,7 @@ These are some functions that will search or validate three word addresses.
279
285
280
286
#### isPossible3wa(text: String) -> Bool
281
287
282
-
Checks to see if the text follows the form of a three word address via regex, that is, a word followed by a separator followed by a word followed by a separator followed by a word. A word is defined as series of letters that belong to any writing system.
288
+
Check to see if the text follows the form of a three word address via regex, that is, a word followed by a separator followed by a word followed by a separator followed by a word. A word is defined as series of letters that belong to any writing system.
283
289
This does not validate the address as being a real location on the earth, just that it follows the textual form of one. For example, xx.xx.xx would pass this test even though it is not a valid address.
284
290
285
291
```Swift
@@ -304,7 +310,7 @@ api.isValid3wa(words: "filled.count.soap") { valid in
304
310
305
311
#### findPossible3wa(text: String) -> [String]
306
312
307
-
Finds any number of possible three word addresses in a block of text. The term "possible three word addresses" refers to text that matches the regex used in isPossible3wa(), that is, these are pieces of text that appear to be three word address, but have not been veified against the engine as representing an actual place on earth.
313
+
Finds any number of possible three word addresses in a block of text. The term "possible three word addresses" refers to text that matches the regex used in isPossible3wa(), that is, these are pieces of text that appear to be three word addresses, but have not been verified against the engine as representing an actual place on earth.
308
314
309
315
```Swift
310
316
let twas = api.findPossible3wa(text: "This is a filled.count.soap sentence with index.home.raft fun in it nowhere near grilled.cheese.sandwhich")
0 commit comments