w3w swift wrapper
v4.0.1
ไลบรารี Swift สำหรับการโต้ตอบกับ what3words REST API และ VoiceAPI
wrapper what3words Swift API ช่วยให้คุณเข้าถึงโดยทางโปรแกรมได้
ออบเจ็กต์ wrapper ที่รวดเร็วของ API หลักคือ What3WordsV3 และมีฟังก์ชันการทำงานข้างต้น นอกจากนี้ยังมี W3WAutosuggestHelper ระดับที่สูงกว่าซึ่งทำหน้าที่เรียก API สำหรับฟังก์ชันการแนะนำอัตโนมัติของช่องข้อความเป็นจำนวนมาก สิ่งนี้มีประโยชน์อย่างยิ่งหากคุณต้องการเพิ่ม what3words ลงในโค้ดเติมข้อความอัตโนมัติที่มีอยู่ สามารถดูบทช่วยสอนได้ที่นี่
สำหรับส่วนประกอบ UI ในระดับที่สูงกว่า ลองดูไลบรารี w3w-swift-components ของเราบน GitHub รวมถึง W3WAutosuggestTextField ซึ่งขยาย UITextField เพื่อเพิ่มฟังก์ชันเติมข้อความอัตโนมัติที่อยู่สามคำ
คุณสามารถดูบทช่วยสอนแบบเริ่มต้นอย่างรวดเร็วได้ที่นี่เพื่อช่วยคุณในการตั้งค่าและใช้งานขั้นพื้นฐาน
แพ็คเกจนี้ยังประกอบด้วยเวอร์ชันที่เข้ากันได้กับ Objective-C, What3WordsObjC - ดูโปรเจ็กต์ ObjectiveC ใน Examples/ObjectiveC/ObjectiveC.xcodeproj
แพ็คเกจนี้ใช้งานได้กับ:
หากต้องการใช้ไลบรารีนี้ คุณจะต้องมีคีย์ API what3words ซึ่งสามารถสมัครได้ที่นี่ หากคุณต้องการใช้การเรียก Voice API คุณต้องเพิ่มแผน Voice API ให้กับบัญชีของคุณ
ตัวอย่างของแพ็คเกจนี้สามารถพบได้ในพื้นที่เก็บข้อมูลตัวอย่างของเรา: https://github.com/what3words/w3w-swift-samples
คุณสามารถติดตั้งสิ่งนี้ด้วย Swift Package Manager ได้โดยเพิ่ม URL ด้านล่างลงใน Swift Package ภายใต้การตั้งค่าโปรเจ็กต์ของคุณ:
https://github.com/what3words/w3w-swift-wrapper.git
คุณสามารถใช้ CocoaPods เพื่อติดตั้ง w3w-swift-wrapper ได้โดยเพิ่มลงในเป้าหมายใน Podfile ของคุณ:
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 Server จะมีพารามิเตอร์ 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 คำเป็นพิกัดทางภูมิศาสตร์ ซึ่งแสดงด้วยละติจูดและลองจิจูด ฟังก์ชันนี้รับพารามิเตอร์คำเป็นสตริง 3 คำ 'table.book.chair' ค่าที่ส่งคืนจากเมธอด convertToCoordinates อธิบายไว้ในเอกสารประกอบ API
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} ส่งคืนรายการที่อยู่คำ 3 คำตามการป้อนข้อมูลของผู้ใช้และพารามิเตอร์อื่นๆ
วิธีนี้มีการแก้ไขข้อผิดพลาดอินพุตประเภทต่อไปนี้:
วิธี autosuggest จะกำหนดการแก้ไขที่เป็นไปได้สำหรับสตริงที่อยู่ 3 คำที่ให้มา โดยพิจารณาจากความน่าจะเป็นของข้อผิดพลาดในการป้อนข้อมูลที่ระบุไว้ข้างต้น และส่งคืนรายการคำแนะนำที่ได้รับการจัดอันดับ วิธีนี้ยังคำนึงถึงความใกล้เคียงทางภูมิศาสตร์ของการแก้ไขที่เป็นไปได้ไปยังตำแหน่งที่กำหนด เพื่อปรับปรุงคำแนะนำที่ส่งคืนต่อไป
หากคุณมีบัญชีที่เปิดใช้งาน VoiceAPI คุณสามารถเรียก autosuggest พร้อมข้อมูลเสียงเพื่อจดจำเสียงได้ เพื่อให้ได้ผล คุณต้องเพิ่มแผน Voice API ให้กับบัญชีของคุณ มีตัวอย่างเล็กๆ น้อยๆ ของเรื่องนี้ด้านล่างนี้ แต่สามารถดูข้อมูลโดยละเอียดได้ที่นี่
คุณจะได้รับผลลัพธ์กลับมาก็ต่อเมื่อสตริงที่อยู่คำ 3 คำบางส่วนที่คุณส่งประกอบด้วยคำสองคำแรกและอย่างน้อยก็มีอักขระตัวแรกของคำที่สาม มิฉะนั้นข้อความแสดงข้อผิดพลาดจะถูกส่งกลับ
เพื่อตรวจสอบว่าสตริงที่อยู่ของคุณตรงตามรูปแบบที่กำหนดหรือไม่ เราขอเสนอฟังก์ชันง่ายๆ ที่เรียกว่า isPossible3wa ฟังก์ชันนี้ใช้ regex ของเราเพื่อระบุที่อยู่สามคำที่เป็นไปได้ โดยยืนยันเฉพาะในกรณีที่อินพุตประกอบด้วยคำสามคำที่คั่นด้วยตัวคั่น 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")
}
หรือหากคุณต้องการ คุณสามารถใช้ regex ของเราได้ โค้ดตัวอย่างมีอยู่ในเอกสารประกอบ regex ของเรา
เรามีนโยบาย 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 อนุญาตให้ผู้ใช้พูดสามคำในแอปพลิเคชันหรือบริการใดๆ โดยส่งคืนรายการคำแนะนำที่อยู่ what3words ที่กำหนดค่าได้ ทั้งหมดนี้ผ่านการเรียก API เพียงครั้งเดียว
เพื่อให้ใช้งานได้ คุณต้องเพิ่มแผน Voice API ให้กับบัญชีของคุณ
ตัวอย่างนี้สร้างอินสแตนซ์ W3WMicrophone ซึ่งจัดเตรียมสตรีมเสียงเพื่อ autosuggest(audio:) ซึ่งจะเริ่มการบันทึกเมื่อมีการเรียกการแนะนำ autosuggest สำหรับข้อมูลเกี่ยวกับ W3WMicrophone และการปรับแต่ง W3WAudioStream ของคุณเองสำหรับ autosuggest(audio:) โปรดดู 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 อธิบายไว้ในเอกสารประกอบ REST API ของ what3words
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} สำหรับภาษา Voice 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 )
}
} นี่คือฟังก์ชันบางอย่างที่จะค้นหาหรือตรวจสอบที่อยู่คำสามคำ
ตรวจสอบว่าข้อความเป็นไปตามรูปแบบของที่อยู่สามคำผ่าน regex หรือไม่ นั่นคือคำที่ตามด้วยตัวคั่นตามด้วยคำที่ตามด้วยตัวคั่นตามด้วยคำ คำถูกกำหนดให้เป็นชุดตัวอักษรที่อยู่ในระบบการเขียนใดๆ สิ่งนี้ไม่ได้ตรวจสอบที่อยู่ว่าเป็นสถานที่จริงบนโลก เพียงแต่ว่าเป็นไปตามรูปแบบข้อความของสถานที่หนึ่งเท่านั้น ตัวอย่างเช่น xx.xx.xx จะผ่านการทดสอบนี้แม้ว่าจะไม่ใช่ที่อยู่ที่ถูกต้องก็ตาม
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}การดำเนินการนี้จะพิมพ์ผลลัพธ์เนื่องจากแม้ว่า "abc.def.ghi" จะ ไม่ใช่ ที่อยู่สามคำที่ถูกต้อง แต่ก็ยัง พอดี กับรูปแบบของหนึ่ง [word][separator][word][separator][word]
ตรวจสอบว่าข้อความเป็นที่อยู่สามคำที่ถูกต้องซึ่งแสดงถึงรูปสี่เหลี่ยมจัตุรัสบนโลกได้สำเร็จ ซึ่งจะทำการเรียกไปยัง API เพื่อตรวจสอบ ฟังก์ชันการตรวจสอบความถูกต้องอื่นๆ จะเรียกใช้ regex ภายในเครื่องเท่านั้น
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} ค้นหาที่อยู่คำสามคำที่เป็นไปได้ในบล็อกข้อความ คำว่า "ที่อยู่สามคำที่เป็นไปได้" หมายถึงข้อความที่ตรงกับ regex ที่ใช้ใน 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 what3words ของ Swift ทั้งหมดคือ 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 enum และการโทร autosuggest เสียงส่งคืน enum W3WVoiceError
นอกจากนี้ยังมี SDK ที่ทำงานแบบออฟไลน์ ข้อมูลเพิ่มเติมมีอยู่ที่นี่
SDK สามารถใช้แทนกันได้กับ API Wrapper นี้ กล่าวคือ คุณสามารถเริ่มโปรเจ็กต์ได้โดยใช้ API Wrapper นี้ และคุณสามารถอัปเกรดเป็น SDK ได้ในภายหลังโดยมีการเปลี่ยนแปลงโค้ดเพียงเล็กน้อย
ด้านล่างนี้คือตารางเวอร์ชัน SDK ที่เข้ากันได้กับเวอร์ชัน Wrapper API ใด:
| w3w-swift-wrapper | เวอร์ชัน SDK |
|---|---|
| เวอร์ชัน 3.8.2 และต่ำกว่า | เวอร์ชัน 3.8.0 และต่ำกว่า |
| เวอร์ชัน 3.9.0 และสูงกว่า | เวอร์ชัน 4.0.0 และสูงกว่า |
