w3w swift wrapper
v4.0.1
مكتبة Swift للتفاعل مع واجهة برمجة تطبيقات عنوان3كلمات REST وVoiceAPI.
يمنحك غلاف What3words Swift API وصولاً برمجيًا إليه
كائن مجمّع واجهة برمجة التطبيقات السريع الرئيسي هو What3WordsV3 ويوفر الوظيفة المذكورة أعلاه. يوجد أيضًا مستوى أعلى من W3WAutosuggestHelper يقوم بالكثير من عمل استدعاء واجهة برمجة التطبيقات (API) لوظيفة الاقتراح التلقائي لحقل النص. يعد هذا مفيدًا بشكل خاص إذا كنت تريد إضافة عنوان3كلمات إلى رمز الإكمال التلقائي الموجود لديك. يمكن العثور على البرنامج التعليمي هنا.
للحصول على مكونات واجهة مستخدم ذات مستوى أعلى، راجع مكتبة مكونات w3w-swift على GitHub، بما في ذلك W3WAutosuggestTextField الذي يوسع UITextField لإضافة وظيفة الإكمال التلقائي للعناوين المكونة من ثلاث كلمات.
يمكنك العثور على برنامج تعليمي للبدء السريع هنا لمساعدتك في الإعداد والتشغيل باستخدام الأساسيات.
تحتوي هذه الحزمة أيضًا على إصدار متوافق مع Objective-C، What3WordsObjC - راجع مشروع ObjectiveC في الأمثلة/ObjectiveC/ObjectiveC.xcodeproj
تعمل هذه الحزمة مع:
لاستخدام هذه المكتبة، ستحتاج إلى مفتاح API عنوان3كلمات، والذي يمكن الاشتراك فيه هنا. إذا كنت ترغب في استخدام مكالمات 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 عن طريق إضافته إلى الهدف في ملف 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 كلمات. تأخذ هذه الوظيفة خط الطول وخط العرض ككائن CLLocationCoerate2D. تم وصف القيم التي تم إرجاعها من طريقة 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 . convertToCoordinates ( words : " filled.count.soap " ) { square , error in
print ( square ? . coordinates ?? " " )
} إرجاع قائمة بالعناوين المكونة من 3 كلمات بناءً على إدخال المستخدم والمعلمات الأخرى.
توفر هذه الطريقة تصحيحات للأنواع التالية من أخطاء الإدخال:
تحدد طريقة autosuggest التصحيحات المحتملة لسلسلة العناوين المكونة من 3 كلمات المتوفرة بناءً على احتمالية أخطاء الإدخال المذكورة أعلاه وتقوم بإرجاع قائمة مرتبة من الاقتراحات. يمكن أن تأخذ هذه الطريقة أيضًا في الاعتبار القرب الجغرافي للتصحيحات المحتملة من موقع معين لتحسين الاقتراحات التي يتم إرجاعها.
إذا كان لديك حساب يدعم VoiceAPI، فيمكنك أيضًا الاتصال autosuggest باستخدام البيانات الصوتية للتعرف على الصوت. لكي ينجح هذا، يجب عليك إضافة خطة Voice API إلى حسابك. يوجد مثال بسيط على ذلك أدناه، ولكن يمكن العثور على معلومات مفصلة هنا
لن تتلقى النتائج إلا إذا كانت سلسلة العنوان الجزئية المكونة من 3 كلمات التي ترسلها تحتوي على أول كلمتين والحرف الأول من الكلمة الثالثة على الأقل؛ وإلا سيتم إرجاع رسالة خطأ.
للتحقق مما إذا كانت سلسلة العنوان الخاصة بك تتوافق مع التنسيق المطلوب، فإننا نقدم وظيفة بسيطة تسمى isPossible3wa . تستخدم هذه الوظيفة التعبير العادي الخاص بنا لتحديد العناوين المحتملة المكونة من ثلاث كلمات، مع التأكيد فقط إذا كان الإدخال يتكون من ثلاث كلمات مفصولة بفاصلين عنوان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")
}
أو إذا كنت تفضل ذلك، يمكنك ببساطة استخدام التعبير العادي الخاص بنا. يمكن العثور على رمز المثال في وثائق regex الخاصة بنا.
نحن نقدم سياسات clip متنوعة للسماح لك بالتصفية حسب المنطقة الجغرافية. نوصي باستخدام خيارات القطع لإعطاء مجموعة نتائج أكثر استهدافًا للمستخدم. يمكنك القص حسب البلد أو حسب المربع الجغرافي أو الدائرة أو المضلع. قم بذلك عبر W3WOptions وقم بتمريره إلى مكالمة الاقتراح التلقائي (انظر المثال أدناه).
إذا كنت تعرف الموقع الحالي للمستخدم، فإننا نوصي بشدة أيضًا باستخدام التركيز لعرض النتائج التي من المحتمل أن تكون أكثر صلة بالموضوع. قم بذلك عبر W3WOptions وقم بتمريره إلى مكالمة الاقتراح التلقائي (انظر المثال أدناه)
تم توضيح القيم التي تم إرجاعها من طريقة autosuggest في وثائق عنوان3كلمات 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 ?? " " )
} تسمح واجهة برمجة تطبيقات عنوان3كلمات الصوتية للمستخدم بقول ثلاث كلمات في أي تطبيق أو خدمة، مع عرض قائمة قابلة للتكوين باقتراحات عناوين عنوان3كلمات، كل ذلك من خلال استدعاء واجهة برمجة تطبيقات واحدة.
لكي ينجح هذا، يجب عليك إضافة خطة 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.
تقوم هذه الوظيفة بإرجاع اللغات المدعومة حاليًا لمكالمات autosuggest(text:) المستندة إلى النص. سيُرجع الرمز المكون من حرفين (ISO 639)، واسم اللغة بتلك اللغة وباللغة الإنجليزية.
تم وصف القيم التي تم إرجاعها من طريقة convertTo3wa في وثائق عنوان3كلمات REST API
api . availableLanguages ( ) { ( languages , error ) in
for language in languages ?? [ ] {
print ( language . code , language . name , language . nativeName )
}
} للتعرف على لغات واجهة برمجة التطبيقات الصوتية المتاحة، اتصل بـ api.availableVoiceLanguages(completion:) الذي يعمل بنفس الطريقة تمامًا.
إرجاع قسم من شبكة عنوان 3 م × 3 م لمنطقة معينة. يجب ألا يتجاوز المربع المطلوب 4 كم من زاوية إلى أخرى، وإلا سيتم إرجاع خطأ BadBoundingBoxTooBig. يجب أن تكون خطوط العرض >= -90 و<= 90، ولكن يُسمح لخطوط الطول بالالتفاف حول 180. لتحديد مربع محيط يعبر خط الطول العكسي، استخدم خط طول أكبر من 180. قيمة المثال: 50.0، 179.995، 50.01، 180.0005 .
يتم إرجاع الشبكة كـ [W3WLine]? ويحتوي كل W3WLine على متغير start end ، وكلاهما من النوع CLLocationCoordinate2D .
تم وصف القيم التي تم إرجاعها من وظيفة gridSection في وثائق عنوان3كلمات 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 )
}
} هذه بعض الوظائف التي ستقوم بالبحث أو التحقق من صحة العناوين المكونة من ثلاث كلمات.
تحقق لمعرفة ما إذا كان النص يتبع شكل عنوان مكون من ثلاث كلمات عبر 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" ليس عنوانًا صالحًا من ثلاث كلمات، إلا أنه لا يزال يناسب شكل كلمة واحدة، [كلمة] [فاصل] [كلمة] [فاصل] [كلمة].
التحقق من أن النص عبارة عن عنوان صالح مكون من ثلاث كلمات ويمثل مربعًا على الأرض بنجاح. يؤدي هذا إلى استدعاء واجهة برمجة التطبيقات (API) للتحقق. تعمل وظائف التحقق الأخرى على تشغيل regex محليًا فقط.
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 enum ويقوم استدعاء الاقتراح الصوتي autosuggest بإرجاع تعداد W3WVoiceError .
يوجد أيضًا SDK يعمل دون اتصال بالإنترنت. مزيد من المعلومات متاحة هنا.
يمكن استخدام SDK بالتبادل مع غلاف API هذا. أي أنه يمكنك بدء مشروعك باستخدام غلاف API هذا، ويمكنك لاحقًا الترقية إلى SDK مع الحد الأدنى من التغييرات على التعليمات البرمجية الخاصة بك.
يوجد أدناه جدول يوضح إصدار SDK المتوافق مع إصدار غلاف API:
| w3w-سريع المجمع | نسخة اس دي كيه |
|---|---|
| v3.8.2 وأقل | الإصدار 3.8.0 والإصدارات الأقل |
| الإصدار 3.9.0 والإصدارات الأحدث | الإصدار 4.0.0 والإصدارات الأحدث |
