w3w swift wrapper
v4.0.1
Eine Swift-Bibliothek für die Interaktion mit der what3words REST API und VoiceAPI.
Der what3words Swift API-Wrapper ermöglicht Ihnen den programmgesteuerten Zugriff auf
Das Haupt-API-Swift-Wrapper-Objekt ist What3WordsV3 und bietet die oben genannte Funktionalität. Es gibt auch einen übergeordneten W3WAutosuggestHelper , der einen Großteil der Arbeit des Aufrufs der API für die Funktion zur automatischen Textfeld-Vorschlagserstellung übernimmt. Dies ist besonders hilfreich, wenn Sie what3words zu Ihrem vorhandenen Autovervollständigungscode hinzufügen möchten. Eine Anleitung finden Sie hier.
Weitere UI-Komponenten auf höherer Ebene finden Sie in unserer w3w-swift-components-Bibliothek auf GitHub, einschließlich W3WAutosuggestTextField , das UITextField um die Funktion zur automatischen Vervollständigung von Drei-Wörter-Adressen erweitert.
Hier finden Sie ein Schnellstart-Tutorial, das Ihnen die Einrichtung und den Betrieb mit den Grundlagen erleichtert.
Dieses Paket enthält auch eine Objective-C-kompatible Version, What3WordsObjC – siehe das ObjectiveC -Projekt in Examples/ObjectiveC/ObjectiveC.xcodeproj
Dieses Paket funktioniert mit:
Um diese Bibliothek nutzen zu können, benötigen Sie einen what3words-API-Schlüssel, für den Sie sich hier anmelden können. Wenn Sie die Voice-API-Aufrufe verwenden möchten, müssen Sie Ihrem Konto einen Voice-API-Plan hinzufügen.
Beispiele für dieses Paket finden Sie in unserem Beispiel-Repository: https://github.com/what3words/w3w-swift-samples
Sie können dies mit Swift Package Manager installieren, indem Sie in Ihren Projekteinstellungen die folgende URL zu Swift Packages hinzufügen:
https://github.com/what3words/w3w-swift-wrapper.git
Sie können CocoaPods verwenden, um den w3w-swift-wrapper zu installieren, indem Sie ihn dem Ziel in Ihrer Poddatei hinzufügen:
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
oder, wenn Sie sowohl die Bibliotheken W3WSwiftApi als auch W3WSwiftVoiceApi verwenden möchten:
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
pod 'W3WSwiftVoiceApi', :git => 'https://github.com/what3words/w3w-swift-voice-api.git'
Importieren Sie in jede Datei, in der Sie die What3words-API verwenden, Folgendes:
import W3WSwiftApi
import W3WSwiftVoiceApi
import CoreLocation
Verwenden Sie den folgenden Code mit Ihrem API-Schlüssel, um die API zu initialisieren:
let api = What3WordsV3 ( apiKey : " YourApiKey " )Falls Sie unseren Enterprise Suite API Server selbst betreiben, können Sie die URL zu Ihrem eigenen Server wie folgt angeben:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " ) Wenn Sie den Enterprise Suite API Server ausführen, gibt es außerdem einen weiteren optionalen setup() -Parameter: customHeaders . Verwenden Sie dies, wenn Sie benutzerdefinierte Header an Ihren eigenen Server senden müssen:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " , customHeaders : [ " x-header-1 " : " value-1 " , " x-header-2 " : " value-2 " ] )Jeder Aufruf benötigt als letzten Parameter einen Abschlussblock. Dadurch kann die Trailing-Closure-Syntax von Swift verwendet werden. Die Parameter des Abschlusses enthalten die Ergebnisse. Wenn bei einem Aufruf ein Problem auftritt, wird dies durch das Fehlerobjekt angezeigt.
Konvertieren Sie Koordinaten, ausgedrückt als Breiten- und Längengrad, in eine 3-Wörter-Adresse. Diese Funktion übernimmt den Breiten- und Längengrad als CLLocationCoordinate2D-Objekt. Die von der Methode convertTo3wa zurückgegebenen Werte werden in der API-Dokumentation beschrieben.
let coords = CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 )
api . convertTo3wa ( coordinates : coords , language : W3WApiLanguage ( locale : " en " ) ) { square , error in
print ( square ? . words ?? " " )
} Konvertieren Sie eine 3-Wörter-Adresse in geografische Koordinaten, dargestellt durch Breiten- und Längengrad. Diese Funktion verwendet den Wortparameter als Zeichenfolge aus drei Wörtern 'table.book.chair' . Die von der Methode convertToCoordinates zurückgegebenen Werte werden in der API-Dokumentation beschrieben.
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} Gibt eine Liste mit 3-Wort-Adressen basierend auf Benutzereingaben und anderen Parametern zurück.
Diese Methode bietet Korrekturen für die folgenden Arten von Eingabefehlern:
Die autosuggest -Methode ermittelt mögliche Korrekturen an der bereitgestellten 3-Wörter-Adresszeichenfolge basierend auf der Wahrscheinlichkeit der oben aufgeführten Eingabefehler und gibt eine Rangliste mit Vorschlägen zurück. Diese Methode kann auch die geografische Nähe möglicher Korrekturen zu einem bestimmten Standort berücksichtigen, um die zurückgegebenen Vorschläge weiter zu verbessern.
Wenn Sie über ein VoiceAPI-fähiges Konto verfügen, können Sie autosuggest auch mit Audiodaten zur Spracherkennung aufrufen. Damit dies funktioniert, müssen Sie Ihrem Konto einen Voice-API-Plan hinzufügen. Nachfolgend finden Sie ein Minimalbeispiel hierfür, detaillierte Informationen finden Sie hier
Sie erhalten nur dann Ergebnisse zurück, wenn die teilweise aus drei Wörtern bestehende Adresszeichenfolge, die Sie übermitteln, die ersten beiden Wörter und mindestens das erste Zeichen des dritten Wortes enthält; andernfalls wird eine Fehlermeldung zurückgegeben.
Um zu überprüfen, ob Ihre Adresszeichenfolge dem erforderlichen Format entspricht, bieten wir eine einfache Funktion namens isPossible3wa an. Diese Funktion verwendet unseren regulären Ausdruck, um potenzielle Drei-Wort-Adressen zu identifizieren und bestätigt nur, ob die Eingabe aus drei Wörtern besteht, die durch zwei what3words-Trennzeichen getrennt sind. Bitte beachten Sie, dass dadurch nicht überprüft wird, ob es sich bei der Eingabe um eine tatsächliche Drei-Wörter-Adresse in der Welt handelt. Die folgende if -Anweisung gibt 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")
}
Wenn Sie möchten, können Sie auch einfach unseren regulären Ausdruck verwenden. Beispielcode finden Sie in unserer Regex-Dokumentation.
Wir stellen verschiedene clip -Richtlinien zur Verfügung, damit Sie nach einem geografischen Gebiet filtern können. Wir empfehlen Ihnen, die Beschneidungsoptionen zu verwenden, um Ihrem Benutzer gezieltere Ergebnisse zu liefern. Sie können nach Land oder nach geografischem Feld, Kreis oder Polygon ausschneiden. Tun Sie dies über die W3WOptions und übergeben Sie es an den Autosuggest-Aufruf (siehe Beispiel unten).
Wenn Sie den aktuellen Standort Ihres Benutzers kennen, empfehlen wir Ihnen außerdem dringend , den Fokus zu verwenden, um wahrscheinlich relevantere Ergebnisse zurückzugeben. Tun Sie dies über die W3WOptions und übergeben Sie es an den Autosuggest-Aufruf (siehe Beispiel unten).
Die von der autosuggest -Methode zurückgegebenen Werte werden in der what3words-REST-API-Dokumentation beschrieben.
Der erste Parameter sind die partiellen drei Wörter oder Sprachdaten. Der zweite optionale Parameter sind die Optionen für die Autosuggest-Funktion. Der letzte Parameter ist der Abschlussblock.
api . autosuggest ( text : " filled.count.soa " ) { ( suggestions , error ) in
for suggestion in suggestions ?? [ ] {
print ( " ( suggestion . words ?? " " ) is near ( suggestion . nearestPlace ?? " " ) " )
}
} Konzentrieren Sie sich mit einer einzigen Option auf einen bestimmten Ort:
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 ?? " " )
} Konzentrieren Sie sich auf (51,4243877,-0,34745) und schneiden Sie es mithilfe des Objekts mit mehreren Optionen auf das Vereinigte Königreich ab:
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 ?? " " )
} Mit der Sprach-API von what3words kann ein Benutzer über einen einzigen API-Aufruf drei Wörter in eine beliebige Anwendung oder einen beliebigen Dienst sagen und dabei eine konfigurierbare Liste mit Adressvorschlägen von what3words zurückgeben.
Damit dies funktioniert, müssen Sie Ihrem Konto einen Voice-API-Plan hinzufügen.
In diesem Beispiel wird ein W3WMicrophone instanziiert, das einen Audiostream für autosuggest(audio:) bereitstellt, der mit der Aufnahme beginnt, wenn autosuggest aufgerufen wird. Informationen zu W3WMicrophone und zum Anpassen Ihres eigenen W3WAudioStream für autosuggest(audio:) finden Sie in der VoiceAPI-README-Datei.
// 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 " )
}
} Außerdem verfügt W3WMicrophone über einen Callback-Abschluss W3WMicrophone.volumeUpdate: (Double) -> () , der Amplitudeninformationen bereitstellt, die für die Animierung von Benutzerfeedback nützlich sind. Sehen Sie sich das Voice-API-Beispiel an. Weitere Informationen finden Sie in der VoiceAPI-README-Datei.
Diese Funktion gibt die derzeit unterstützten Sprachen für textbasierte autosuggest(text:) -Aufrufe zurück. Es werden der Zwei-Buchstaben-Code (ISO 639) und der Name der Sprache sowohl in dieser Sprache als auch in Englisch zurückgegeben.
Die von der Methode convertTo3wa zurückgegebenen Werte werden in der Dokumentation zur what3words-REST-API beschrieben
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} Für die verfügbaren Sprach-API-Sprachen rufen Sie api.availableVoiceLanguages(completion:) auf, was genauso funktioniert.
Gibt einen Abschnitt des 3 x 3 m großen what3words-Rasters für einen bestimmten Bereich zurück. Die angeforderte Box darf von Ecke zu Ecke nicht länger als 4 km sein, sonst wird ein BadBoundingBoxTooBig-Fehler zurückgegeben. Breitengrade müssen >= -90 und <= 90 sein, Längengrade dürfen jedoch um 180 umlaufen. Um einen Begrenzungsrahmen anzugeben, der den Antimeridian kreuzt, verwenden Sie einen Längengrad größer als 180. Beispielwert: 50,0, 179,995, 50,01, 180,0005 .
Das Raster wird als [W3WLine]? und jede W3WLine enthält eine start und end , beide vom Typ CLLocationCoordinate2D .
Die von der Funktion gridSection zurückgegebenen Werte werden in der Dokumentation zur what3words-REST-API beschrieben
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 )
}
} Dies sind einige Funktionen, die Drei-Wort-Adressen suchen oder validieren.
Überprüfen Sie, ob der Text per Regex der Form einer Adresse mit drei Wörtern folgt, d. h. einem Wort, gefolgt von einem Trennzeichen, gefolgt von einem Wort, gefolgt von einem Trennzeichen, gefolgt von einem Wort. Ein Wort ist definiert als eine Reihe von Buchstaben, die zu einem beliebigen Schriftsystem gehören. Dies bestätigt nicht, dass es sich bei der Adresse um einen realen Ort auf der Erde handelt, sondern nur darum, dass sie der Textform eines solchen folgt. Beispielsweise würde xx.xx.xx diesen Test bestehen, obwohl es keine gültige Adresse ist.
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}Dies würde das Ergebnis ausdrucken, denn auch wenn „abc.def.ghi“ keine gültige Adresse mit drei Wörtern ist, passt sie dennoch in die Form [Wort][Trennzeichen][Wort][Trennzeichen][Wort].
Überprüft, ob der Text eine gültige Adresse mit drei Wörtern ist, die erfolgreich ein Quadrat auf der Erde darstellt. Dadurch wird zur Überprüfung ein Aufruf an die API durchgeführt. Die anderen Validierungsfunktionen führen einen regulären Ausdruck nur lokal aus.
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} Findet eine beliebige Anzahl möglicher Drei-Wort-Adressen in einem Textblock. Der Begriff „mögliche Drei-Wort-Adressen“ bezieht sich auf Text, der mit dem in isPossible3wa() verwendeten regulären Ausdruck übereinstimmt, d auf der Erde.
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 ) Dies wird ausgedruckt: ["filled.count.soap", "index.home.raft", "grilled.cheese.sandwhich"]
Alle Funktionen rufen den Abschlussblock mit error als zweitem Parameter auf. Alle Swift what3words- error sind W3WError und konform mit CustomStringConvertible , sodass sie mit String(describing: error) verwendet werden können, und sie entsprechen natürlich auch 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-Aufruffehler sind vom Typ W3WError -Enumeration und der Sprach- autosuggest -Aufruf gibt eine W3WVoiceError Enumeration zurück.
Es gibt auch ein SDK, das offline funktioniert. Weitere Informationen finden Sie hier.
Das SDK kann austauschbar mit diesem API-Wrapper verwendet werden. Das heißt, Sie können Ihr Projekt mit diesem API-Wrapper starten und später mit minimalen Änderungen an Ihrem Code ein Upgrade auf das SDK durchführen.
Nachfolgend finden Sie eine Tabelle, welche SDK-Version mit welcher API-Wrapper-Version kompatibel ist:
| w3w-swift-wrapper | SDK-Version |
|---|---|
| v3.8.2 und niedriger | v3.8.0 und niedriger |
| v3.9.0 und höher | v4.0.0 und höher |
