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

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

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

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

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

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

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

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

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

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

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

الفلاتر

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

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

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

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

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

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

دائرة

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

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

المنطقة

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

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

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

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

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

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

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

• establishment: يشير عادةً إلى مكان لم يتم تصنيفه بعد.
• street_number: يشير إلى رقم الشارع الدقيق.
• floor: يشير إلى طابق عنوان المبنى.
• post_box: يشير إلى صندوق بريد محدّد.
• street_address: يشير إلى عنوان شارع دقيق.
• ‫room: يشير إلى غرفة عنوان المبنى.
• intersection: يشير إلى تقاطع رئيسي، عادةً ما يكون بين طريقَين رئيسيتين.
• landmark: يشير إلى مكان قريب يُستخدَم كمرجع للمساعدة في التنقّل.
• ‫subpremise: يشير إلى كيان قابل للعنوان على مستوى أقل من مستوى الموقع، مثل شقة أو وحدة أو جناح.
• sublocality_level_5: المستوى الأكثر دقة من العناصر الدقيقة لعنوان الناحية الفرعية، والتي تمثّل عادةً حيًا صغيرًا جدًا أو تقسيمًا فرعيًا أو منطقة محلية جدًا داخل مدينة.

منطقة مخصّصة

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

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

ملاحظة مهمة: يجب أن تحتوي المناطق المخصّصة على 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 Insights API، اطّلِع على الجدول أ ضمن أنواع الأماكن لواجهة برمجة التطبيقات Places API (جديد). يجب تحديد نوع واحد على الأقل من includedTypes أو includedPrimaryTypes.

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

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

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

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

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

حالة التشغيل

باستخدام الفلتر operatingStatus، يمكنك الفلترة استنادًا إلى حالة التشغيل (مثل مفتوح أو مغلق مؤقتًا). في حال عدم ضبط فلتر operatingStatus، لن يتم تضمين سوى الأماكن التي تحمل حالة التشغيل OPERATING_STATUS_OPERATIONAL في النتائج.

مستوى السعر

باستخدام الفلتر price_levels، يمكنك الفلترة استنادًا إلى مستوى السعر (مثل مجاني أو متوسط أو باهظ). في حال عدم ضبط الفلتر price_levels، يتم تضمين جميع مستويات الأسعار في النتائج.

فلتر التقييم

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

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

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