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

يوضّح هذا المستند مَعلمات الطلب الخاصة بواجهة 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.