w3w swift wrapper
v4.0.1
what3words REST API 및 VoiceAPI와 상호작용하기 위한 Swift 라이브러리입니다.
what3words Swift API 래퍼는 다음에 대한 프로그래밍 방식의 액세스를 제공합니다.
주요 API Swift 래퍼 개체는 What3WordsV3 이며 위 기능을 제공합니다. 텍스트 필드 자동 제안 기능을 위해 API를 호출하는 많은 작업을 수행하는 더 높은 수준의 W3WAutosuggestHelper 도 있습니다. 이는 기존 자동 완성 코드에 what3words를 추가하려는 경우 특히 유용합니다. 튜토리얼은 여기에서 찾을 수 있습니다.
더 높은 수준의 UI 구성 요소에 대해서는 UITextField 확장하여 3단어 주소 자동 완성 기능을 추가하는 W3WAutosuggestTextField 포함하여 GitHub의 w3w-swift-comComponents 라이브러리를 확인하세요.
여기에서 기본 사항을 설정하고 실행하는 데 도움이 되는 빠른 시작 튜토리얼을 찾을 수 있습니다.
이 패키지에는 Objective-C 호환 버전인 What3WordsObjC 도 포함되어 있습니다. 예제/ObjectiveC/ObjectiveC.xcodeproj의 ObjectiveC 프로젝트를 참조하세요.
이 패키지는 다음과 함께 작동합니다.
이 라이브러리를 사용하려면 what3words API 키가 필요하며 여기에서 등록할 수 있습니다. Voice API 호출을 사용하려면 계정에 Voice API 계획을 추가해야 합니다.
이 패키지의 예는 예제 저장소(https://github.com/what3words/w3w-swift-samples)에서 찾을 수 있습니다.
프로젝트 설정 아래의 Swift 패키지에 아래 URL을 추가하여 Swift 패키지 관리자로 이를 설치할 수 있습니다.
https://github.com/what3words/w3w-swift-wrapper.git
CocoaPods를 사용하여 Podfile의 대상에 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'
What3words API를 사용하는 모든 파일에서 다음을 가져옵니다.
import W3WSwiftApi
import W3WSwiftVoiceApi
import CoreLocation
API를 초기화하려면 API 키와 함께 다음 코드를 사용하세요.
let api = What3WordsV3 ( apiKey : " YourApiKey " )Enterprise Suite API 서버를 직접 실행하는 경우 다음과 같이 자체 서버에 대한 URL을 지정할 수 있습니다.
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " ) 또한 Enterprise Suite API 서버를 실행하는 경우 또 다른 선택적 setup() 매개변수인 customHeaders 가 있습니다. 자신의 서버에 사용자 정의 헤더를 보내야 하는 경우 다음을 사용하십시오.
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " , customHeaders : [ " x-header-1 " : " value-1 " , " x-header-2 " : " value-2 " ] )각 호출은 완료 블록을 마지막 매개변수로 사용합니다. 이를 통해 Swift의 후행 클로저 구문을 사용할 수 있습니다. 클로저의 매개변수에는 결과가 포함됩니다. 호출에 문제가 있으면 오류 개체로 표시됩니다.
위도와 경도로 표현된 좌표를 3단어 주소로 변환합니다. 이 함수는 위도와 경도를 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 ?? " " )
} 3단어 주소를 위도와 경도로 표시되는 지리적 좌표로 변환합니다. 이 함수는 단어 매개변수를 'table.book.chair' 3개 단어의 문자열로 사용합니다. convertToCoordinates 메소드에서 반환된 값은 API 설명서에 설명되어 있습니다.
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} 사용자 입력 및 기타 매개변수를 기반으로 3단어 주소 목록을 반환합니다.
이 방법은 다음 유형의 입력 오류에 대한 수정을 제공합니다.
autosuggest 방법은 위에 나열된 입력 오류의 확률을 기반으로 제공된 3단어 주소 문자열에 대한 가능한 수정 사항을 결정하고 순위가 매겨진 제안 목록을 반환합니다. 이 방법은 반환된 제안을 더욱 향상시키기 위해 주어진 위치에 대한 가능한 수정 사항의 지리적 근접성을 고려할 수도 있습니다.
VoiceAPI 지원 계정이 있는 경우 음성 인식을 위한 오디오 데이터로 autosuggest 호출할 수도 있습니다. 이 기능이 작동하려면 계정에 Voice API 계획을 추가해야 합니다. 아래에 이에 대한 최소한의 예가 있지만 자세한 정보는 여기에서 찾을 수 있습니다.
제출한 부분 3단어 주소 문자열에 처음 두 단어와 최소한 세 번째 단어의 첫 번째 문자가 포함된 경우에만 결과를 받게 됩니다. 그렇지 않으면 오류 메시지가 반환됩니다.
주소 문자열이 필수 형식을 충족하는지 확인하기 위해 isPossible3wa 라는 간단한 함수를 제공합니다. 이 함수는 정규식을 사용하여 잠재적인 세 단어 주소를 식별하고, 입력이 두 개의 what3words 구분 기호로 구분된 세 단어로 구성되어 있는지만 확인합니다. 입력된 내용이 실제 세계의 3단어 주소인지 여부는 검증되지 않습니다. 다음 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 메소드에서 반환된 값은 what3words REST API 문서에 설명되어 있습니다.
첫 번째 매개변수는 부분적인 세 단어 또는 음성 데이터입니다. 두 번째 선택적 매개변수는 자동 제안 기능에 대한 옵션입니다. 마지막 매개변수는 완료 블록입니다.
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 ?? " " )
} what3words Voice API를 사용하면 사용자는 모든 애플리케이션이나 서비스에 세 단어를 말할 수 있으며 단일 API 호출을 통해 구성 가능한 what3words 주소 제안 목록이 반환됩니다.
이 기능이 작동하려면 계정에 Voice API 계획을 추가해야 합니다.
이 예는 autosuggest 호출될 때 녹음을 시작하는 autosuggest(audio:) 에 오디오 스트림을 제공하는 W3WMicrophone 을 인스턴스화합니다. W3WMicrophone 에 대한 정보와 자동 autosuggest(audio:) 위한 W3WAudioStream 사용자 정의는 VoiceAPI README를 참조하세요.
// 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 예제를 참조하세요. 자세한 내용은 VoiceAPI README에서 확인할 수 있습니다.
이 함수는 텍스트 기반 autosuggest(text:) 호출에 대해 현재 지원되는 언어를 반환합니다. 두 문자 코드(ISO 639)와 해당 언어와 영어로 된 언어 이름을 반환합니다.
convertTo3wa 메소드에서 반환된 값은 what3words REST API 문서에 설명되어 있습니다.
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} 사용 가능한 Voice API 언어의 경우 정확히 동일한 방식으로 작동하는 api.availableVoiceLanguages(completion:) 호출하세요.
주어진 영역에 대해 3m x 3m what3words 그리드의 섹션을 반환합니다. 요청된 상자는 모퉁이에서 모퉁이까지 4km를 초과해서는 안 됩니다. 그렇지 않으면 BadBoundingBoxTooBig 오류가 반환됩니다. 위도는 -90 이상 및 90 미만이어야 하지만 경도는 180 주위로 둘러싸일 수 있습니다. 반자오선을 가로지르는 경계 상자를 지정하려면 180보다 큰 경도를 사용하십시오. 값 예: 50.0, 179.995, 50.01, 180.0005 .
그리드는 [W3WLine]? 각 W3WLine 에는 CLLocationCoordinate2D 유형의 start 및 end 변수가 포함되어 있습니다.
gridSection 함수에서 반환된 값은 what3words REST API 문서에 설명되어 있습니다.
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 )
}
} 다음은 세 단어 주소를 검색하거나 유효성을 검사하는 일부 기능입니다.
텍스트가 정규 표현식을 통해 3단어 주소 형식을 따르는지 확인하세요. 즉, 단어 뒤에 구분 기호, 단어 뒤에 구분 기호, 단어가 옵니다. 단어는 모든 쓰기 체계에 속하는 일련의 문자로 정의됩니다. 이는 주소가 지구상의 실제 위치인지 확인하는 것이 아니라 주소의 텍스트 형식을 따른다는 것입니다. 예를 들어, xx.xx.xx는 유효한 주소가 아니더라도 이 테스트를 통과합니다.
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}"abc.def.ghi"가 유효한 세 단어 주소가 아니더라도 여전히 [단어][구분 기호][단어][구분 기호][단어] 형식에 맞기 때문에 결과가 인쇄됩니다.
텍스트가 지구상의 사각형을 성공적으로 나타내는 유효한 3단어 주소인지 확인합니다. 확인을 위해 API를 호출합니다. 다른 유효성 검사 기능은 로컬에서만 정규식을 실행합니다.
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} 텍스트 블록에서 가능한 세 단어 주소를 원하는 만큼 찾습니다. "가능한 3단어 주소"라는 용어는 isPossible3wa()에 사용된 정규식과 일치하는 텍스트를 나타냅니다. 즉, 이는 3단어 주소로 보이지만 엔진에 대해 실제 장소를 나타내는 것으로 확인되지 않은 텍스트 조각입니다. 지구상에.
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 두 번째 매개변수로 사용하여 완료 블록을 호출합니다. 모든 Swift what3words error 는 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-스위프트 래퍼 | SDK 버전 |
|---|---|
| v3.8.2 이하 | v3.8.0 이하 |
| v3.9.0 이상 | v4.0.0 이상 |
