نظرة عامة

اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب
واجهة Places API هي خدمة تقبل طلبات HTTP لبيانات الموقع من خلال عدة طرق. فهي تعرض بيانات موقع منسقة وصورًا حول المنشآت أو المواقع الجغرافية أو نقاط الاهتمام البارزة.

أسباب استخدام Places API

يمكنك إنشاء ميزات معرَّفة للموقع الجغرافي لإتاحة بيانات الموقع الجغرافي التفصيلية للمستخدمين بسهولة. تستند البيانات المتوفرة من خلال Places API إلى أحد أكثر نماذج الأماكن دقة وحداثة وشمولية في العالم الحقيقي. في ما يلي أمثلة على حالات استخدام التطبيقات:

  • عرض أماكن للاستئجار في المناطق الحضرية الكبرى مع نتائج تستهدف المدن تحديدًا.
  • أدرِج تفاصيل المكان في تعديل على حالة استلام الطلب أو التسليم.
  • عرض قائمة بالحدائق في إحدى المناطق جنبًا إلى جنب مع الصور والمراجعات التي يرسلها المستخدمون.
  • تزويد الأشخاص الذين يخطّطون للرحلات بمعلومات الاتصال والمراجعات ومستويات الأسعار للمنشآت على طول الطريق.

الإجراءات التي يمكن تنفيذها باستخدام Places API

يمكنك استخدام Places API لتضمين الميزات التالية في تطبيقاتك:

  • قدّم نتائج بحث عن الأماكن من أنواع مختلفة من طلبات البحث التي يُدخلها المستخدمون، مثل إدخال النص، والمواقع الجغرافية القريبة، وطلبات البحث الغامضة أو الفئوية التي يُدخلها المستخدمون.
  • يمكنك تفعيل ميزات الإكمال التلقائي لأنواع بحث مختلفة، إمّا طلبات بحث نصية محدّدة أو طلبات بحث فئوية.
  • حسِّن نوع التفاصيل التي يتم عرضها حول مكان ما، مثل ساعات العمل وملخّص ومراجعات المستخدمين وصورة.
  • أضِف صورًا عالية الجودة إلى المواقع الجغرافية التي يعرضها تطبيقك.

تتوافق العديد من واجهات برمجة تطبيقات "منصة خرائط Google" مع معرّفات الأماكن، حيث يحدّد رقم تعريف المكان بشكل فريد مكانًا في قاعدة بيانات "أماكن Google" وعلى "خرائط Google". هناك العديد من الطرق للحصول على معرّف مكان، بما في ذلك من Places API، ولكن أيضًا من Geocoding API وRoutes API وAddress Verification 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 الحصول على صورة لأحد الأماكن تتيح لك خدمة "صور المكان" الوصول إلى ملايين الصور المخزّنة في قاعدة بيانات "الأماكن". استخدِم صورة المكان (جديدة) أو تفاصيل المكان للوصول إلى صور المكان.