w3w swift wrapper
v4.0.1
Uma biblioteca Swift para interagir com a API REST e VoiceAPI do what3words.
O wrapper da API Swift what3words oferece acesso programático a
O principal objeto wrapper da API Swift é What3WordsV3 e fornece a funcionalidade acima. Há também um W3WAutosuggestHelper de nível superior que faz grande parte do trabalho de chamar a API para a funcionalidade de sugestão automática de campo de texto. Isso é particularmente útil se você deseja adicionar what3words ao seu código de preenchimento automático existente. Um tutorial pode ser encontrado aqui.
Para componentes de UI de nível ainda mais alto, confira nossa biblioteca w3w-swift-components no GitHub, incluindo W3WAutosuggestTextField que estende UITextField para adicionar funcionalidade de preenchimento automático de endereço de três palavras.
Você pode encontrar um tutorial de início rápido aqui para ajudá-lo a configurar e executar o básico.
Este pacote também contém uma versão compatível com Objective-C, What3WordsObjC - veja o projeto ObjectiveC em Exemplos/ObjectiveC/ObjectiveC.xcodeproj
Este pacote funciona com:
Para usar esta biblioteca você precisará de uma chave API what3words, que pode ser cadastrada aqui. Se desejar usar as chamadas da API de voz, você deverá adicionar um plano da API de voz à sua conta.
Exemplos deste pacote podem ser encontrados em nosso repositório de exemplos: https://github.com/what3words/w3w-swift-samples
Você pode instalar isso com o Swift Package Manager adicionando o URL abaixo aos Pacotes Swift nas configurações do seu projeto:
https://github.com/what3words/w3w-swift-wrapper.git
Você pode usar CocoaPods para instalar o w3w-swift-wrapper adicionando-o ao destino em seu Podfile:
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
ou, se desejar usar as bibliotecas W3WSwiftApi e W3WSwiftVoiceApi:
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
pod 'W3WSwiftVoiceApi', :git => 'https://github.com/what3words/w3w-swift-voice-api.git'
Em qualquer arquivo onde você usa a API What3words, importe o seguinte:
import W3WSwiftApi
import W3WSwiftVoiceApi
import CoreLocation
Use o seguinte código com sua chave de API para inicializar a API:
let api = What3WordsV3 ( apiKey : " YourApiKey " )Caso você mesmo execute nosso servidor API Enterprise Suite, você pode especificar a URL para seu próprio servidor da seguinte forma:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " ) Além disso, se você executar o Enterprise Suite API Server, há outro parâmetro setup() opcional: customHeaders . Use isto se precisar enviar cabeçalhos personalizados para seu próprio servidor:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " , customHeaders : [ " x-header-1 " : " value-1 " , " x-header-2 " : " value-2 " ] )Cada chamada usa um bloco de conclusão como último parâmetro. Isso permite que a sintaxe de fechamento final do Swift seja usada. Os parâmetros do encerramento contêm os resultados. Se houver algum problema com alguma chamada, isso será indicado pelo objeto de erro.
Converta coordenadas, expressas como latitude e longitude em um endereço de 3 palavras. Esta função considera a latitude e a longitude como um objeto CLLocationCoorden2D. Os valores retornados do método convertTo3wa estão descritos na documentação da API.
let coords = CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 )
api . convertTo3wa ( coordinates : coords , language : W3WApiLanguage ( locale : " en " ) ) { square , error in
print ( square ? . words ?? " " )
} Converta um endereço de 3 palavras em coordenadas geográficas, representadas por latitude e longitude. Esta função usa o parâmetro words como uma string de 3 palavras 'table.book.chair' . Os valores retornados do método convertToCoordinates estão descritos na documentação da API.
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} Retorna uma lista de endereços de 3 palavras com base na entrada do usuário e outros parâmetros.
Este método fornece correções para os seguintes tipos de erros de entrada:
O método autosuggest determina possíveis correções para a sequência de endereços de 3 palavras fornecida com base na probabilidade dos erros de entrada listados acima e retorna uma lista classificada de sugestões. Este método também pode levar em consideração a proximidade geográfica de possíveis correções a um determinado local para melhorar ainda mais as sugestões retornadas.
Se você tiver uma conta habilitada para VoiceAPI, também poderá chamar autosuggest com dados de áudio para reconhecimento de voz. Para que isso funcione, você deve adicionar um plano de API de voz à sua conta. Há um exemplo mínimo disso abaixo, mas informações detalhadas podem ser encontradas aqui
Você só receberá os resultados se a sequência de endereço parcial de 3 palavras enviada contiver as duas primeiras palavras e pelo menos o primeiro caractere da terceira palavra; caso contrário, uma mensagem de erro será retornada.
Para verificar se a sua string de endereço atende ao formato exigido, oferecemos uma função simples chamada isPossible3wa . Esta função usa nosso regex para identificar possíveis endereços de três palavras, confirmando apenas se a entrada consiste em três palavras separadas por dois separadores what3words. Observe que isso não valida se a entrada é um endereço real de três palavras no mundo. A seguinte instrução if retornará 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 se preferir, você pode simplesmente usar nosso regex. O código de exemplo pode ser encontrado em nossa documentação sobre regex.
Fornecemos várias políticas clip para permitir que você filtre por área geográfica. Recomendamos que você use as opções de recorte para fornecer um conjunto de resultados mais direcionado ao seu usuário. Você pode recortar por país ou por caixa geográfica, círculo ou polígono. Faça isso por meio de W3WOptions e passe para a chamada de sugestão automática (veja o exemplo abaixo).
Se você souber a localização atual do seu usuário, também recomendamos fortemente que você use o foco para retornar resultados que provavelmente sejam mais relevantes. Faça isso através do W3WOptions e passe para a chamada de sugestão automática (veja o exemplo abaixo)
Os valores retornados do método autosuggest estão descritos na documentação da API REST do what3words.
O primeiro parâmetro são as três palavras parciais ou dados de voz. O segundo parâmetro opcional são as opções da função autosuggest. O último parâmetro é o bloco de conclusão.
api . autosuggest ( text : " filled.count.soa " ) { ( suggestions , error ) in
for suggestion in suggestions ?? [ ] {
print ( " ( suggestion . words ?? " " ) is near ( suggestion . nearestPlace ?? " " ) " )
}
} Concentre-se em um local específico usando uma única opção:
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 ?? " " )
} Concentre-se em (51.4243877,-0.34745) e recorte para o Reino Unido usando o objeto de múltiplas opções:
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 ?? " " )
} A API de voz what3words permite que um usuário diga três palavras em qualquer aplicativo ou serviço, retornando uma lista configurável de sugestões de endereços what3words, tudo por meio de uma única chamada de API.
Para que isso funcione, você deve adicionar um plano de API de voz à sua conta.
Este exemplo instancia um W3WMicrophone que fornece um fluxo de áudio para autosuggest(audio:) que começa a gravar quando autosuggest é chamado. Para obter informações sobre W3WMicrophone e como personalizar seu próprio W3WAudioStream para autosuggest(audio:) consulte o README do 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 " )
}
} Além disso, W3WMicrophone possui um fechamento de retorno de chamada W3WMicrophone.volumeUpdate: (Double) -> () que fornece informações de amplitude úteis para animar o feedback do usuário. Veja o exemplo da API de voz e mais informações estão disponíveis no README da VoiceAPI.
Esta função retorna os idiomas atualmente suportados para chamadas autosuggest(text:) baseadas em texto. Ele retornará o código de duas letras (ISO 639) e o nome do idioma nesse idioma e em inglês.
Os valores retornados do método convertTo3wa estão descritos na documentação da API REST what3words
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} Para os idiomas disponíveis da API de voz, chame api.availableVoiceLanguages(completion:) que funciona exatamente da mesma maneira.
Retorna uma seção da grade what3words de 3m x 3m para uma determinada área. A caixa solicitada não deve ultrapassar 4km de ponta a ponta, caso contrário será retornado um erro BadBoundingBoxTooBig. As latitudes devem ser >= -90 e <= 90, mas as longitudes podem girar em torno de 180. Para especificar uma caixa delimitadora que cruza o antimeridiano, use uma longitude maior que 180. Valor de exemplo: 50,0, 179,995, 50,01, 180,0005 .
A grade é retornada como [W3WLine]? e cada W3WLine contém uma variável start e end , ambas do tipo CLLocationCoordinate2D .
Os valores retornados da função gridSection estão descritos na documentação da 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 )
}
} Estas são algumas funções que irão pesquisar ou validar endereços de três palavras.
Verifique se o texto segue a forma de um endereço de três palavras via regex, ou seja, uma palavra seguida de um separador seguida de uma palavra seguida de um separador seguida de uma palavra. Uma palavra é definida como uma série de letras que pertencem a qualquer sistema de escrita. Isto não valida o endereço como sendo uma localização real na Terra, apenas que segue a forma textual de uma. Por exemplo, xx.xx.xx passaria neste teste mesmo que não fosse um endereço válido.
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}Isso imprimiria o resultado porque, embora "abc.def.ghi" não seja um endereço válido de três palavras, ainda assim ele se ajusta à forma de um, [palavra][separador][palavra][separador][palavra].
Verifica se o texto é um endereço válido de três palavras que representa com êxito um quadrado na Terra. Isso faz uma chamada para a API para verificação. As outras funções de validação executam apenas uma regex localmente.
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} Encontra qualquer número possível de endereços de três palavras em um bloco de texto. O termo "possíveis endereços de três palavras" refere-se ao texto que corresponde ao regex usado em isPossible3wa(), ou seja, são pedaços de texto que parecem ser endereços de três palavras, mas não foram verificados no mecanismo como representando um local real na terra.
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 ) Isso imprimirá: ["filled.count.soap", "index.home.raft", "grilled.cheese.sandwhich"]
Todas as funções chamam o bloco de conclusão com error como segundo parâmetro. Todos error what3words do Swift são W3WError e estão em conformidade com CustomStringConvertible , portanto, podem ser usados com String(describing: error) e também estão em conformidade com Error é claro:
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 ?? " " )
}
} Os erros de chamada de API são do tipo enum W3WError e a chamada autosuggest de voz retorna um enum W3WVoiceError .
Também existe um SDK que funciona offline. Mais informações estão disponíveis aqui.
O SDK pode ser usado de forma intercambiável com este wrapper de API. Ou seja, você pode iniciar seu projeto usando esse wrapper de API e, posteriormente, atualizar para o SDK com alterações mínimas em seu código.
Abaixo está uma tabela de qual versão do SDK é compatível com qual versão do wrapper da API:
| w3w-swift-wrapper | Versão do SDK |
|---|---|
| v3.8.2 e inferior | v3.8.0 e inferior |
| v3.9.0 e superior | v4.0.0 e superior |
