w3w swift wrapper
v4.0.1
Una biblioteca Swift para interactuar con la API REST y VoiceAPI de what3words.
El contenedor Swift API de what3words le brinda acceso programático a
El principal objeto contenedor rápido de API es What3WordsV3 y proporciona la funcionalidad anterior. También hay un W3WAutosuggestHelper de nivel superior que hace gran parte del trabajo de llamar a la API para la funcionalidad de sugerencia automática de campos de texto. Esto es particularmente útil si desea agregar what3words a su código de autocompletar existente. Puede encontrar un tutorial aquí.
Para obtener componentes de interfaz de usuario de nivel aún más alto, consulte nuestra biblioteca w3w-swift-components en GitHub, incluido W3WAutosuggestTextField , que extiende UITextField para agregar la funcionalidad de autocompletar de direcciones de tres palabras.
Puede encontrar un tutorial de inicio rápido aquí para ayudarle a configurar y ejecutar los conceptos básicos.
Este paquete también contiene una versión compatible con Objective-C, What3WordsObjC ; consulte el proyecto ObjectiveC en Ejemplos/ObjectiveC/ObjectiveC.xcodeproj.
Este paquete funciona con:
Para utilizar esta biblioteca, necesitará una clave API de what3words, a la que puede registrarse aquí. Si desea utilizar las llamadas de Voice API, debe agregar un plan de Voice API a su cuenta.
Se pueden encontrar ejemplos de este paquete en nuestro repositorio de ejemplos: https://github.com/what3words/w3w-swift-samples
Puede instalar esto con Swift Package Manager agregando la siguiente URL a Swift Packages en la configuración de su proyecto:
https://github.com/what3words/w3w-swift-wrapper.git
Puedes usar CocoaPods para instalar w3w-swift-wrapper agregándolo al destino en tu Podfile:
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
o, si desea utilizar las bibliotecas W3WSwiftApi y W3WSwiftVoiceApi:
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
pod 'W3WSwiftVoiceApi', :git => 'https://github.com/what3words/w3w-swift-voice-api.git'
En cualquier archivo donde utilice la API What3words, importe lo siguiente:
import W3WSwiftApi
import W3WSwiftVoiceApi
import CoreLocation
Utilice el siguiente código con su clave API para inicializar la API:
let api = What3WordsV3 ( apiKey : " YourApiKey " )En el caso de que usted mismo ejecute nuestro servidor API Enterprise Suite, puede especificar la URL de su propio servidor de la siguiente manera:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " ) Además, si ejecuta Enterprise Suite API Server, hay otro parámetro setup() opcional: customHeaders . Utilice esto si necesita enviar encabezados personalizados a su propio servidor:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " , customHeaders : [ " x-header-1 " : " value-1 " , " x-header-2 " : " value-2 " ] )Cada llamada toma un bloque de finalización como último parámetro. Esto permite utilizar la sintaxis de cierre final de Swift. Los parámetros del cierre contienen los resultados. Si hay algún problema con alguna llamada, se indicará mediante el objeto de error.
Convierta coordenadas, expresadas como latitud y longitud, en una dirección de 3 palabras. Esta función toma la latitud y la longitud como un objeto CLLocationCoordinate2D. Los valores devueltos por el método convertTo3wa se describen en la documentación de la API.
let coords = CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 )
api . convertTo3wa ( coordinates : coords , language : W3WApiLanguage ( locale : " en " ) ) { square , error in
print ( square ? . words ?? " " )
} Convierta una dirección de 3 palabras en coordenadas geográficas, representadas por latitud y longitud. Esta función toma el parámetro palabras como una cadena de 3 palabras 'table.book.chair' . Los valores devueltos por el método convertToCoordinates se describen en la documentación de la API.
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} Devuelve una lista de direcciones de 3 palabras según la entrada del usuario y otros parámetros.
Este método proporciona correcciones para los siguientes tipos de errores de entrada:
El método autosuggest determina posibles correcciones a la cadena de dirección de 3 palabras proporcionada en función de la probabilidad de los errores de entrada enumerados anteriormente y devuelve una lista clasificada de sugerencias. Este método también puede tener en cuenta la proximidad geográfica de posibles correcciones a una ubicación determinada para mejorar aún más las sugerencias devueltas.
Si tiene una cuenta habilitada para VoiceAPI, también puede llamar a autosuggest con datos de audio para reconocimiento de voz. Para que esto funcione, debe agregar un plan API de voz a su cuenta. Hay un ejemplo mínimo de esto a continuación, pero puede encontrar información detallada aquí.
Solo recibirá resultados si la cadena de dirección parcial de 3 palabras que envíe contiene las dos primeras palabras y al menos el primer carácter de la tercera palabra; de lo contrario, se devolverá un mensaje de error.
Para verificar si su cadena de dirección cumple con el formato requerido, ofrecemos una función simple llamada isPossible3wa . Esta función utiliza nuestra expresión regular para identificar posibles direcciones de tres palabras, confirmando solo si la entrada consta de tres palabras separadas por dos separadores de what3words. Tenga en cuenta que no valida si la entrada es una dirección real de tres palabras en el mundo. La siguiente declaración if devolverá 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")
}
O si lo prefieres, simplemente puedes usar nuestra expresión regular. Puede encontrar un código de ejemplo en nuestra documentación de expresiones regulares.
Proporcionamos varias políticas clip para permitirle filtrar por área geográfica. Le recomendamos que utilice las opciones de recorte para brindar un conjunto de resultados más específicos a su usuario. Puede recortar por país, o por cuadro geográfico, círculo o polígono. Haga esto a través de W3WOptions y páselo a la llamada de sugerencia automática (vea el ejemplo a continuación).
Si conoce la ubicación actual de su usuario, también le recomendamos encarecidamente que utilice el enfoque para obtener resultados que probablemente sean más relevantes. Haga esto a través de W3WOptions y páselo a la llamada de sugerencia automática (vea el ejemplo a continuación)
Los valores devueltos por el método autosuggest se describen en la documentación de la API REST de what3words.
El primer parámetro son las tres palabras parciales o datos de voz. El segundo parámetro opcional son las opciones para la función de sugerencia automática. El último parámetro es el bloque de finalización.
api . autosuggest ( text : " filled.count.soa " ) { ( suggestions , error ) in
for suggestion in suggestions ?? [ ] {
print ( " ( suggestion . words ?? " " ) is near ( suggestion . nearestPlace ?? " " ) " )
}
} Concéntrate en un lugar en particular usando una única opción:
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 ?? " " )
} Céntrese en (51.4243877,-0.34745) y recorte al Reino Unido usando el objeto de opciones múltiples:
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 ?? " " )
} La API de voz de what3words permite a un usuario decir tres palabras en cualquier aplicación o servicio, y devuelve una lista configurable de sugerencias de direcciones de what3words, todo a través de una única llamada API.
Para que esto funcione, debe agregar un plan API de voz a su cuenta.
Este ejemplo crea una instancia de un W3WMicrophone que proporciona una secuencia de audio para autosuggest(audio:) que comienza a grabar cuando se llama autosuggest . Para obtener información sobre W3WMicrophone y personalizar su propio W3WAudioStream para autosuggest(audio:) consulte el archivo LÉAME 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 " )
}
} Además, W3WMicrophone tiene un cierre de devolución de llamada W3WMicrophone.volumeUpdate: (Double) -> () que proporciona información de amplitud útil para animar los comentarios de los usuarios. Consulte el ejemplo de Voice API y encontrará más información disponible en VoiceAPI README.
Esta función devuelve los idiomas actualmente admitidos para llamadas autosuggest(text:) basadas en texto. Devolverá el código de dos letras (ISO 639), y el nombre del idioma tanto en ese idioma como en inglés.
Los valores devueltos por el método convertTo3wa se describen en la documentación de la API REST de what3words.
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} Para conocer los idiomas de Voice API disponibles, llame a api.availableVoiceLanguages(completion:) que funciona exactamente de la misma manera.
Devuelve una sección de la cuadrícula what3words de 3 mx 3 m para un área determinada. El cuadro solicitado no debe exceder los 4 km de esquina a esquina, o se devolverá un error BadBoundingBoxTooBig. Las latitudes deben ser >= -90 y <= 90, pero se permite que las longitudes se ajusten a 180. Para especificar un cuadro delimitador que cruce el antimeridiano, utilice una longitud mayor que 180. Valor de ejemplo: 50,0, 179,995, 50,01, 180,0005 .
¿La cuadrícula se devuelve como [W3WLine]? y cada W3WLine contiene una variable start y end , ambas de tipo CLLocationCoordinate2D .
Los valores devueltos por la función gridSection se describen en la documentación de la API REST de 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 )
}
} Estas son algunas funciones que buscarán o validarán direcciones de tres palabras.
Verifique si el texto sigue la forma de una dirección de tres palabras mediante expresiones regulares, es decir, una palabra seguida de un separador seguida de una palabra seguida de un separador seguido de una palabra. Una palabra se define como una serie de letras que pertenecen a cualquier sistema de escritura. Esto no valida que la dirección sea una ubicación real en la tierra, solo que sigue la forma textual de una. Por ejemplo, xx.xx.xx pasaría esta prueba aunque no sea una dirección válida.
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}Esto imprimiría el resultado porque aunque "abc.def.ghi" no es una dirección válida de tres palabras, aún así se ajusta a la forma de una, [palabra][separador][palabra][separador][palabra].
Verifica que el texto sea una dirección válida de tres palabras que represente con éxito un cuadrado en la tierra. Esto realiza una llamada a la API para verificar. Las otras funciones de validación solo ejecutan una expresión regular localmente.
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} Encuentra cualquier número de posibles direcciones de tres palabras en un bloque de texto. El término "posibles direcciones de tres palabras" se refiere al texto que coincide con la expresión regular utilizada en isPossible3wa(), es decir, son fragmentos de texto que parecen ser direcciones de tres palabras, pero que no se han verificado con el motor como si representaran un lugar real. en la tierra.
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 ) Esto imprimirá: ["filled.count.soap", "index.home.raft", "grilled.cheese.sandwhich"]
Todas las funciones llaman al bloque de finalización con error como segundo parámetro. Todos error de Swift what3words son W3WError y se ajustan a CustomStringConvertible , por lo que se pueden usar con String(describing: error) y, por supuesto, también se ajustan a 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 ?? " " )
}
} Los errores de llamada API son de tipo enumeración W3WError y la llamada autosuggest de voz devuelve una enumeración W3WVoiceError .
También hay un SDK que funciona sin conexión. Más información está disponible aquí.
El SDK se puede utilizar indistintamente con este contenedor de API. Es decir, puede iniciar su proyecto utilizando este contenedor de API y luego puede actualizar al SDK con cambios mínimos en su código.
A continuación se muestra una tabla sobre qué versión de SDK es compatible con qué versión de contenedor de API:
| w3w-swift-envoltorio | Versión SDK |
|---|---|
| v3.8.2 y anteriores | v3.8.0 y anteriores |
| v3.9.0 y superior | v4.0.0 y superior |
