w3w-swift-wrapper

一个 Swift 库，用于使用 what3words REST API 和 what3words VoiceAPI。

概述

what3words Swift API 包装器为您提供了程序化的访问方式：

• 将 3 个单词地址转换为坐标
• 将坐标转换为 3 个单词地址
• 自动建议功能，可以接受一个略微不正确的 3 个单词地址，并提供一系列有效 3 个单词地址的建议
• 获取一个 3m x 3m what3words 格子的部分。
• 确定当前支持 3 个单词地址的语言。
• 自动建议功能将语音 API 转换的语音 3 个单词地址转换为一系列有效的 3 个单词地址

主要API Swift包装对象是What3WordsV3，并提供上述功能。还有更高层次的W3WAutosuggestHelper，它可以进行大量调用API的文本字段自动提示功能的操作。如果您想将what3words添加到现有的自动完成代码中，这将非常有帮助。教程可以在这里找到。

更高级的UI功能可以在我们的UI组件库中找到，即w3w-swift-components，可在GitHub上找到。特别值得注意的是我们的W3WAutosuggestTextField继承自UITextField，并添加了三个单词地址自动完成功能。

TLDR

您可以在这里找到一份简短的教程，它将展示如何以最小化配置和启动。

Objective-C

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

OS Requirements

此包与

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

Authentication

要使用此库，您需要一个what3words API密钥，可以在此处注册。如果您想使用语音API调用，则必须将语音API方案添加到您的账户。

示例

此包中的示例

macOS终端

使用convertToCoordinates的macOS终端示例位于
Examples/ConvertToCoords/ConvertToCoords.xcodeproj

iOS UIKit 语音API

使用VoiceAPI的iOS UIKit示例位于
Examples/VoiceAPI/VoiceAPI.xcodeproj

iOS UIKit 网格线

使用MapKit在地图上显示what3words网格线的iOS示例
Examples/GridLines/GridLines.xcodeproj

Objective-C

使用Objective-C的一个示例。
Examples/ObjectiveC/ObjectiveC.xcodeproj

iOS SwiftUI

一个非常简单的SwiftUI示例，调用autosuggest并显示结果。
Examples/AutoSuggest/AutoSuggest.xcodeproj

iOS SwiftUI Autosuggest Helper

一个使用W3WAutosuggestHelper来创建在List中建议的自动完成TextField的SwiftUI示例。
Examples/AutosuggestHelperSwiftUI/AutosuggestHelperSwiftUI.xcodeproj

使用Autosuggest Helper增强您的自动完成功能

一个使用W3WAutosuggestHelper增强另一个地址数据源的iOS示例。换句话说，它展示了如何将what3words与其他地址服务结合使用。示例使用Apple的MKLocalSearchCompleter并将其结果与what3words建议混合。
Examples/AutosuggestPlusYourData/AutosuggestPlusYourData.xcodeproj

安装

Swift 包管理器

您可以使用 Swift 包管理器 安装它，只需将以下 URL 添加到项目设置的 Swift 包中

https://github.com/what3words/w3w-swift-wrapper.git

CocoaPods (iOS 9+, OS X 10.10+)

您可以使用 CocoaPods 通过将其添加到 Podfile 中的目标来安装 w3w-swift-wrapper

pod 'what3words', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'

如果您正在使用 CocoaPods，请在 Swift 文件中使用 import what3words 代替 import W3WSwiftApi。

XCFramework

有一个名为 build.sh 的脚本可以运行，将代码构建为 XCFramework。它使用所包含的 w3w-swift-wrapper.xcodeproj。

使用方法

导入

在任何使用what3words API的文件中，导入以下内容

import W3WSwiftApi
import CoreLocation

注意

• 如果您使用CocoaPods，请使用 import what3words 代替。
• 如果您在设备上使用本包的语音API功能，应包含麦克风权限

初始化

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

let api = What3WordsV3(apiKey: "YourApiKey")

如果您自行运行我们的企业套件API服务器，您可以这样指定您自己的服务器URL

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

此外，如果您运行企业套件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词地址

将纬度和经度表示的坐标转换为3词地址。此功能接受纬度和经度作为CLLocationCoordinate2D对象。从convertTo3wa方法返回的值在API文档中描述。

代码示例

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

转换为坐标

将3词地址转换为位置，表示为纬度和经度的坐标。此函数接受单词参数作为包含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词地址

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

为了检查您的地址字符串是否符合此标准，我们提供了一个简单的函数，该函数使用我们的正则表达式来帮助您识别3词地址。它被称为isPossible3wa，但请注意，它仅指示输入是否为三个由w3w分隔符分隔的潜在单词。它不会告诉您它是否是真实世界的3词地址。以下示例中，以下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 实现，并将其传递到自动建议调用中（见下面的示例）。

autosuggest 方法返回的值请参考what3words REST API 文档。

使用方法

第一个参数是部分三词，或语音数据。第二个可选参数是自动建议功能的选项。最后一个参数是完成块。

示例一

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

VoiceAPI 示例

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

为了实现这一点，您必须向您的帐户添加 Voice API 计划。

此示例创建了一个 W3WMicrophone 对象，该对象提供了一个音频流到 autosuggest(audio:)，当调用 autosuggest 时开始录音。有关 W3WMicrophone 和为 autosuggest(audio:) 定制自己的 W3WAudioStream 的信息，请参阅 VoiceAPI README。

// make a microphone
let microphone = W3WMicrophone()

// call autosuggest
api.autosuggest(audio: microphone, language: "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)
  }
}

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

网格部分

按指定区域返回3米 x 3米的what3words网格的一部分。请求的盒子面积不得超过从角到角4公里，否则将返回BadBoundingBoxTooBig错误。纬度必须 >= -90 且 <= 90，但经度可以绕180度折回。要指定跨越子午线的边界框，请使用大于180度的经度。例如：50.0, 179.995, 50.01, 180.0005。

网格以 [W3WLine]?形式返回，其中每个 W3WLine 包含一个类型为 CLLocationCoordinate2D 的 start 和 end 变量。

代码示例

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

错误处理

所有函数都将 error 作为第二个参数调用完成块。所有 Swift what3words 的 error 类型都是 enum 类型，并遵循 CustomStringConvertible 协议，因此可以使用 String(describing: 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。更多信息请参见这里。

SDK 可以与 API 包装器互换使用。也就是说，您可以使用此 API 包装器开始您的项目，之后可以最小更改代码即可升级到 SDK。

下表列出了哪个 SDK 版本与哪个 API 包装器版本兼容