نظرة عامة

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

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

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

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

ما الذي يمكنك فعله باستخدام واجهة برمجة تطبيقات الأماكن؟

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

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

آلية عمل واجهة برمجة تطبيقات الأماكن

تقبل واجهة برمجة تطبيقات الأماكن الطلبات كعنوان 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.

الموارد

يلخّص الجدول التالي الموارد المتاحة من خلال Maps API مع البيانات التي يعرضها.

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

اطّلِع على تفاصيل حول الردود على البحث في الأماكن والردود على طلبات البحث القريبة والردود النصية على نتائج البحث.

  • JSON
  • XML
تفاصيل المكان لعرض معلومات أكثر تفصيلاً عن مكان محدّد، بما في ذلك مراجعات المستخدمين.

يمكنك الاطّلاع على التفاصيل في الردود على تفاصيل المكان.

  • JSON
  • XML
صور المكان يسمح هذا الإذن بالوصول إلى الملايين من الصور ذات الصلة بالمكان والمخزّنة في قاعدة بيانات الأماكن من Google.

يمكنك الاطّلاع على تفاصيل الردّ من صور الأماكن.

  • JSON
  • XML
الإكمال التلقائي للمكان ملء اسم المكان و/أو عنوانه تلقائيًا أثناء كتابة المستخدمين

يمكنك الاطّلاع على تفاصيل إضافة ردود الإكمال التلقائي.

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

يمكنك الاطّلاع على تفاصيل ردود الإكمال التلقائي لطلب البحث.

  • JSON
  • XML

كيفية استخدام الأماكن

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

مكتبات العملاء المتاحة

يمكنك استدعاء واجهة برمجة التطبيقات هذه باللغة التي تختارها من خلال إحدى مكتبات العملاء التالية:

"برنامج Java" و"برنامج Python" و"برنامج عملاء Go" و"عميل Node.js" في "خرائط Google" هي مكتبات عميلة متاحة بواسطة المنتدى ومفتوحة المصدر بموجب ترخيص Apache 2.0 يُرجى تنزيلها من GitHub حيث يمكنك أيضًا العثور على تعليمات التثبيت ورمز نموذجي.

الخطوات التالية