w3w swift wrapper
v4.0.1
Pustaka Swift untuk berinteraksi dengan REST API dan VoiceAPI what3words.
Pembungkus API What3words Swift memberi Anda akses terprogram
Objek pembungkus Swift API utama adalah What3WordsV3 dan menyediakan fungsionalitas di atas. Ada juga W3WAutosuggestHelper tingkat lebih tinggi yang melakukan banyak pekerjaan memanggil API untuk fungsionalitas saran otomatis bidang teks. Ini sangat membantu jika Anda ingin menambahkan kata apa ke kode pelengkapan otomatis yang ada. Tutorialnya dapat ditemukan di sini.
Untuk komponen UI tingkat yang lebih tinggi, lihat pustaka w3w-swift-components kami di GitHub, termasuk W3WAutosuggestTextField yang memperluas UITextField untuk menambahkan fungsionalitas pelengkapan otomatis alamat tiga kata.
Anda dapat menemukan tutorial memulai cepat di sini untuk membantu Anda menyiapkan dan menjalankan dasar-dasarnya.
Paket ini juga berisi versi yang kompatibel dengan Objective-C, What3WordsObjC - lihat proyek ObjectiveC di Contoh/ObjectiveC/ObjectiveC.xcodeproj
Paket ini berfungsi dengan:
Untuk menggunakan perpustakaan ini, Anda memerlukan kunci API what3words, yang dapat didaftarkan di sini. Jika Anda ingin menggunakan panggilan Voice API maka Anda harus menambahkan paket Voice API ke akun Anda.
Contoh paket ini dapat ditemukan di repositori contoh kami: https://github.com/what3words/w3w-swift-samples
Anda dapat menginstalnya dengan Swift Package Manager dengan menambahkan URL di bawah ini ke Paket Swift di bawah pengaturan proyek Anda:
https://github.com/what3words/w3w-swift-wrapper.git
Anda dapat menggunakan CocoaPods untuk menginstal w3w-swift-wrapper dengan menambahkannya ke target di Podfile Anda:
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
atau, jika Anda ingin menggunakan pustaka W3WSwiftApi dan W3WSwiftVoiceApi:
pod 'W3WSwiftApi', :git => 'https://github.com/what3words/w3w-swift-wrapper.git'
pod 'W3WSwiftVoiceApi', :git => 'https://github.com/what3words/w3w-swift-voice-api.git'
Di file mana pun tempat Anda menggunakan What3words API, impor yang berikut ini:
import W3WSwiftApi
import W3WSwiftVoiceApi
import CoreLocation
Gunakan kode berikut dengan kunci API Anda untuk menginisialisasi API:
let api = What3WordsV3 ( apiKey : " YourApiKey " )Jika Anda menjalankan sendiri Server API Enterprise Suite kami, Anda dapat menentukan URL ke server Anda sendiri seperti:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " ) Selain itu, jika Anda menjalankan Server API Enterprise Suite, ada parameter setup() opsional lainnya: customHeaders . Gunakan ini jika Anda perlu mengirim header khusus ke server Anda sendiri:
let api = What3WordsV3 ( apiKey : " YourApiKey " , apiUrl : " https://api.yourserver.com " , customHeaders : [ " x-header-1 " : " value-1 " , " x-header-2 " : " value-2 " ] )Setiap panggilan mengambil blok penyelesaian sebagai parameter terakhir. Hal ini memungkinkan sintaks penutupan akhir Swift untuk digunakan. Parameter penutupan berisi hasilnya. Jika ada masalah dengan panggilan apa pun, itu akan ditunjukkan oleh objek kesalahan.
Ubah koordinat, yang dinyatakan sebagai lintang dan bujur menjadi alamat 3 kata. Fungsi ini mengambil garis lintang dan garis bujur sebagai objek CLLocationCoordinate2D. Nilai yang dikembalikan dari metode convertTo3wa dijelaskan dalam dokumentasi API.
let coords = CLLocationCoordinate2D ( latitude : 51.4243877 , longitude : - 0.34745 )
api . convertTo3wa ( coordinates : coords , language : W3WApiLanguage ( locale : " en " ) ) { square , error in
print ( square ? . words ?? " " )
} Ubah alamat 3 kata menjadi koordinat geografis, yang diwakili oleh garis lintang dan garis bujur. Fungsi ini mengambil parameter kata sebagai string 3 kata 'table.book.chair' . Nilai yang dikembalikan dari metode convertToCoordinates dijelaskan dalam dokumentasi API.
api . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} Mengembalikan daftar alamat 3 kata berdasarkan input pengguna dan parameter lainnya.
Metode ini memberikan koreksi untuk jenis kesalahan masukan berikut:
Metode autosuggest menentukan kemungkinan koreksi pada string alamat 3 kata yang disediakan berdasarkan kemungkinan kesalahan input yang tercantum di atas dan mengembalikan daftar saran yang diberi peringkat. Metode ini juga dapat mempertimbangkan kedekatan geografis dari kemungkinan koreksi terhadap lokasi tertentu untuk lebih menyempurnakan saran yang diberikan.
Jika Anda memiliki akun yang mendukung VoiceAPI, Anda juga dapat menghubungi autosuggest dengan data audio untuk pengenalan suara. Agar ini berfungsi, Anda harus menambahkan paket Voice API ke akun Anda. Ada contoh minimalnya di bawah, tetapi informasi detailnya dapat ditemukan di sini
Anda hanya akan menerima hasil kembali jika sebagian string alamat 3 kata yang Anda kirimkan berisi dua kata pertama dan setidaknya karakter pertama dari kata ketiga; jika tidak, pesan kesalahan akan dikembalikan.
Untuk memverifikasi apakah string alamat Anda memenuhi format yang diperlukan, kami menawarkan fungsi sederhana yang disebut isPossible3wa . Fungsi ini menggunakan ekspresi reguler kami untuk mengidentifikasi alamat tiga kata potensial, hanya mengonfirmasi jika masukan terdiri dari tiga kata yang dipisahkan oleh dua pemisah kata apa. Harap dicatat bahwa ini tidak memvalidasi apakah inputnya adalah alamat tiga kata yang sebenarnya di dunia. Pernyataan if berikut akan mengembalikan 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")
}
Atau jika Anda mau, Anda cukup menggunakan regex kami. Contoh kode dapat ditemukan di dokumentasi regex kami.
Kami menyediakan berbagai kebijakan clip untuk memungkinkan Anda memfilter berdasarkan wilayah geografis. Kami menyarankan Anda menggunakan opsi kliping untuk memberikan serangkaian hasil yang lebih bertarget kepada pengguna Anda. Anda dapat memotong berdasarkan negara, atau berdasarkan kotak geografis, lingkaran, atau poligon. Lakukan ini melalui W3WOptions dan teruskan ke panggilan saran otomatis (lihat contoh di bawah).
Jika Anda mengetahui lokasi pengguna Anda saat ini, kami juga sangat menyarankan agar Anda menggunakan fokus untuk memberikan hasil yang mungkin lebih relevan. Lakukan ini melalui W3WOptions dan teruskan ke panggilan saran otomatis (lihat contoh di bawah)
Nilai yang dikembalikan dari metode autosuggest dijelaskan dalam dokumentasi REST API what3words.
Parameter pertama adalah sebagian tiga kata atau data suara. Parameter opsional kedua adalah opsi untuk fungsi saran otomatis. Parameter terakhir adalah blok penyelesaian.
api . autosuggest ( text : " filled.count.soa " ) { ( suggestions , error ) in
for suggestion in suggestions ?? [ ] {
print ( " ( suggestion . words ?? " " ) is near ( suggestion . nearestPlace ?? " " ) " )
}
} Fokus pada satu tempat tertentu menggunakan satu opsi:
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 ?? " " )
} Fokus pada (51.4243877,-0.34745), dan klip ke Inggris menggunakan objek pilihan ganda:
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 memungkinkan pengguna mengucapkan tiga kata ke dalam aplikasi atau layanan apa pun, dan mengembalikan daftar saran alamat what3words yang dapat dikonfigurasi, semuanya melalui satu panggilan API.
Agar ini berfungsi, Anda harus menambahkan paket Voice API ke akun Anda.
Contoh ini membuat instance W3WMicrophone yang menyediakan aliran audio ke autosuggest(audio:) yang mulai direkam saat autosuggest dipanggil. Untuk informasi tentang W3WMicrophone dan menyesuaikan W3WAudioStream Anda sendiri untuk autosuggest(audio:) lihat 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 " )
}
} Selain itu, W3WMicrophone memiliki penutupan panggilan balik W3WMicrophone.volumeUpdate: (Double) -> () yang menyediakan informasi amplitudo yang berguna untuk menganimasikan umpan balik pengguna. Lihat contoh Voice API, dan informasi lebih lanjut tersedia di README VoiceAPI.
Fungsi ini mengembalikan bahasa yang saat ini didukung untuk panggilan autosuggest(text:) berbasis teks. Ini akan mengembalikan kode dua huruf (ISO 639), dan nama bahasa dalam bahasa tersebut dan dalam bahasa Inggris.
Nilai yang dikembalikan dari metode convertTo3wa dijelaskan dalam dokumentasi REST API what3words
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} Untuk bahasa API Suara yang tersedia, panggil api.availableVoiceLanguages(completion:) yang cara kerjanya persis sama.
Mengembalikan bagian kisi kata-kata apa berukuran 3m x 3m untuk area tertentu. Kotak yang diminta tidak boleh melebihi 4 km dari sudut ke sudut, atau kesalahan BadBoundingBoxTooBig akan ditampilkan. Garis lintang harus >= -90 dan <= 90, namun garis bujur boleh berada di sekitar 180. Untuk menentukan kotak pembatas yang melintasi anti-meridian, gunakan garis bujur yang lebih besar dari 180. Contoh nilai: 50.0, 179.995, 50.01, 180.0005 .
Grid dikembalikan sebagai [W3WLine]? dan setiap W3WLine berisi variabel start dan end , keduanya bertipe CLLocationCoordinate2D .
Nilai yang dikembalikan dari fungsi gridSection dijelaskan dalam dokumentasi 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 )
}
} Ini adalah beberapa fungsi yang akan mencari atau memvalidasi tiga alamat kata.
Periksa apakah teks mengikuti bentuk alamat tiga kata melalui regex, yaitu kata yang diikuti dengan pemisah diikuti dengan kata yang diikuti dengan pemisah diikuti dengan kata. Sebuah kata didefinisikan sebagai rangkaian huruf yang termasuk dalam sistem penulisan apa pun. Hal ini tidak memvalidasi alamat tersebut sebagai lokasi sebenarnya di bumi, hanya saja alamat tersebut mengikuti bentuk tekstualnya. Misalnya, xx.xx.xx akan lulus tes ini meskipun alamatnya tidak valid.
if api . isPossible3wa ( text : " abc.def.ghi " ) {
print ( " does match the text pattern for a three word address " )
}Ini akan mencetak hasilnya karena meskipun "abc.def.ghi" bukan alamat tiga kata yang valid, namun tetap cocok dengan bentuk satu, [word][separator][word][separator][word].
Memverifikasi bahwa teks tersebut adalah alamat tiga kata valid yang berhasil mewakili persegi di bumi. Ini membuat panggilan ke API untuk memverifikasi. Fungsi validasi lainnya hanya menjalankan regex secara lokal.
api . isValid3wa ( words : " filled.count.soap " ) { valid in
if valid {
print ( " the address provided is a real address somewhere on earth " )
}
} Menemukan sejumlah kemungkinan alamat tiga kata dalam satu blok teks. Istilah "kemungkinan alamat tiga kata" mengacu pada teks yang cocok dengan regex yang digunakan dalam isPossible3wa(), yaitu, ini adalah potongan teks yang tampak seperti alamat tiga kata, namun belum diverifikasi terhadap mesin sebagai mewakili tempat sebenarnya di dunia.
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 ) Ini akan mencetak: ["filled.count.soap", "index.home.raft", "grilled.cheese.sandwhich"]
Semua fungsi memanggil blok penyelesaian dengan error sebagai parameter kedua. Semua error Swift what3words adalah W3WError dan sesuai dengan CustomStringConvertible , sehingga dapat digunakan dengan String(describing: error) , dan tentu saja juga sesuai dengan 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 ?? " " )
}
} Kesalahan panggilan API bertipe W3WError enum dan panggilan autosuggest suara mengembalikan enum W3WVoiceError .
Ada juga SDK yang bekerja offline. Informasi lebih lanjut tersedia di sini.
SDK dapat digunakan secara bergantian dengan pembungkus API ini. Artinya, Anda dapat memulai proyek menggunakan pembungkus API ini, dan nantinya Anda dapat meningkatkan versi ke SDK dengan sedikit perubahan pada kode Anda.
Di bawah ini adalah tabel versi SDK mana yang kompatibel dengan versi wrapper API yang mana:
| w3w-swift-wrapper | Versi SDK |
|---|---|
| v3.8.2 dan lebih rendah | v3.8.0 dan lebih rendah |
| v3.9.0 dan lebih tinggi | v4.0.0 dan lebih tinggi |
