w3w swift wrapper
v4.0.1
Библиотека Swift для взаимодействия с REST API What3words и VoiceAPI.
Оболочка Swift API What3words предоставляет вам программный доступ к
Основным объектом-оболочкой Swift API является What3WordsV3 , который обеспечивает вышеуказанную функциональность. Существует также более высокий уровень W3WAutosuggestHelper , который выполняет большую часть работы по вызову API для функции автозаполнения текстовых полей. Это особенно полезно, если вы хотите добавить What3words к существующему коду автозаполнения. Учебное пособие можно найти здесь.
Если вам нужны компоненты пользовательского интерфейса еще более высокого уровня, ознакомьтесь с нашей библиотекой w3w-swift-comComponents на GitHub, включая W3WAutosuggestTextField , которая расширяет UITextField , добавляя функцию автозаполнения адреса из трех слов.
Здесь вы можете найти краткое руководство, которое поможет вам настроить и начать работу с основами.
Этот пакет также содержит версию What3WordsObjC , совместимую с Objective-C — см. проект ObjectiveC в разделе «Примеры/ObjectiveC/ObjectiveC.xcodeproj».
Этот пакет работает с:
Чтобы использовать эту библиотеку, вам понадобится ключ API What3words, который можно зарегистрировать здесь. Если вы хотите использовать вызовы Voice API, вам необходимо добавить план Voice API в свою учетную запись.
Примеры этого пакета можно найти в нашем репозитории примеров: https://github.com/what3words/w3w-swift-samples.
Вы можете установить его с помощью Swift Package Manager, добавив URL-адрес ниже в Swift Packages в настройках вашего проекта:
https://github.com/what3words/w3w-swift-wrapper.git
Вы можете использовать CocoaPods для установки 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'
В любой файл, в котором вы используете API What3words, импортируйте следующее:
import W3WSwiftApi
import W3WSwiftVoiceApi
import CoreLocation
Используйте следующий код с вашим ключом API для инициализации API:
let api = What3WordsV3 ( apiKey : " YourApiKey " )В случае, если вы самостоятельно запускаете наш API-сервер Enterprise Suite, вы можете указать URL-адрес своего собственного сервера следующим образом:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " ) Кроме того, если вы запускаете API-сервер Enterprise Suite, есть еще один необязательный параметр setup() : customHeaders . Используйте это, если вам нужно отправить собственные заголовки на свой сервер:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " , customHeaders : [ " x-header-1 " : " value-1 " , " x-header-2 " : " value-2 " ] )Каждый вызов принимает блок завершения в качестве последнего параметра. Это позволяет использовать синтаксис замыкания Swift. Параметры замыкания содержат результаты. Если с каким-либо вызовом возникнет проблема, это будет обозначено объектом ошибки.
Преобразуйте координаты, выраженные как широта и долгота, в адрес из трех слов. Эта функция принимает широту и долготу как объект CLLocationCoordinate2D. Значения, возвращаемые методом 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 ?? " " )
} Преобразуйте адрес из трех слов в географические координаты, представленные широтой и долготой. Эта функция принимает параметр «words» как строку из трех слов 'table.book.chair' . Значения, возвращаемые методом convertToCoordinates описаны в документации API.
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} Возвращает список адресов из трех слов на основе ввода пользователя и других параметров.
Этот метод обеспечивает исправление следующих типов ошибок ввода:
Метод autosuggest определяет возможные исправления предоставленной адресной строки из трех слов на основе вероятности ошибок ввода, перечисленных выше, и возвращает ранжированный список предложений. Этот метод также может учитывать географическую близость возможных исправлений к данному местоположению для дальнейшего улучшения возвращаемых предложений.
Если у вас есть учетная запись с поддержкой VoiceAPI, вы также можете вызвать autosuggest со звуковыми данными для распознавания голоса. Чтобы это работало, вы должны добавить план Voice API в свою учетную запись. Ниже приведен минимальный пример этого, но подробную информацию можно найти здесь.
Вы получите результаты только в том случае, если отправленная вами неполная адресная строка из трех слов содержит первые два слова и хотя бы первый символ третьего слова; в противном случае будет возвращено сообщение об ошибке.
Чтобы проверить, соответствует ли ваша адресная строка требуемому формату, мы предлагаем простую функцию isPossible3wa . Эта функция использует наше регулярное выражение для идентификации потенциальных адресов из трех слов, подтверждая только то, что входные данные состоят из трех слов, разделенных двумя разделителями What3words. Обратите внимание, что он не проверяет, является ли ввод реальным адресом из трех слов в мире. Следующий оператор 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 и передайте его в вызов автозаполнения (см. пример ниже).
Если вы знаете текущее местоположение вашего пользователя, мы также настоятельно рекомендуем вам использовать фокус для получения более релевантных результатов. Сделайте это через W3WOptions и передайте его в вызов автозаполнения (см. пример ниже).
Значения, возвращаемые методом autosuggest , описаны в документации REST API What3words.
Первый параметр — это частичные три слова или голосовые данные. Второй необязательный параметр — это параметры функции автозаполнения. Последний параметр — это блок завершения.
api . autosuggest ( text : " filled.count.soa " ) { ( suggestions , error ) in
for suggestion in suggestions ?? [ ] {
print ( " ( suggestion . words ?? " " ) is near ( suggestion . nearestPlace ?? " " ) " )
}
} Сосредоточьтесь на одном конкретном месте, используя один вариант:
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) и выделите Великобританию, используя объект с несколькими параметрами:
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 ?? " " )
} Голосовой API What3words позволяет пользователю произнести три слова в любом приложении или сервисе, возвращая при этом настраиваемый список предложений адресов What3words, и все это посредством одного вызова API.
Чтобы это работало, вы должны добавить план Voice API в свою учетную запись.
В этом примере создается экземпляр W3WMicrophone , который предоставляет аудиопоток для autosuggest(audio:) , который начинает запись при вызове autosuggest . Информацию о W3WMicrophone и настройке собственного W3WAudioStream для autosuggest(audio:) см. в README 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 " )
}
} Кроме того, W3WMicrophone имеет замыкание обратного вызова W3WMicrophone.volumeUpdate: (Double) -> () , которое предоставляет информацию об амплитуде, полезную для анимации обратной связи с пользователем. См. пример Voice API. Дополнительную информацию можно найти в файле README VoiceAPI.
Эта функция возвращает поддерживаемые в настоящее время языки для текстовых вызовов autosuggest(text:) . Он вернет двухбуквенный код (ISO 639) и название языка как на этом языке, так и на английском языке.
Значения, возвращаемые методом convertTo3wa описаны в документации REST API What3words.
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} Для доступных языков голосового API вызовите api.availableVoiceLanguages(completion:) который работает точно так же.
Возвращает часть сетки what3words размером 3 x 3 метра для заданной области. Запрошенный ящик не должен превышать 4 км от угла до угла, иначе будет возвращена ошибка BadBoundingBoxTooBig. Широта должна быть >= -90 и <= 90, но долгота может оборачиваться вокруг 180. Чтобы указать ограничивающую рамку, пересекающую антимеридиан, используйте долготу больше 180. Пример значения: 50,0, 179,995, 50,01, 180,0005. .
Сетка возвращается как [W3WLine]? и каждая W3WLine содержит start и end переменную, обе типа CLLocationCoordinate2D .
Значения, возвращаемые функцией gridSection описаны в документации REST API 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 )
}
} Это некоторые функции, которые будут искать или проверять адреса из трех слов.
Проверьте, соответствует ли текст форме адреса из трех слов с помощью регулярного выражения, то есть за словом следует разделитель, за которым следует слово, за которым следует разделитель, за которым следует слово. Слово определяется как серия букв, принадлежащих к любой системе письма. Это не подтверждает, что адрес является реальным местом на Земле, просто он соответствует его текстовой форме. Например, xx.xx.xx пройдет этот тест, даже если это недействительный адрес.
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}Результат будет напечатан, потому что, хотя «abc.def.ghi» не является допустимым адресом из трех слов, он все же соответствует форме одного: [слово][разделитель][слово][разделитель][слово].
Проверяет, что текст представляет собой действительный адрес из трех слов, который успешно представляет собой квадрат на земле. Это вызывает вызов API для проверки. Другие функции проверки запускают регулярное выражение только локально.
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} Находит любое количество возможных адресов из трех слов в блоке текста. Термин «возможные адреса из трех слов» относится к тексту, который соответствует регулярному выражению, используемому в isPossible3wa(), то есть это фрагменты текста, которые кажутся адресами из трех слов, но не были проверены движком как представляющие фактическое место. на земле.
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"]
Все функции вызывают блок завершения с error в качестве второго параметра. Все error Swift What3words являются 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-обертка | Версия SDK |
|---|---|
| v3.8.2 и ниже | v3.8.0 и ниже |
| v3.9.0 и выше | v4.0.0 и выше |
