W3WSwiftApi 3.9.6

W3WSwiftApi 3.9.6

×

由 what3words 维护。

W3WSwiftApi 3.9.6

  • 由
  • what3words

what3words

what3words w3w-swift-wrapper

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

概述

what3words Swift API 包装器使您能够

  • 将 3 字地址转换为坐标
  • 将坐标转换为 3 字地址
  • 自动建议功能，它将一个略有错误的 3 字地址作为输入，并建议一系列有效的 3 字地址
  • 获取 3mx3m what3words 网格的某个部分（用于边界框）
  • 确定目前支持的 3 字地址语言
  • 自动建议功能将（通过语音API）听到的 3 字地址转换为一系列有效的 3 字地址

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

甚至更高级的 UI 功能可以在我们的 UI 组件库中找到，该库位于 GitHub 上的 w3w-swift-components。值得注意的是，我们的 W3WAutosuggestTextField 继承自 UITextField，并添加了三字地址自动完成功能。

SOE（总结说明）

您可以在这里找到一个简短的教程，它将向您展示如何设置和运行。

Objective-C

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

操作系统要求

此包与以下操作系统兼容

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

身份验证

使用此库，您需要一个 what3words API 密钥，您可以通过 这里 注册获取。如果您希望使用语音 API 调用，则必须将语音 API 计划添加到您的 帐户 中。

示例

此包中的示例

macOS 终端

一个在 macOS 终端上演示 convertToCoordinates 的示例位于
Examples/ConvertToCoords/ConvertToCoords.xcodeproj

iOS UIKit 语音 API

一个使用语音API的 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

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

iOS SwiftUI Autosuggest Helper

使用 W3WAutosuggestHelper 创建一个带有建议列表的自动完成的 TextField 的 SwiftUI 示例。
Examples/AutosuggestHelperSwiftUI/AutosuggestHelperSwiftUI.xcodeproj

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

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

安装

Swift 包管理器

您可以使用 Swift 包管理器 安装此软件包，方法是在项目的设置下将以下 URL 添加到 "Swift Packages"。

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

CocoaPods (iOS 9+, OS X 10.10+)

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

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

XCFramework

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

使用方法

导入

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

import W3WSwiftApi
import CoreLocation
注意
  • 如果您正在使用 CocoaPods，则使用 import what3words 代替。
  • 如果您在设备上使用此软件包的 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 字段地址

将坐标（作为纬度和经度表示）转换为 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 字段地址。

此方法为以下类型的输入错误提供纠正措施

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

该方法根据上面的输入错误的可能性确定对提供的 3 字段地址字符串的可能更正，并返回一个按排名排列的建议清单。此方法还可以考虑可能更正与指定位置的地理邻近性，以进一步提高返回的建议的质量。

  • 语音

如果您的账户启用了VoiceAPI，您还可以使用音频数据进行语音识别，调用autosuggest。为了使此功能正常工作，您必须在您的账户中添加Voice API计划。以下是一个简单的示例，但详细的信息可以在这里找到。

输入3词地址

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

为了检查您的地址字符串是否符合这些标准，我们提供了一个简单的函数，它采用我们的正则表达式来帮助您识别3词地址。它被称为isPossible3wa，但请注意，它仅表示输入是否由三个由w3w分隔符分隔的潜在单词组成。它不会告诉您它是否是真实的三词地址。以下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 ?? "")
}

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:)调用所支持的当前语言。它将返回两位字母代码（《a href="https://en.wikipedia.org/wiki/ISO_639" rel="nofollow”>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 what3words网格的一部分。请求的框对角线距离不得超过4km，否则将返回"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)
  }
}

验证函数

这些是一些用于搜索或验证三个单词地址的函数。

isPossible3wa(text: String) -> Bool

通过正则表达式检查文本是否遵循三个单词地址的格式，即单词后面跟着分隔符，然后是另一个单词，后面再跟一个分隔符，最后是另一个单词。单词被定义为属于任何书写系统的字母序列。这并不验证地址确实是地球上真实的位置，只是验证它符合一个地址的文本格式。例如，xx.xx.xx即使不是有效地址，也会通过此测试。

if api.isPossible3wa(text: "abc.def.ghi") {
  print("does match the text pattern for a three word address")
}

即使"abc.def.ghi"不是一个有效的三个单词地址，它仍然符合[单词][分隔符][单词][分隔符][单词]的形式，因此会打印出结果。

isValid3wa(words: String, completion: @escaping (Bool) -> (

)

验证文本是否为有效的三个单词地址，该地址成功表示地球上的一个正方形。这会调用API进行验证。其他验证函数只在本地进行正则表达式运行。

api.isValid3wa(words: "filled.count.soap") { valid in
  if valid {
    print("the address provided is a real address somewhere on earth")
  }
}

findPossible3wa(text: String) -> [String]

在一个文本块中查找任意数量的可能三个单词地址。术语"可能的三个单词地址"指文本匹配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类型都是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包装器版本兼容性的表格

w3w-swift-wrapper SDK版本
v3.8.2及以下 v3.8.0及以下
v3.9.0及以上 v4.0.0及以上