用于与 what3words REST API 和 VoiceAPI 交互的 Swift 库。

what3words Swift API 封装器让您能够以编程方式访问以下功能：

• 将 3 词地址转换为坐标
• 将坐标转换为 3 词地址
• 自动建议功能，可以接收略微不正确的 3 词地址，并建议一系列有效的 3 词地址
• 获取边界框内 3m x 3m what3words 网格的一部分。
• 确定当前支持的 3 词地址语言。
• 自动建议功能，用于将口语化的 3 词地址（通过 voiceAPI）转换为一系列有效的 3 词地址

主要的 API swift 封装器对象是 What3WordsV3，它提供上述功能。还有一个更高级别的 W3WAutosuggestHelper，它完成了大量调用 API 以实现文本字段自动建议功能的工作。如果您想将 what3words 添加到现有的自动完成代码中，这将特别有帮助。教程可以在这里找到。

对于更高级别的 UI 组件，请查看我们在 GitHub 上的 w3w-swift-components 库，其中包括 W3WAutosuggestTextField，它扩展了 UITextField 以添加三词地址自动完成功能。

您可以在这里找到快速入门教程，以帮助您设置并运行基本功能。

此软件包还包含一个 Objective-C 兼容版本 What3WordsObjC - 请参阅 Examples/ObjectiveC/ObjectiveC.xcodeproj 中的 ObjectiveC 项目

此软件包适用于：

• macOS 10.11 或更高版本
• iOS 9 或更高版本
• tvOS 9 或更高版本
• watchOS 2 或更高版本

要使用此库，您需要一个 what3words API 密钥，您可以在这里注册。如果您希望使用 Voice API 调用，则必须在您的 帐户中添加 Voice 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 中的 target

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

• 如果您在设备上使用此软件包的 Voice API 功能，则应包含麦克风权限

使用以下代码和您的 API 密钥来初始化 API

let api = What3WordsV3(apiKey: "YourApiKey")

如果您自己运行 Enterprise Suite API 服务器，您可以像这样指定您自己的服务器的 URL

let api = What3WordsV3(apiKey: "YourApiKey", apiUrl: "https://api.yourserver.com")

此外，如果您运行 Enterprise Suite API 服务器，则还有另一个可选的 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 词地址。此函数将纬度和经度作为 CLLocationCoordinate2D 对象。从 convertTo3wa 方法返回的值在 API 文档中描述。

let coords = CLLocationCoordinate2D(latitude: 51.4243877, longitude: -0.34745)
api.convertTo3wa(coordinates: coords, language: W3WApiLanguage(locale: "en")) { square, error in
    print(square?.words ?? "")
}

将 3 词地址转换为地理坐标，以纬度和经度表示。此函数将 words 参数作为 3 个单词的字符串 'table.book.chair'。从 convertToCoordinates 方法返回的值在 API 文档中描述。

api.convertToCoordinates(words: "filled.count.soap") { square, error in
  print(square?.coordinates ?? "")
}

根据用户输入和其他参数返回 3 词地址列表。

此方法为以下类型的输入错误提供更正：

• 打字错误
• 拼写错误
• 记错的单词（例如，单数与复数）
• 单词顺序错误

autosuggest 方法根据上述输入错误的概率确定对提供的 3 词地址字符串的可能更正，并返回建议的排名列表。此方法还可以考虑给定位置的可能更正的地理邻近性，以进一步改进返回的建议。

• 语音

如果您拥有启用 VoiceAPI 的帐户，您还可以使用音频数据调用 autosuggest 以进行语音识别。为此，您必须在您的帐户中添加 Voice API 计划。下面有一个最简单的示例，但详细信息可以在这里找到

只有当您提交的部分 3 词地址字符串包含前两个单词和第三个单词的至少第一个字符时，您才会收到结果；否则将返回错误消息。

为了验证您的地址字符串是否符合要求的格式，我们提供了一个名为 isPossible3wa 的简单函数。此函数使用我们的正则表达式来识别潜在的三词地址，仅确认输入是否由三个单词组成，单词之间用两个 what3words 分隔符分隔。请注意，它不验证输入是否是世界上实际的三词地址。以下 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 执行此操作，并将其传递到 autosuggest 调用中（请参阅下面的示例）。

如果您知道用户的当前位置，我们还强烈建议您使用焦点来返回可能更相关的结果。通过 W3WOptions 执行此操作，并将其传递到 autosuggest 调用中（请参阅下面的示例）

从 autosuggest 方法返回的值在 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)，并使用多个选项对象裁剪到英国

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 ?? "")
}

what3words Voice API 允许用户在任何应用程序或服务中说出三个单词，并通过单个 API 调用返回可配置的 what3words 地址建议列表。

为了使此功能正常工作，您必须在您的帐户中添加 Voice API 计划。

此示例实例化了一个 W3WMicrophone，它为 autosuggest(audio:) 提供音频流，后者在调用 autosuggest 时开始录制。有关 W3WMicrophone 和自定义您自己的 W3WAudioStream 以用于 autosuggest(audio:) 的信息，请参阅 VoiceAPI README。

// 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) -> ()，它提供振幅信息，可用于动画用户反馈。请参阅 Voice API 示例，更多信息请参见 VoiceAPI README。

此函数返回当前支持的用于基于文本的 autosuggest(text:) 调用的语言。它将返回两个字母的代码 (ISO 639) 以及该语言和英语的语言名称。

从 convertTo3wa 方法返回的值在 what3words REST API 文档中描述

api.availableLanguages() { (languages, error) in
  for language in languages ?? [] {
    print(language.code, language.name, language.nativeName)
  }
}

对于可用的 Voice API 语言，请调用 api.availableVoiceLanguages(completion:)，其工作方式完全相同。

返回给定区域的 3m x 3m what3words 网格的一部分。请求的框的对角线不得超过 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 封装器版本兼容