w3w swift wrapper
v4.0.1
用于与三词地址 REST API 和 VoiceAPI 交互的 Swift 库。
What3words Swift API 包装器使您能够以编程方式访问
主要的 API swift 包装对象是What3WordsV3 ，并提供上述功能。还有一个更高级别的W3WAutosuggestHelper ，它完成了调用文本字段自动建议功能的 API 的大量工作。如果您想将三词地址添加到现有的自动完成代码中，这特别有用。可以在此处找到教程。
对于更高级别的 UI 组件，请查看 GitHub 上的 w3w-swift-components 库，包括W3WAutosuggestTextField ，它扩展了UITextField以添加三字地址自动完成功能。
您可以在此处找到快速入门教程，以帮助您进行基础设置和运行。
该软件包还包含 Objective-C 兼容版本What3WordsObjC - 请参阅 Examples/ObjectiveC/ObjectiveC.xcodeproj 中的ObjectiveC项目
该软件包适用于：
要使用此库，您需要一个三词地址 API 密钥，可以在此处注册。如果您希望使用语音 API 调用，则必须将语音 API 计划添加到您的帐户。
该包的示例可以在我们的示例存储库中找到：https://github.com/what3words/w3w-swift-samples
您可以使用 Swift Package Manager 安装它，方法是将以下 URL 添加到项目设置下的 Swift Packages：
https://github.com/what3words/w3w-swift-wrapper.git
您可以使用 CocoaPods 将w3w-swift-wrapper添加到 Podfile 中的目标来安装它：
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
或者，如果您想同时使用 W3WSwiftApi 和 W3WSwiftVoiceApi 库：
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
pod 'W3WSwiftVoiceApi', :git => 'https://github.com/what3words/w3w-swift-voice-api.git'
在使用 What3words API 的任何文件中，导入以下内容：
import W3WSwiftApi
import W3WSwiftVoiceApi
import CoreLocation
使用以下代码和您的 API 密钥来初始化 API：
let api = What3WordsV3 ( apiKey : " YourApiKey " )如果您自己运行我们的 Enterprise Suite API 服务器，您可以指定您自己的服务器的 URL，如下所示：
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " )此外，如果您运行 Enterprise Suite API Server，还有另一个可选的setup()参数： customHeaders 。如果您需要将自定义标头发送到您自己的服务器，请使用此选项：
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " , customHeaders : [ " x-header-1 " : " value-1 " , " x-header-2 " : " value-2 " ] )每个调用都将一个完成块作为最后一个参数。这允许使用 Swift 的尾随闭包语法。闭包的参数包含结果。如果任何调用出现问题，都会通过错误对象来指示。
将以纬度和经度表示的坐标转换为 3 字地址。该函数将纬度和经度作为 CLLocationCooperative2D 对象。 API 文档中描述了从convertTo3wa方法返回的值。
let coords = CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 )
api . convertTo3wa ( coordinates : coords , language : W3WApiLanguage ( locale : " en " ) ) { square , error in
print ( square ? . words ?? " " )
} 将三字地址转换为地理坐标，以纬度和经度表示。该函数将words参数作为3个单词的字符串'table.book.chair' 。 API 文档中描述了从convertToCoordinates方法返回的值。
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} 根据用户输入和其他参数返回 3 字地址的列表。
此方法可纠正以下类型的输入错误：
autosuggest方法根据上面列出的输入错误的概率确定对所提供的 3 字地址字符串的可能更正，并返回建议的排名列表。该方法还可以考虑可能的校正与给定位置的地理邻近性，以进一步改进返回的建议。
如果您有启用 VoiceAPI 的帐户，您还可以使用音频数据调用autosuggest以进行语音识别。为此，您必须将语音 API 计划添加到您的帐户。下面有一个最小的示例，但可以在此处找到详细信息
仅当您提交的部分 3 字地址字符串包含前两个单词且至少包含第三个单词的第一个字符时，您才会收到返回结果；否则会返回错误信息。
为了验证您的地址字符串是否符合所需的格式，我们提供了一个名为isPossible3wa的简单函数。该函数使用我们的正则表达式来识别潜在的三字地址，仅确认输入是否包含由两个三词地址分隔符分隔的三个单词。请注意，它不会验证输入是否是世界上实际的三字地址。下面的if语句将返回true.
if api.isPossible3wa(text: "xxx.xxx.x") {
print("Input is in the form of a three word address")
} else {
print("Input is NOT in the form of a three word address")
}
或者，如果您愿意，您可以简单地使用我们的正则表达式。示例代码可以在我们的正则表达式文档中找到。
我们提供各种clip策略，允许您按地理区域进行过滤。我们建议您使用剪切选项为用户提供更有针对性的结果集。您可以按国家/地区、地理框、圆形或多边形进行剪辑。通过W3WOptions执行此操作并将其传递到自动建议调用中（请参见下面的示例）。
如果您知道用户的当前位置，我们还强烈建议您使用焦点来返回可能更相关的结果。通过W3WOptions执行此操作并将其传递到自动建议调用中（请参见下面的示例）
What3words REST API 文档中描述了从autosuggest方法返回的值。
第一个参数是部分三个字或语音数据。第二个可选参数是自动建议功能的选项。最后一个参数是完成块。
api . autosuggest ( text : " filled.count.soa " ) { ( suggestions , error ) in
for suggestion in suggestions ?? [ ] {
print ( " ( suggestion . words ?? " " ) is near ( suggestion . nearestPlace ?? " " ) " )
}
} 使用单一选项专注于一个特定位置：
let coords = CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 )
api . autosuggest ( text : " flottons.annulons.garço " , options : W3WOption . focus ( coords ) ) { ( suggestions , error ) in
print ( suggestions ?? " " )
} 关注 (51.4243877,-0.34745)，并使用多个选项对象剪辑到 UK：
let coords = CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 )
let options = W3WOptions ( ) . focus ( coords ) . clipToCountry ( " GB " )
api . autosuggest ( text : " flottons.annulons.garço " , options : options ) { ( suggestions , error ) in
print ( suggestions ?? " " )
} 三词地址语音 API 允许用户在任何应用程序或服务中说出三个单词，并返回可配置的三词地址建议列表，所有这一切都通过单个 API 调用完成。
为了使其发挥作用，您必须将语音 API 计划添加到您的帐户。
此示例实例化一个W3WMicrophone ，它向autosuggest(audio:)提供音频流，autosuggest(audio:) 会在调用autosuggest时开始录制。有关W3WMicrophone和自定义您自己的W3WAudioStream以进行autosuggest(audio:)的信息，请参阅 VoiceAPI 自述文件。
// make a microphone
let microphone = W3WMicrophone ( )
// call autosuggest
api . autosuggest ( audio : microphone , options : . voiceLanguage ( W3WApiLanguage ( locale : " en " ) ) ) { suggestions , error in
for suggestion in suggestions ?? [ ] {
print ( suggestion . words ?? " no suggestions " )
}
}此外， W3WMicrophone有一个回调闭包W3WMicrophone.volumeUpdate: (Double) -> () ，它提供了对动画用户反馈有用的幅度信息。请参阅语音 API 示例，更多信息可在 VoiceAPI 自述文件中找到。
此函数返回基于文本的autosuggest(text:)调用当前支持的语言。它将返回两个字母代码 (ISO 639) 以及该语言和英语的语言名称。
从convertTo3wa方法返回的值在 What3words REST API 文档中进行了描述
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
}对于可用的语音 API 语言，请调用api.availableVoiceLanguages(completion:) ，其工作方式完全相同。
返回给定区域的 3m x 3m 三词地址网格的一部分。请求的盒子从一个角到另一个角不能超过4公里，否则将返回BadBoundingBoxTooBig错误。纬度必须 >= -90 且 <= 90，但经度允许环绕 180。要指定穿过反子午线的边界框，请使用大于 180 的经度。示例值：50.0、179.995、50.01、180.0005 。
网格返回为[W3WLine]?每个W3WLine包含一个start和end变量，均为CLLocationCoordinate2D类型。
从gridSection函数返回的值在 What3words REST API 文档中进行了描述
let southWest = CLLocationCoordinate2D ( latitude : 52.208867 , longitude : 0.117540 )
let northEast = CLLocationCoordinate2D ( latitude : 52.207988 , longitude : 0.116126 )
api . gridSection ( southWest : southWest , northEast : northEast ) { ( lines , error ) in
for line in lines ?? [ ] {
print ( line . start , " -> " , line . end )
}
} 这些是一些将搜索或验证三字地址的函数。
通过正则表达式检查文本是否遵循三字地址的形式，即单词后跟分隔符，后跟单词，后跟分隔符，后跟单词。单词被定义为属于任何书写系统的一系列字母。这并不能验证该地址是否是地球上的真实位置，只是它遵循文本形式。例如，xx.xx.xx 会通过此测试，即使它不是有效地址。
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}这将打印结果，因为即使“abc.def.ghi”不是有效的三字地址，但它仍然符合[字][分隔符][字][分隔符][字]的形式。
验证文本是否是有效的三字地址，可以成功代表地球上的一个正方形。这会调用 API 进行验证。其他验证函数仅在本地运行正则表达式。
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} 在文本块中查找任意数量的可能的三字地址。术语“可能的三字地址”是指与 isPossible3wa() 中使用的正则表达式匹配的文本，也就是说，这些文本似乎是三字地址，但尚未针对引擎验证是否代表实际位置在地球上。
let twas = api . findPossible3wa ( text : " This is a filled.count.soap sentence with index.home.raft fun in it nowhere near grilled.cheese.sandwhich " )
print ( twas )这将打印出： ["filled.count.soap", "index.home.raft", "grilled.cheese.sandwhich"]
所有函数都调用完成块，并将error作为第二个参数。所有 Swift What3words error都是W3WError并符合CustomStringConvertible ，因此它们可以与String(describing: error)一起使用，并且它们当然也符合Error ：
api . convertTo3wa ( coordinates : CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 ) ) { square , error in
if let e = error {
print ( String ( describing : e ) )
} else {
print ( square ? . words ?? " " )
}
} API 调用错误的类型为W3WError枚举，语音autosuggest调用返回W3WVoiceError枚举。
还有一个可以离线工作的 SDK。更多信息请点击此处。
SDK 可以与此 API 包装器互换使用。也就是说，您可以使用此 API 包装器启动您的项目，并且稍后可以通过对代码进行最少的更改来升级到 SDK。
下表显示了哪个 SDK 版本与哪个 API 包装器版本兼容：
| w3w-swift-包装器 | SDK版本 |
|---|---|
| v3.8.2 及更低版本 | v3.8.0 及更低版本 |
| v3.9.0 及更高版本 | v4.0.0 及更高版本 |
