w3w swift wrapper
v4.0.1
what3words REST API および VoiceAPI と対話するための Swift ライブラリ。
what3words Swift API ラッパーを使用すると、プログラムによるアクセスが可能になります。
メイン API の Swift ラッパー オブジェクトはWhat3WordsV3で、上記の機能を提供します。テキスト フィールドの自動提案機能の API を呼び出す多くの作業を実行する、より高レベルのW3WAutosuggestHelperもあります。これは、既存のオートコンプリート コードに what3words を追加する場合に特に役立ちます。チュートリアルはここにあります。
さらに高レベルの UI コンポーネントについては、GitHub の w3w-swift-components ライブラリを確認してください。これには、 UITextFieldを拡張して 3 単語のアドレス オートコンプリート機能を追加するW3WAutosuggestTextFieldが含まれます。
基本をセットアップして実行するのに役立つクイックスタート チュートリアルがここにあります。
このパッケージには、Objective-C 互換バージョンであるWhat3WordsObjCも含まれています。Examples/ObjectiveC/ObjectiveC.xcodeproj のObjectiveCプロジェクトを参照してください。
このパッケージは以下で動作します。
このライブラリを使用するには、what3words API キーが必要です。これは、ここでサインアップできます。 Voice API 呼び出しを使用したい場合は、Voice API プランをアカウントに追加する必要があります。
このパッケージの例は、サンプル リポジトリにあります: https://github.com/what3words/w3w-swift-samples
以下の URL をプロジェクト設定の Swift Packages に追加することで、Swift Package Manager を使用してこれをインストールできます。
https://github.com/what3words/w3w-swift-wrapper.git
CocoaPods を使用して、Podfile のターゲットにw3w-swift-wrapperインストールできます。
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 ワードのアドレスに変換します。この関数は、緯度と経度を CLLocationCoowned2D オブジェクトとして受け取ります。 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 単語のアドレス文字列の一部に最初の 2 単語と、少なくとも 3 番目の単語の最初の文字が含まれている場合にのみ、結果が返されます。それ以外の場合は、エラー メッセージが返されます。
アドレス文字列が必要な形式を満たしているかどうかを確認するために、 isPossible3waという単純な関数が提供されています。この関数は、正規表現を使用して潜在的な 3 ワードのアドレスを識別し、入力が 2 つの what3words 区切り文字で区切られた 3 つのワードで構成されているかどうかのみを確認します。入力が実際の 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経由で実行し、autosuggest 呼び出しに渡します (以下の例を参照)。
ユーザーの現在位置がわかっている場合は、フォーカスを使用して、より関連性の高い結果を返すことも強くお勧めします。これをW3WOptions経由で実行し、autosuggest 呼び出しに渡します (以下の例を参照)。
autosuggestメソッドから返される値については、what3words REST API ドキュメントで説明されています。
最初のパラメータは、部分的な 3 つの単語または音声データです。 2 番目のオプションのパラメーターは、autosuggest 関数のオプションです。最後のパラメータは完了ブロックです。
api . autosuggest ( text : " filled.count.soa " ) { ( suggestions , error ) in
for suggestion in suggestions ?? [ ] {
print ( " ( suggestion . words ?? " " ) is near ( suggestion . nearestPlace ?? " " ) " )
}
} 単一のオプションを使用して、特定の 1 つの場所に焦点を当てます。
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 ?? " " )
} what3words Voice API を使用すると、ユーザーは任意のアプリケーションまたはサービスに 3 つの単語を言うことができ、すべて 1 回の API 呼び出しを通じて、what3words のアドレス候補の構成可能なリストが返されます。
これを機能させるには、アカウントに Voice API プランを追加する必要があります。
この例では、 autosuggestが呼び出されたときに録音を開始するautosuggest(audio:)にオーディオ ストリームを提供するW3WMicrophoneインスタンス化します。 W3WMicrophoneとautosuggest(audio:)用の独自のW3WAudioStreamのカスタマイズについては、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:)呼び出しで現在サポートされている言語を返します。 2 文字のコード (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 グリッドのセクションを返します。要求されたボックスは隅から隅まで 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 )
}
} これらは、3 つのワード アドレスを検索または検証するいくつかの関数です。
テキストが正規表現による 3 単語アドレスの形式に従っているかどうかを確認します。つまり、単語の後に区切り文字が続き、単語が続き、その後に区切り文字が続き、その後に単語が続きます。単語は、任意の書記体系に属する一連の文字として定義されます。これは、住所が地球上の実際の場所であることを検証するものではなく、単に住所のテキスト形式に従っているというだけです。たとえば、xx.xx.xx は、有効なアドレスではない場合でも、このテストに合格します。
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}「abc.def.ghi」は有効な 3 単語のアドレスではありませんが、[単語][区切り文字][単語][区切り文字][単語] という 1 つの形式に適合するため、これにより結果が出力されます。
テキストが地球上の正方形を正しく表す有効な 3 ワードのアドレスであることを検証します。これにより、検証のために API が呼び出されます。他の検証関数は正規表現をローカルでのみ実行します。
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} テキストのブロック内で可能な 3 つの単語のアドレスを任意の数検索します。 「可能な 3 ワードのアドレス」という用語は、isPossible3wa() で使用される正規表現に一致するテキストを指します。つまり、これらは 3 ワードのアドレスのように見えますが、実際の場所を表すものとしてエンジンに対して検証されていないテキストです。地球上で。
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"]
すべての関数は、2 番目のパラメーターとして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-wrapper | SDKのバージョン |
|---|---|
| v3.8.2 以下 | v3.8.0以下 |
| v3.9.0以降 | v4.0.0以降 |
