مزايا استخدام 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
تتناول الخطوات التالية سيناريو حالة استخدام نموذجيًا لاستخدام خدمة Places API. أثناء إنشاء حلّك، يمكنك استخدام نقاط نهاية إضافية، مثل "البحث عن الأماكن القريبة" و"صور الأماكن".| 1 | الإعداد | ابدأ بـ إعداد مشروعك على Google Cloud وأكمِل تعليمات الإعداد التي تليها، ثم تعرَّف على كيفية استخدام مفتاح واجهة برمجة التطبيقات. بالنسبة إلى Places API (الإصدار الجديد)، يمكنك أيضًا استخدام رموز OAuth المميزة. |
| 2 | تجربة البحث عن نص أساسي | أجرِ عملية بحث نصي باستخدام البحث النصي (جديد) أو البحث النصي. |
| 3 | استخدام رقم تعريف المكان للحصول على مزيد من التفاصيل | تعرض العديد من واجهات برمجة تطبيقات "منصّة خرائط Google" معرّف مكان كجزء من الاستجابة. استخدِم رقم تعريف المكان للحصول على تفاصيل عن مكان معيّن. اطّلِع على تفاصيل المكان (الإصدار الجديد) وتفاصيل المكان. |
| 4 | الحصول على صورة لمكان | تتيح لك خدمة "صور الأماكن" الوصول إلى ملايين الصور المخزّنة في قاعدة بيانات "الأماكن" . استخدِم صورة المكان (جديد) أو تفاصيل المكان للوصول إلى صور مكان معيّن. |