نظرة عامة

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

مزايا استخدام واجهة برمجة تطبيقات الأماكن

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

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

كيفية الاستفادة من Places API

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

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

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

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