مَعلمات الطلب

يصف هذا المستند مَعلمات طلب Places Aggregate API ويتضمّن إحصاءات وأفضل الممارسات لاستخدام هذه الخدمة.

تتيح لك واجهة Places Aggregate API تنفيذ عدة وظائف رئيسية:

• احتساب عدد الأماكن: يمكنك تحديد عدد الأماكن التي تتطابق مع معايير معيّنة، مثل نوع الموقع الجغرافي وحالة العمل ومستوى السعر والتقييمات.
• استرداد تفاصيل الأماكن: يمكنك الحصول على أسماء الأماكن التي تستوفي الفلاتر المحدّدة، ثم جلب معلومات أكثر تفصيلاً باستخدام Places API.
• الفلترة المرنة: يمكنك تطبيق فلاتر شاملة للحصول على بيانات مجمّعة دقيقة. تشمل الفلاتر المتاحة ما يلي:
  • المنطقة الجغرافية (دائرة أو منطقة أو مضلّع مخصّص)
  • أنواع الأماكن
  • حالة العمل
  • مستويات الأسعار
  • نطاقات التقييم

المعلمات المطلوبة

يتناول هذا القسم المَعلمات المطلوبة عند إرسال طلب إلى Places Aggregate API. يجب أن يوفّر كل طلب ما يلي:

• نوع الإحصاءات
• فلتر الموقع الجغرافي وفلتر النوع

نوع الإحصاءات

تحدّد نوع الإحصاءات التي تريد احتسابها. تتوفّر أنواع الإحصاءات التالية:

• ‫INSIGHT_COUNT: تعرض هذه السمة عدد الأماكن التي تطابق معايير الفلتر.
• ‫INSIGHT_PLACES: تعرض أرقام تعريف الأماكن التي تطابق معايير الفلتر.

ملاحظة: إذا اخترت INSIGHT_PLACES، ستعرض واجهة Places Aggregate API أرقام تعريف الأماكن فقط إذا كانت قيمة count تساوي 100 أو أقل.

الفلاتر

تحدّد معايير فلترة الأماكن. يجب تحديد LocationFilter وTypeFilter كحدّ أدنى.

تصفية المواقع

يمكن أن يكون فلتر الموقع الجغرافي من أحد الأنواع التالية:

• ‫circle: تحدّد هذه السمة منطقة على شكل دائرة لها مركز ونصف قطر.
• ‫region: تحدّد مساحة كمنطقة.
• ‫customArea: تحدّد هذه السمة منطقة معيّنة كمضلّع مخصّص.

ملاحظة مهمة: يجب أن تكون مساحة أي فلتر للموقع الجغرافي بين 1556.86 متر مربع (حجم كتلة سكنية صغيرة تقريبًا) و2 تريليون متر مربع (حجم ألاسكا تقريبًا). ستؤدي الطلبات التي تتضمّن مناطق خارج هذا النطاق إلى ظهور الخطأ INVALID_ARGUMENT.

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

دائرة

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

• center:
  • ‫latLng: خط العرض وخط الطول لمركز الدائرة يجب أن تكون خطوط العرض رقمًا بين -90 و90، شاملة. يجب أن يكون خط الطول رقمًا يتراوح بين -180 و180، بما في ذلك هذين الرقمين.
  • ‫place: رقم تعريف المكان لمركز الدائرة يُرجى العِلم أنّه يمكن استخدام الأماكن المحدّدة بنقاط فقط. يجب أن تبدأ هذه السلسلة بالبادئة places/.
• ‫radius: نصف قطر الدائرة بالأمتار يجب أن يكون هذا الرقم موجبًا.

المنطقة

حدِّد منطقتك كمنطقة من خلال تمرير رقم تعريف المكان إلى المَعلمة place. يمثّل رقم تعريف المكان منطقة جغرافية (مثل منطقة يمكن تمثيلها بمضلّع). على سبيل المثال، رقم تعريف المكان لمدينة تامبا في فلوريدا هو places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. يُرجى العِلم أنّ بعض أرقام تعريف الأماكن لا تتضمّن شكلاً هندسيًا محدّدًا، وفي هذه الحالات، تعرض واجهة برمجة التطبيقات Places Aggregate API رمز الخطأ 400 مع رسالة تشير إلى أنّ المنطقة غير متاحة. بالإضافة إلى ذلك، بالنسبة إلى المناطق الجغرافية المعقدة، قد تؤدي تحسينات المعالجة الداخلية إلى تقريب زائد قليلاً للمنطقة (يصل إلى %2-3) التي تمثل المنطقة.

ملاحظة مهمة: عند استخدام الفلتر region مع نوع الإحصاءات INSIGHT_PLACES، يتم تلقائيًا رفض الطلبات التي تتضمّن مناطق متنازع عليها لضمان دقة خدمات Google وحياديتها. المناطق المتنازع عليها هي مناطق ذات حدود متعارضة أو مطالبات إقليمية من بلدان أو كيانات مختلفة. تُعرض الحدود المتنازع عليها بخط رمادي متقطّع على "خرائط Google".

لمزيد من المعلومات حول كيفية تحديد المناطق المتنازع عليها، يُرجى الاطّلاع على مقالة فهم الحدود الجغرافية للبلدان وأسمائها.

ملاحظة مهمة: لا تتيح Google بعض أرقام تعريف الأماكن التي تنتمي إلى أنواع المناطق التالية:

• أنواع المناطق الكبيرة جدًا التي تؤدي إلى وقت استجابة طويل
• أنواع المناطق الصغيرة جدًا لدرجة أنّها تخلّ بالامتثال للخصوصية

لتحديد ما إذا كان رقم تعريف المكان يمثّل نوع مكان غير متوافق، عليك تمرير رقم تعريف المكان في طلب Geocoding API. تتضمّن الاستجابة مصفوفة type التي تسرد أنواع الأماكن المرتبطة برقم تعريف المكان، مثل locality أو neighborhood أو country. سيتم رفض مكان ما في فلترة المناطق إذا تطابق أي من أنواعه مع هذه القائمة.

تشمل أنواع الأماكن غير المتوافقة ما يلي:

• ‫establishment: يشير عادةً إلى مكان لم يتم تصنيفه بعد.
• ‫intersection: يشير إلى تقاطع رئيسي، عادةً بين طريقَين رئيسيَين.
• ‫subpremise: تشير إلى كيان يمكن الوصول إليه تحت مستوى المبنى، مثل شقة أو وحدة أو جناح.

ملاحظة: قد يتم رفض بعض الأماكن غير المدرَجة أعلاه إذا لم تكن تتضمّن هندسة مضلّعات محدّدة جيدًا. ويحدث ذلك بشكل أكثر شيوعًا مع أنواع مثل neighborhood وlocality وsublocality ومتغيراتها المرقمة (sublocality_level_1 وsublocality_level_2 وsublocality_level_3 وsublocality_level_4). يتم عرض رمز الخطأ 400 في هذه الحالة.

منطقة مخصّصة

تحدّد هذه السمة مساحة مضلّع مخصّص باستخدام إحداثيات خطوط العرض والطول.

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

ملاحظة مهمة: يجب أن تحتوي المناطق المخصّصة على 7, 000 رأس أو أقل.

يمكنك الانتقال إلى https://geojson.io/ لرسم مضلّع مخصّص وإدخال هذه الإحداثيات في الطلب. يجب أن يحتوي المضلّع على 4 إحداثيات على الأقل، بحيث يكون الإحداثيان الأول والأخير متطابقَين. يجب أن تكون 3 على الأقل من الإحداثيات المقدَّمة فريدة.

سيتم التعامل مع الإحداثيات المتطابقة المتتالية كإحداثي واحد. ومع ذلك، ستؤدي الإحداثيات المكرّرة غير المتتالية (بخلاف الإحداثيات الأولى والأخيرة المتطابقة المطلوبة) إلى حدوث خطأ.

بالإضافة إلى ذلك، لا يُسمح بتقاطع الحواف غير المتجاورة، ولا يُسمح بالحواف التي يبلغ طولها 180 درجة (أي لا يمكن أن تكون الرؤوس المتجاورة متقابلة).

على سبيل المثال:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

فلتر النوع

تحدّد أنواع الأماكن التي يجب تضمينها أو استبعادها. للاطّلاع على قائمة بجميع أنواع الأماكن الأساسية والثانوية التي تتيحها Places Aggregate API، يُرجى مراجعة الجدول (أ) ضمن أنواع الأماكن في Places API (الإصدار الجديد). يجب تحديد نوع واحد على الأقل من includedTypes أو includedPrimaryTypes.

• ‫includedTypes: قائمة بأنواع الأماكن المضمّنة
• ‫excludedTypes: قائمة بأنواع الأماكن المستبعَدة
• ‫includedPrimaryTypes: قائمة بأنواع الأماكن الأساسية المضمّنة
• ‫excludedPrimaryTypes: قائمة بأنواع الأماكن الأساسية المُستبعَدة.

لمزيد من المعلومات حول كيفية عمل فلاتر الأنواع وأنواع الأماكن، يمكنك الاطّلاع على مزيد من المعلومات حول فلاتر الأنواع.

ملاحظة: تتضمّن فلاتر الأنواع تلقائيًا الأنواع الفرعية للأنواع المحدّدة. على سبيل المثال، إذا فلترت النتائج حسب gym، ستتضمّن النتائج أيضًا الأماكن المصنّفة ضمن أنواعها الفرعية، مثل yoga_studio.

المعلمات الاختيارية

هذه الفلاتر اختيارية:

• ‫operatingStatus: تحدّد حالات الأماكن التي يجب تضمينها أو استبعادها. يتم تلقائيًا الفلترة حسب operatingStatus: OPERATING_STATUS_OPERATIONAL (قيمة واحدة محدّدة).
• ‫priceLevels: تحدّد مستويات أسعار الأماكن التي يجب تضمينها. لا يتم تطبيق أي فلترة لمستوى السعر تلقائيًا، ويتم عرض جميع الأماكن (بما في ذلك الأماكن التي لا تتضمّن معلومات عن مستوى السعر).
• ‫ratingFilter: تحدّد نطاق تقييم الأماكن. الإعداد التلقائي هو عدم الفلترة (يتم تضمين جميع التقييمات في النتائج).

حالة العمل

باستخدام فلتر "operatingStatus"، يمكنك الفلترة استنادًا إلى حالة التشغيل، مثل "OPERATIONAL" أو "TEMPORARILY_CLOSED". يعمل فلتر operatingStatus على النحو التالي:

• إذا لم يتم توفير أي فلاتر، سيتم تضمين الأماكن التي تكون حالة تشغيلها OPERATING_STATUS_OPERATIONAL فقط في النتائج.
• في حال توفير فلتر واحد أو أكثر، يجب تحديد قيم صالحة لحالة التشغيل (OPERATING_STATUS_OPERATIONAL أو OPERATING_STATUS_PERMANENTLY_CLOSED أو OPERATING_STATUS_TEMPORARILY_CLOSED).

مستوى السعر

باستخدام فلتر priceLevels، يمكنك فلترة الأماكن استنادًا إلى مستوى السعر. القيم الصالحة لمستوى السعر هي: PRICE_LEVEL_FREE وPRICE_LEVEL_INEXPENSIVE وPRICE_LEVEL_MODERATE وPRICE_LEVEL_EXPENSIVE وPRICE_LEVEL_VERY_EXPENSIVE.

في ما يلي سلوك فلتر priceLevels:

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

فلتر التقييم

لفلترة الأماكن استنادًا إلى متوسط تقييمات المستخدمين كلا الحقلَين اختياريان، لذا إذا تم حذفهما، سيتم تلقائيًا تضمين الأماكن التي ليس لها تقييم.

• minRating: الحدّ الأدنى لمتوسط تقييم المستخدمين (بين 1.0 و5.0)
• ‫maxRating: الحد الأقصى لمتوسط تقييم المستخدمين (بين 1.0 و5.0)

بالإضافة إلى ذلك، يجب أن تكون قيمة minRating دائمًا أقل من أو تساوي قيمة maxRating. إذا تم تحديد قيمة minRating أكبر من maxRating، سيظهر خطأ INVALID_ARGUMENT.