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

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

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

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

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

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

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

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

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

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

الفلاتر

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

فلتر الموقع الجغرافي

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

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

دائرة

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

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

المنطقة

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

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

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

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

منطقة مخصّصة

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

يمكنك الانتقال إلى 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: قائمة بأنواع الأماكن الأساسية المستبعَدة

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

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

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

• 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.