مميزات استخدام Places API
إنشاء ميزات تدرك الموقع لإتاحة بيانات الموقع التفصيلية بسهولة للمستخدمين. تستند البيانات المتاحة من خلال Places API إلى أحد نماذج الأماكن الأكثر دقة وحداثة وشمولية. في ما يلي أمثلة على حالات الاستخدام الخاصة بالتطبيقات:
- اعرض وحدات سكنية للاستئجار في المناطق الحضرية الكبرى مع نتائج تستهدف المدن على وجه التحديد.
- أدرِج تفاصيل المكان في تعديل حالة استلام الطلب أو التوصيل.
- يمكنك عرض قائمة بالمنتزهات في منطقة ما إلى جانب صور ومراجعات أرسلها المستخدمون.
- قدِّم للأشخاص الذين يخطّطون للرحلات معلومات الاتصال والمراجعات ومستويات الأسعار للمنشآت أثناء التنقّل.
الإجراءات التي يمكنك اتّخاذها باستخدام Places API
يمكنك استخدام Places API لتضمين الميزات التالية في تطبيقاتك:
- قدِّم نتائج بحث عن الأماكن من أنواع مختلفة من طلبات بحث المستخدمين، مثل إدخال النص والمواقع الجغرافية المجاورة وطلبات البحث الغامضة أو الفئوية للمستخدمين.
- يمكنك تفعيل ميزات الإكمال التلقائي لأنواع مختلفة من عمليات البحث، إمّا لطلبات بحث نصية محدّدة أو طلبات بحث فئوية.
- تحسين نوع التفاصيل التي يتم عرضها عن مكان معيّن، مثل ساعات العمل والملخّص ومراجعات المستخدمين وصورة
- أضِف صورًا عالية الجودة إلى المواقع الجغرافية التي يعرضها تطبيقك.
يتيح العديد من واجهات برمجة التطبيقات في "منصة خرائط Google" استخدام أرقام تعريف الأماكن، حيث يحدّد رقم تعريف المكان مكانًا بشكل فريد في قاعدة بيانات "أماكن Google" وعلى "خرائط Google". هناك العديد من الطرق للحصول على رقم تعريف المكان، بما في ذلك من Places API، ولكن أيضًا من Geocoding API وRoutes API وAddress Validation API.
بعد حصولك على معرّف المكان، يمكنك استخدام Places API لطلب المزيد من التفاصيل حول منشأة معيّنة أو نقطة اهتمام معيّنة، مثل عنوانها الكامل ورقم هاتفها وتقييم المستخدم الخاص بها وتعليقاتها.
اختيار الإصدار الذي تستخدمه من Places API
تدعم Places API إصدارين من واجهات برمجة التطبيقات: هما: Places API عبارة عن واجهات برمجة التطبيقات الحالية، وPlaces API (جديدة) هي إصدارات الجيل التالي من واجهات برمجة التطبيقات.
مع إصدار Places API (جديدة)، تتمثل مهمتك الأولى في تحديد مجموعة واجهات برمجة التطبيقات التي تريد استخدامها. ينطبق ذلك إذا كنت عميلاً جديدًا أو عميلاً حاليًا تستخدم واجهات برمجة التطبيقات. يمكنك الاستعانة بهذا الدليل للتعرّف على الاختلافات الرئيسية بين واجهتَي برمجة التطبيقات.
آلية عمل Places API
Places API (جديدة)
تقبل واجهة Places API (الجديدة) الطلبات على أنّها عنوان URL عادي مع نقطة نهاية خدمة معيّنة، مثل /places أو places:searchText، وتعرض استجابة JSON. تتيح واجهة Places API (الجديدة) إمكانية المصادقة من خلال مفتاح واجهة برمجة التطبيقات ورمز OAuth المميز.
يقدّم المثال التالي طلب "تفاصيل المكان" لعرض مكوّنات العنوان لرقم تعريف المكان باستخدام مفتاح واجهة برمجة التطبيقات:
https://places.googleapis.com/v1/places/GyuEmsRBfy61i59si0?fields=addressComponents &key=YOUR_API_KEY
واجهة برمجة تطبيقات الأماكن
تقبل Places API الطلبات على أنّها عنوان URL عادي تتضمَّن نقطة نهاية خدمة محدّدة، مثل /place أو /photo. وتقبل نقاط النهاية أيضًا نوع التنسيق المحدّد في الطلب، إما JSON أو XML. يستخدم طلب الخدمة معلَمات ذات صلة بنقطة النهاية المحدّدة لتحسين البيانات التي يتم عرضها.
يقدّم المثال التالي طلب "تفاصيل المكان" لعرض مكوّنات العنوان لرقم تعريف المكان بتنسيق JSON:
https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0 &fields=address_components &key=YOUR_API_KEY
في هذه الحالة، تستخدم الخدمة معرّف المكان المقدَّم للعثور على المكان المطلوب وعرض مكوّنات العنوان بتنسيق JSON.
المراجع
يلخص الجدول التالي الموارد المتاحة من خلال واجهة برمجة تطبيقات الأماكن.
| واجهة برمجة تطبيقات الأماكن | Places API (جديدة) | ملاحظة |
|---|---|---|
| البحث عن مكان | البحث النصي (جديد) | لا يوجد إصدار جديد من "البحث عن مكان". وقد تم استبداله باستخدام البحث النصي (جديد). |
| البحث عن الأجهزة المجاورة | البحث عن الأجهزة المجاورة (جديد) | في جميع الطلبات التي تستخدم واجهة برمجة التطبيقات الحالية والتي تتضمّن طلب بحث نصي، يجب استخدام البحث النصي (جديد) لأنّ ميزة "البحث عن قرب" (جديد) لا تتيح إدخال النص. |
| البحث النصي | البحث النصي (جديد) | |
| تفاصيل المكان | تفاصيل المكان (جديد) | |
| صورة المكان | صورة المكان (جديدة) | |
| الإكمال التلقائي للأماكن | الإكمال التلقائي (جديد) | |
| الإكمال التلقائي لطلبات البحث | الإكمال التلقائي (جديد) | الإمكانات المُضافة إلى الإكمال التلقائي (جديدة) |
كيفية استخدام Places API
تتناول الخطوات التالية سيناريو نموذجي لحالة استخدام لاستخدام خدمة Places API. أثناء إنشاء الحل، يمكنك استخدام نقاط نهاية إضافية، مثل "البحث عن مكان قريب" و"صور الأماكن".| 1 | البدء | ابدأ بالاطّلاع على إعداد مشروعك على Google Cloud وأكمِل تعليمات الإعداد التالية، ثم تعرَّف على كيفية استخدام مفتاح واجهة برمجة التطبيقات. بالنسبة إلى Places API (الجديدة)، يمكنك أيضًا استخدام رموز OAuth المميزة. |
| 2 | جرِّب البحث النصي الأساسي | أجرِ بحثًا نصيًا بسيطًا باستخدام البحث النصي (جديد) أو البحث النصي. |
| 3 | استخدام رقم تعريف المكان للحصول على مزيد من التفاصيل | وتعرِض العديد من واجهات برمجة التطبيقات في "منصة خرائط Google" رقم تعريف مكان كجزء من الردّ. استخدِم معرّف المكان للحصول على تفاصيل حول مكان معيّن. اطّلِع على تفاصيل المكان (جديد) وتفاصيل المكان. |
| 4 | الحصول على صورة لمكان معيّن | تتيح لك خدمة "صور المكان" الوصول إلى ملايين الصور المخزنة في قاعدة بيانات "الأماكن". استخدِم صورة المكان (جديدة) أو تفاصيل المكان للوصول إلى صور المكان. |