w3w swift wrapper
v4.0.1
Une bibliothèque Swift pour interagir avec l'API REST what3words et VoiceAPI.
Le wrapper de l'API What3words Swift vous donne un accès programmatique à
L'objet principal du wrapper Swift de l'API est What3WordsV3 et fournit la fonctionnalité ci-dessus. Il existe également un W3WAutosuggestHelper de niveau supérieur qui effectue une grande partie du travail d'appel de l'API pour la fonctionnalité de suggestion automatique des champs de texte. Ceci est particulièrement utile si vous souhaitez ajouter what3words à votre code de saisie semi-automatique existant. Un tutoriel peut être trouvé ici.
Pour des composants d'interface utilisateur de niveau encore plus élevé, consultez notre bibliothèque w3w-swift-components sur GitHub, y compris W3WAutosuggestTextField qui étend UITextField pour ajouter une fonctionnalité de saisie semi-automatique d'adresse de trois mots.
Vous pouvez trouver ici un didacticiel de démarrage rapide pour vous aider à configurer et à utiliser les bases.
Ce package contient également une version compatible Objective-C, What3WordsObjC - voir le projet ObjectiveC dans Exemples/ObjectiveC/ObjectiveC.xcodeproj
Ce package fonctionne avec :
Pour utiliser cette bibliothèque, vous aurez besoin d'une clé API what3words, pour laquelle vous pouvez vous inscrire ici. Si vous souhaitez utiliser les appels Voice API, vous devez ajouter un plan Voice API à votre compte.
Des exemples de ce package peuvent être trouvés dans notre référentiel d'exemples : https://github.com/what3words/w3w-swift-samples
Vous pouvez l'installer avec Swift Package Manager en ajoutant l'URL ci-dessous aux packages Swift dans les paramètres de votre projet :
https://github.com/what3words/w3w-swift-wrapper.git
Vous pouvez utiliser CocoaPods pour installer le w3w-swift-wrapper en l'ajoutant à la cible dans votre Podfile :
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
ou, si vous souhaitez utiliser à la fois les bibliothèques W3WSwiftApi et W3WSwiftVoiceApi :
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
pod 'W3WSwiftVoiceApi', :git => 'https://github.com/what3words/w3w-swift-voice-api.git'
Dans n'importe quel fichier dans lequel vous utilisez l'API What3words, importez les éléments suivants :
import W3WSwiftApi
import W3WSwiftVoiceApi
import CoreLocation
Utilisez le code suivant avec votre clé API pour initialiser l'API :
let api = What3WordsV3 ( apiKey : " YourApiKey " )Dans le cas où vous exécutez vous-même notre serveur API Enterprise Suite, vous pouvez spécifier l'URL de votre propre serveur comme suit :
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " ) De plus, si vous exécutez le serveur API Enterprise Suite, il existe un autre paramètre setup() facultatif : customHeaders . Utilisez ceci si vous devez envoyer des en-têtes personnalisés à votre propre serveur :
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " , customHeaders : [ " x-header-1 " : " value-1 " , " x-header-2 " : " value-2 " ] )Chaque appel prend un bloc de complétion comme dernier paramètre. Cela permet d'utiliser la syntaxe de fermeture finale de Swift. Les paramètres de la fermeture contiennent les résultats. S'il y a un problème avec un appel, il sera indiqué par l'objet d'erreur.
Convertissez les coordonnées, exprimées en latitude et longitude, en une adresse de 3 mots. Cette fonction prend la latitude et la longitude comme objet CLLocationCoordonnée2D. Les valeurs renvoyées par la méthode convertTo3wa sont décrites dans la documentation de l'API.
let coords = CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 )
api . convertTo3wa ( coordinates : coords , language : W3WApiLanguage ( locale : " en " ) ) { square , error in
print ( square ? . words ?? " " )
} Convertissez une adresse de 3 mots en coordonnées géographiques, représentées par la latitude et la longitude. Cette fonction prend le paramètre mots sous la forme d'une chaîne de 3 mots 'table.book.chair' . Les valeurs renvoyées par la méthode convertToCoordinates sont décrites dans la documentation de l'API.
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} Renvoie une liste de 3 adresses de mots basées sur la saisie de l'utilisateur et d'autres paramètres.
Cette méthode fournit des corrections pour les types d'erreurs de saisie suivants :
La méthode autosuggest détermine les corrections possibles à apporter à la chaîne d'adresse de 3 mots fournie en fonction de la probabilité des erreurs de saisie répertoriées ci-dessus et renvoie une liste classée de suggestions. Cette méthode peut également prendre en compte la proximité géographique des corrections possibles avec un emplacement donné pour améliorer encore les suggestions renvoyées.
Si vous disposez d'un compte compatible VoiceAPI, vous pouvez également appeler autosuggest avec des données audio pour la reconnaissance vocale. Pour que cela fonctionne, vous devez ajouter un forfait Voice API à votre compte. Il y a un exemple minimal de ceci ci-dessous, mais des informations détaillées peuvent être trouvées ici
Vous ne recevrez les résultats que si la chaîne d'adresse partielle de 3 mots que vous soumettez contient les deux premiers mots et au moins le premier caractère du troisième mot ; sinon un message d'erreur sera renvoyé.
Pour vérifier si votre chaîne d'adresse répond au format requis, nous proposons une fonction simple appelée isPossible3wa . Cette fonction utilise notre regex pour identifier les adresses potentielles de trois mots, en confirmant uniquement si l'entrée se compose de trois mots séparés par deux séparateurs what3words. Veuillez noter qu'il ne valide pas si l'entrée est une véritable adresse de trois mots dans le monde. L'instruction if suivante retournera 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")
}
Ou si vous préférez, vous pouvez simplement utiliser notre regex. Un exemple de code peut être trouvé dans notre documentation sur les expressions régulières.
Nous proposons diverses politiques clip pour vous permettre de filtrer par zone géographique. Nous vous recommandons d'utiliser les options de découpage pour donner un ensemble de résultats plus ciblés à votre utilisateur. Vous pouvez découper par pays, ou par zone géographique, cercle ou polygone. Faites-le via W3WOptions et transmettez-le dans l'appel de suggestion automatique (voir l'exemple ci-dessous).
Si vous connaissez l'emplacement actuel de votre utilisateur, nous vous recommandons également fortement d'utiliser focus pour renvoyer des résultats probablement plus pertinents. Faites-le via W3WOptions et transmettez-le dans l'appel de suggestion automatique (voir exemple ci-dessous)
Les valeurs renvoyées par la méthode autosuggest sont décrites dans la documentation de l'API REST what3words.
Le premier paramètre correspond aux trois mots partiels ou données vocales. Le deuxième paramètre facultatif concerne les options de la fonction de suggestion automatique. Le dernier paramètre est le bloc de complétion.
api . autosuggest ( text : " filled.count.soa " ) { ( suggestions , error ) in
for suggestion in suggestions ?? [ ] {
print ( " ( suggestion . words ?? " " ) is near ( suggestion . nearestPlace ?? " " ) " )
}
} Concentrez-vous sur un endroit particulier en utilisant une seule option :
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 ?? " " )
} Concentrez-vous sur (51.4243877,-0.34745) et coupez vers le Royaume-Uni à l'aide de l'objet options multiples :
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 ?? " " )
} L'API vocale What3words permet à un utilisateur de prononcer trois mots dans n'importe quelle application ou service, en renvoyant une liste configurable de suggestions d'adresses What3words, le tout via un seul appel API.
Pour que cela fonctionne, vous devez ajouter un forfait Voice API à votre compte.
Cet exemple instancie un W3WMicrophone qui fournit un flux audio à autosuggest(audio:) qui commence l'enregistrement lorsque autosuggest est appelée. Pour plus d’informations sur W3WMicrophone et la personnalisation de votre propre W3WAudioStream pour autosuggest(audio:) consultez le fichier README de 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 " )
}
} De plus, W3WMicrophone dispose d'une fermeture de rappel W3WMicrophone.volumeUpdate: (Double) -> () qui fournit des informations d'amplitude utiles pour animer les commentaires des utilisateurs. Consultez l’exemple de l’API vocale et plus d’informations sont disponibles dans le fichier README de VoiceAPI.
Cette fonction renvoie les langues actuellement prises en charge pour les appels autosuggest(text:) basés sur du texte. Il renverra le code à deux lettres (ISO 639) et le nom de la langue dans cette langue et en anglais.
Les valeurs renvoyées par la méthode convertTo3wa sont décrites dans la documentation de l'API REST what3words
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} Pour les langues disponibles de l'API vocale, appelez api.availableVoiceLanguages(completion:) qui fonctionne exactement de la même manière.
Renvoie une section de la grille what3words de 3 mx 3 m pour une zone donnée. La boîte demandée ne doit pas dépasser 4 km d'un coin à l'autre, sinon une erreur BadBoundingBoxTooBig sera renvoyée. Les latitudes doivent être >= -90 et <= 90, mais les longitudes peuvent s'enrouler autour de 180. Pour spécifier un cadre de délimitation qui traverse l'antiméridien, utilisez une longitude supérieure à 180. Exemple de valeur : 50,0, 179,995, 50,01, 180,0005. .
La grille est renvoyée sous la forme [W3WLine]? et chaque W3WLine contient une variable start et end , toutes deux de type CLLocationCoordinate2D .
Les valeurs renvoyées par la fonction gridSection sont décrites dans la documentation de l'API REST what3words
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 )
}
} Voici quelques fonctions qui rechercheront ou valideront des adresses à trois mots.
Vérifiez si le texte suit la forme d'une adresse de trois mots via regex, c'est-à-dire un mot suivi d'un séparateur suivi d'un mot suivi d'un séparateur suivi d'un mot. Un mot est défini comme une suite de lettres appartenant à n’importe quel système d’écriture. Cela ne valide pas l'adresse comme étant un emplacement réel sur la terre, mais simplement qu'elle en suit la forme textuelle. Par exemple, xx.xx.xx réussirait ce test même s'il ne s'agit pas d'une adresse valide.
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}Cela imprimerait le résultat car même si "abc.def.ghi" n'est pas une adresse valide de trois mots, elle correspond néanmoins à la forme d'un seul, [mot][séparateur][mot][séparateur][mot].
Vérifie que le texte est une adresse valide de trois mots qui représente avec succès un carré sur terre. Cela appelle l'API pour vérifier. Les autres fonctions de validation exécutent uniquement une expression régulière localement.
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} Recherche un nombre illimité d'adresses possibles de trois mots dans un bloc de texte. Le terme « adresses possibles de trois mots » fait référence à un texte qui correspond à l'expression régulière utilisée dans isPossible3wa(), c'est-à-dire qu'il s'agit de morceaux de texte qui semblent être des adresses de trois mots, mais qui n'ont pas été vérifiés par le moteur comme représentant un lieu réel. sur terre.
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 ) Cela affichera : ["filled.count.soap", "index.home.raft", "grilled.cheese.sandwhich"]
Toutes les fonctions appellent le bloc de complétion avec error comme deuxième paramètre. Toutes error Swift what3words sont W3WError et sont conformes à CustomStringConvertible , elles peuvent donc être utilisées avec String(describing: error) , et elles sont également conformes à Error bien sûr :
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 ?? " " )
}
} Les erreurs d’appel d’API sont de type énumération W3WError et l’appel autosuggest vocale renvoie une énumération W3WVoiceError .
Il existe également un SDK qui fonctionne hors ligne. Plus d’informations sont disponibles ici.
Le SDK peut être utilisé de manière interchangeable avec ce wrapper API. Autrement dit, vous pouvez démarrer votre projet à l'aide de ce wrapper d'API, puis effectuer une mise à niveau vers le SDK avec des modifications minimes de votre code.
Vous trouverez ci-dessous un tableau indiquant quelle version du SDK est compatible avec quelle version du wrapper d'API :
| w3w-swift-wrapper | Version du SDK |
|---|---|
| v3.8.2 et versions antérieures | v3.8.0 et versions antérieures |
| v3.9.0 et supérieur | v4.0.0 et supérieur |
