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

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

مساحة مخصّصة

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

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

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

يمكنك الانتقال إلى 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.