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

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

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

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

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

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

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

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

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

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

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

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

الفلاتر

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

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

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

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

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

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

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

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

أنواع المناطق غير المتوافقة
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark 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 Insights API، اطّلِع على الجدول أ ضمن أنواع الأماكن لواجهة برمجة التطبيقات Places API (جديد). يجب تحديد نوع واحد على الأقل من includedTypes أو includedPrimaryTypes.

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

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

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

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

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

حالة التشغيل

الفلترة استنادًا إلى حالة التشغيل (مثل قيد التشغيل أو مغلق مؤقتًا)

مستوى السعر

الفلترة استنادًا إلى مستوى السعر (مثل مجاني أو متوسط أو باهظ)

فلتر التقييم

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

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