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 的經度。
網格返回為[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 及更高版本 |
